blob: 9ac898517539c25938c2fd9814d2652ebee07b3c [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 Tarreau2e077f82019-11-25 20:36:16 +01005 version 2.2
Willy Tarreau6a06a402007-07-15 20:15:28 +02006 willy tarreau
Willy Tarreaue54b43a2019-11-25 19:47:40 +01007 2019/11/25
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
Julien Pivotto6ccee412019-11-27 15:49:54 +0100676. Cache
686.1. Limitation
696.2. Setup
706.2.1. Cache section
716.2.2. Proxy section
72
Willy Tarreau74ca5042013-06-11 23:12:07 +0200737. Using ACLs and fetching samples
747.1. ACL basics
757.1.1. Matching booleans
767.1.2. Matching integers
777.1.3. Matching strings
787.1.4. Matching regular expressions (regexes)
797.1.5. Matching arbitrary data blocks
807.1.6. Matching IPv4 and IPv6 addresses
817.2. Using ACLs to form conditions
827.3. Fetching samples
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200837.3.1. Converters
847.3.2. Fetching samples from internal states
857.3.3. Fetching samples at Layer 4
867.3.4. Fetching samples at Layer 5
877.3.5. Fetching samples from buffer contents (Layer 6)
887.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +0200897.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020090
918. Logging
928.1. Log levels
938.2. Log formats
948.2.1. Default log format
958.2.2. TCP log format
968.2.3. HTTP log format
William Lallemand48940402012-01-30 16:47:22 +0100978.2.4. Custom log format
Willy Tarreau5f51e1a2012-12-03 18:40:10 +0100988.2.5. Error log format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200998.3. Advanced logging options
1008.3.1. Disabling logging of external tests
1018.3.2. Logging before waiting for the session to terminate
1028.3.3. Raising log level upon errors
1038.3.4. Disabling logging of successful connections
1048.4. Timing events
1058.5. Session state at disconnection
1068.6. Non-printable characters
1078.7. Capturing HTTP cookies
1088.8. Capturing HTTP headers
1098.9. Examples of logs
110
Christopher Fauletc3fe5332016-04-07 15:30:10 +02001119. Supported filters
1129.1. Trace
1139.2. HTTP compression
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001149.3. Stream Processing Offload Engine (SPOE)
Christopher Faulet99a17a22018-12-11 09:18:27 +01001159.4. Cache
Christopher Fauletb30b3102019-09-12 23:03:09 +02001169.5. fcgi-app
Christopher Fauletc3fe5332016-04-07 15:30:10 +0200117
Christopher Fauletb30b3102019-09-12 23:03:09 +020011810. FastCGI applications
11910.1. Setup
12010.1.1. Fcgi-app section
12110.1.2. Proxy section
12210.1.3. Example
12310.2. Default parameters
12410.3. Limitations
125
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200126
1271. Quick reminder about HTTP
128----------------------------
129
Davor Ocelice9ed2812017-12-25 17:49:28 +0100130When HAProxy is running in HTTP mode, both the request and the response are
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200131fully analyzed and indexed, thus it becomes possible to build matching criteria
132on almost anything found in the contents.
133
134However, it is important to understand how HTTP requests and responses are
135formed, and how HAProxy decomposes them. It will then become easier to write
136correct rules and to debug existing configurations.
137
138
1391.1. The HTTP transaction model
140-------------------------------
141
142The HTTP protocol is transaction-driven. This means that each request will lead
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100143to one and only one response. Traditionally, a TCP connection is established
Davor Ocelice9ed2812017-12-25 17:49:28 +0100144from the client to the server, a request is sent by the client through the
145connection, the server responds, and the connection is closed. A new request
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200146will involve a new connection :
147
148 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
149
150In this mode, called the "HTTP close" mode, there are as many connection
151establishments as there are HTTP transactions. Since the connection is closed
152by the server after the response, the client does not need to know the content
153length.
154
155Due to the transactional nature of the protocol, it was possible to improve it
156to avoid closing a connection between two subsequent transactions. In this mode
157however, it is mandatory that the server indicates the content length for each
158response so that the client does not wait indefinitely. For this, a special
159header is used: "Content-length". This mode is called the "keep-alive" mode :
160
161 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
162
163Its advantages are a reduced latency between transactions, and less processing
164power required on the server side. It is generally better than the close mode,
165but not always because the clients often limit their concurrent connections to
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200166a smaller value.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200167
Willy Tarreau95c4e142017-11-26 12:18:55 +0100168Another improvement in the communications is the pipelining mode. It still uses
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200169keep-alive, but the client does not wait for the first response to send the
170second request. This is useful for fetching large number of images composing a
171page :
172
173 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
174
175This can obviously have a tremendous benefit on performance because the network
176latency is eliminated between subsequent requests. Many HTTP agents do not
177correctly support pipelining since there is no way to associate a response with
178the corresponding request in HTTP. For this reason, it is mandatory for the
Cyril Bonté78caf842010-03-10 22:41:43 +0100179server to reply in the exact same order as the requests were received.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200180
Willy Tarreau95c4e142017-11-26 12:18:55 +0100181The next improvement is the multiplexed mode, as implemented in HTTP/2. This
182time, each transaction is assigned a single stream identifier, and all streams
183are multiplexed over an existing connection. Many requests can be sent in
184parallel by the client, and responses can arrive in any order since they also
185carry the stream identifier.
186
Willy Tarreau70dffda2014-01-30 03:07:23 +0100187By default HAProxy operates in keep-alive mode with regards to persistent
188connections: for each connection it processes each request and response, and
189leaves the connection idle on both sides between the end of a response and the
Willy Tarreau95c4e142017-11-26 12:18:55 +0100190start of a new request. When it receives HTTP/2 connections from a client, it
191processes all the requests in parallel and leaves the connection idling,
192waiting for new requests, just as if it was a keep-alive HTTP connection.
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200193
Christopher Faulet315b39c2018-09-21 16:26:19 +0200194HAProxy supports 4 connection modes :
Willy Tarreau70dffda2014-01-30 03:07:23 +0100195 - keep alive : all requests and responses are processed (default)
196 - tunnel : only the first request and response are processed,
Christopher Faulet6c9bbb22019-03-26 21:37:23 +0100197 everything else is forwarded with no analysis (deprecated).
Willy Tarreau70dffda2014-01-30 03:07:23 +0100198 - server close : the server-facing connection is closed after the response.
Christopher Faulet315b39c2018-09-21 16:26:19 +0200199 - close : the connection is actively closed after end of response.
Willy Tarreau70dffda2014-01-30 03:07:23 +0100200
Davor Ocelice9ed2812017-12-25 17:49:28 +0100201For HTTP/2, the connection mode resembles more the "server close" mode : given
202the independence of all streams, there is currently no place to hook the idle
Willy Tarreau95c4e142017-11-26 12:18:55 +0100203server connection after a response, so it is closed after the response. HTTP/2
204is only supported for incoming connections, not on connections going to
205servers.
206
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200207
2081.2. HTTP request
209-----------------
210
211First, let's consider this HTTP request :
212
213 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100214 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200215 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
216 2 Host: www.mydomain.com
217 3 User-agent: my small browser
218 4 Accept: image/jpeg, image/gif
219 5 Accept: image/png
220
221
2221.2.1. The Request line
223-----------------------
224
225Line 1 is the "request line". It is always composed of 3 fields :
226
227 - a METHOD : GET
228 - a URI : /serv/login.php?lang=en&profile=2
229 - a version tag : HTTP/1.1
230
231All of them are delimited by what the standard calls LWS (linear white spaces),
232which are commonly spaces, but can also be tabs or line feeds/carriage returns
233followed by spaces/tabs. The method itself cannot contain any colon (':') and
234is limited to alphabetic letters. All those various combinations make it
235desirable that HAProxy performs the splitting itself rather than leaving it to
236the user to write a complex or inaccurate regular expression.
237
238The URI itself can have several forms :
239
240 - A "relative URI" :
241
242 /serv/login.php?lang=en&profile=2
243
244 It is a complete URL without the host part. This is generally what is
245 received by servers, reverse proxies and transparent proxies.
246
247 - An "absolute URI", also called a "URL" :
248
249 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
250
251 It is composed of a "scheme" (the protocol name followed by '://'), a host
252 name or address, optionally a colon (':') followed by a port number, then
253 a relative URI beginning at the first slash ('/') after the address part.
254 This is generally what proxies receive, but a server supporting HTTP/1.1
255 must accept this form too.
256
257 - a star ('*') : this form is only accepted in association with the OPTIONS
258 method and is not relayable. It is used to inquiry a next hop's
259 capabilities.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100260
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200261 - an address:port combination : 192.168.0.12:80
262 This is used with the CONNECT method, which is used to establish TCP
263 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
264 other protocols too.
265
266In a relative URI, two sub-parts are identified. The part before the question
267mark is called the "path". It is typically the relative path to static objects
268on the server. The part after the question mark is called the "query string".
269It is mostly used with GET requests sent to dynamic scripts and is very
270specific to the language, framework or application in use.
271
Willy Tarreau95c4e142017-11-26 12:18:55 +0100272HTTP/2 doesn't convey a version information with the request, so the version is
Davor Ocelice9ed2812017-12-25 17:49:28 +0100273assumed to be the same as the one of the underlying protocol (i.e. "HTTP/2").
Willy Tarreau95c4e142017-11-26 12:18:55 +0100274However, haproxy natively processes HTTP/1.x requests and headers, so requests
275received over an HTTP/2 connection are transcoded to HTTP/1.1 before being
276processed. This explains why they still appear as "HTTP/1.1" in haproxy's logs
277as well as in server logs.
278
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200279
2801.2.2. The request headers
281--------------------------
282
283The headers start at the second line. They are composed of a name at the
284beginning of the line, immediately followed by a colon (':'). Traditionally,
285an LWS is added after the colon but that's not required. Then come the values.
286Multiple identical headers may be folded into one single line, delimiting the
287values with commas, provided that their order is respected. This is commonly
288encountered in the "Cookie:" field. A header may span over multiple lines if
289the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
290define a total of 3 values for the "Accept:" header.
291
Davor Ocelice9ed2812017-12-25 17:49:28 +0100292Contrary to a common misconception, header names are not case-sensitive, and
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200293their values are not either if they refer to other header names (such as the
Willy Tarreau95c4e142017-11-26 12:18:55 +0100294"Connection:" header). In HTTP/2, header names are always sent in lower case,
295as can be seen when running in debug mode.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200296
297The end of the headers is indicated by the first empty line. People often say
298that it's a double line feed, which is not exact, even if a double line feed
299is one valid form of empty line.
300
301Fortunately, HAProxy takes care of all these complex combinations when indexing
302headers, checking values and counting them, so there is no reason to worry
303about the way they could be written, but it is important not to accuse an
304application of being buggy if it does unusual, valid things.
305
306Important note:
Lukas Tribus23953682017-04-28 13:24:30 +0000307 As suggested by RFC7231, HAProxy normalizes headers by replacing line breaks
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200308 in the middle of headers by LWS in order to join multi-line headers. This
309 is necessary for proper analysis and helps less capable HTTP parsers to work
310 correctly and not to be fooled by such complex constructs.
311
312
3131.3. HTTP response
314------------------
315
316An HTTP response looks very much like an HTTP request. Both are called HTTP
317messages. Let's consider this HTTP response :
318
319 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100320 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200321 1 HTTP/1.1 200 OK
322 2 Content-length: 350
323 3 Content-Type: text/html
324
Willy Tarreau816b9792009-09-15 21:25:21 +0200325As a special case, HTTP supports so called "Informational responses" as status
326codes 1xx. These messages are special in that they don't convey any part of the
327response, they're just used as sort of a signaling message to ask a client to
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100328continue to post its request for instance. In the case of a status 100 response
329the requested information will be carried by the next non-100 response message
330following the informational one. This implies that multiple responses may be
331sent to a single request, and that this only works when keep-alive is enabled
332(1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to
333correctly forward and skip them, and only process the next non-100 response. As
334such, these messages are neither logged nor transformed, unless explicitly
335state otherwise. Status 101 messages indicate that the protocol is changing
336over the same connection and that haproxy must switch to tunnel mode, just as
337if a CONNECT had occurred. Then the Upgrade header would contain additional
338information about the type of protocol the connection is switching to.
Willy Tarreau816b9792009-09-15 21:25:21 +0200339
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200340
Davor Ocelice9ed2812017-12-25 17:49:28 +01003411.3.1. The response line
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200342------------------------
343
344Line 1 is the "response line". It is always composed of 3 fields :
345
346 - a version tag : HTTP/1.1
347 - a status code : 200
348 - a reason : OK
349
350The status code is always 3-digit. The first digit indicates a general status :
Davor Ocelice9ed2812017-12-25 17:49:28 +0100351 - 1xx = informational message to be skipped (e.g. 100, 101)
352 - 2xx = OK, content is following (e.g. 200, 206)
353 - 3xx = OK, no content following (e.g. 302, 304)
354 - 4xx = error caused by the client (e.g. 401, 403, 404)
355 - 5xx = error caused by the server (e.g. 500, 502, 503)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200356
Lukas Tribus23953682017-04-28 13:24:30 +0000357Please refer to RFC7231 for the detailed meaning of all such codes. The
Willy Tarreaud72758d2010-01-12 10:42:19 +0100358"reason" field is just a hint, but is not parsed by clients. Anything can be
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200359found there, but it's a common practice to respect the well-established
360messages. It can be composed of one or multiple words, such as "OK", "Found",
361or "Authentication Required".
362
Davor Ocelice9ed2812017-12-25 17:49:28 +0100363HAProxy may emit the following status codes by itself :
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200364
365 Code When / reason
366 200 access to stats page, and when replying to monitoring requests
367 301 when performing a redirection, depending on the configured code
368 302 when performing a redirection, depending on the configured code
369 303 when performing a redirection, depending on the configured code
Willy Tarreaub67fdc42013-03-29 19:28:11 +0100370 307 when performing a redirection, depending on the configured code
371 308 when performing a redirection, depending on the configured code
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200372 400 for an invalid or too large request
373 401 when an authentication is required to perform the action (when
374 accessing the stats page)
Christopher Faulet87f1f3d2019-07-18 14:51:20 +0200375 403 when a request is forbidden by a "http-request deny" rule
Florian Tham9205fea2020-01-08 13:35:30 +0100376 404 when the requested resource could not be found
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200377 408 when the request timeout strikes before the request is complete
Florian Tham272e29b2020-01-08 10:19:05 +0100378 410 when the requested resource is no longer available and will not
379 be available again
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200380 500 when haproxy encounters an unrecoverable internal error, such as a
381 memory allocation failure, which should never happen
382 502 when the server returns an empty, invalid or incomplete response, or
Christopher Faulet87f1f3d2019-07-18 14:51:20 +0200383 when an "http-response deny" rule blocks the response.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200384 503 when no server was available to handle the request, or in response to
385 monitoring requests which match the "monitor fail" condition
386 504 when the response timeout strikes before the server responds
387
388The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3894.2).
390
391
3921.3.2. The response headers
393---------------------------
394
395Response headers work exactly like request headers, and as such, HAProxy uses
396the same parsing function for both. Please refer to paragraph 1.2.2 for more
397details.
398
399
4002. Configuring HAProxy
401----------------------
402
4032.1. Configuration file format
404------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200405
406HAProxy's configuration process involves 3 major sources of parameters :
407
408 - the arguments from the command-line, which always take precedence
409 - the "global" section, which sets process-wide parameters
410 - the proxies sections which can take form of "defaults", "listen",
411 "frontend" and "backend".
412
Willy Tarreau0ba27502007-12-24 16:55:16 +0100413The configuration file syntax consists in lines beginning with a keyword
414referenced in this manual, optionally followed by one or several parameters
William Lallemandf9873ba2015-05-05 17:37:14 +0200415delimited by spaces.
Willy Tarreau0ba27502007-12-24 16:55:16 +0100416
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200417
William Lallemandf9873ba2015-05-05 17:37:14 +02004182.2. Quoting and escaping
419-------------------------
420
421HAProxy's configuration introduces a quoting and escaping system similar to
422many programming languages. The configuration file supports 3 types: escaping
423with a backslash, weak quoting with double quotes, and strong quoting with
424single quotes.
425
426If spaces have to be entered in strings, then they must be escaped by preceding
427them by a backslash ('\') or by quoting them. Backslashes also have to be
428escaped by doubling or strong quoting them.
429
430Escaping is achieved by preceding a special character by a backslash ('\'):
431
432 \ to mark a space and differentiate it from a delimiter
433 \# to mark a hash and differentiate it from a comment
434 \\ to use a backslash
435 \' to use a single quote and differentiate it from strong quoting
436 \" to use a double quote and differentiate it from weak quoting
437
438Weak quoting is achieved by using double quotes (""). Weak quoting prevents
439the interpretation of:
440
441 space as a parameter separator
442 ' single quote as a strong quoting delimiter
443 # hash as a comment start
444
William Lallemandb2f07452015-05-12 14:27:13 +0200445Weak quoting permits the interpretation of variables, if you want to use a non
446-interpreted dollar within a double quoted string, you should escape it with a
447backslash ("\$"), it does not work outside weak quoting.
448
449Interpretation of escaping and special characters are not prevented by weak
William Lallemandf9873ba2015-05-05 17:37:14 +0200450quoting.
451
452Strong quoting is achieved by using single quotes (''). Inside single quotes,
453nothing is interpreted, it's the efficient way to quote regexes.
454
455Quoted and escaped strings are replaced in memory by their interpreted
456equivalent, it allows you to perform concatenation.
457
458 Example:
459 # those are equivalents:
460 log-format %{+Q}o\ %t\ %s\ %{-Q}r
461 log-format "%{+Q}o %t %s %{-Q}r"
462 log-format '%{+Q}o %t %s %{-Q}r'
463 log-format "%{+Q}o %t"' %s %{-Q}r'
464 log-format "%{+Q}o %t"' %s'\ %{-Q}r
465
466 # those are equivalents:
467 reqrep "^([^\ :]*)\ /static/(.*)" \1\ /\2
468 reqrep "^([^ :]*)\ /static/(.*)" '\1 /\2'
469 reqrep "^([^ :]*)\ /static/(.*)" "\1 /\2"
470 reqrep "^([^ :]*)\ /static/(.*)" "\1\ /\2"
471
472
William Lallemandb2f07452015-05-12 14:27:13 +02004732.3. Environment variables
474--------------------------
475
476HAProxy's configuration supports environment variables. Those variables are
477interpreted only within double quotes. Variables are expanded during the
478configuration parsing. Variable names must be preceded by a dollar ("$") and
479optionally enclosed with braces ("{}") similarly to what is done in Bourne
480shell. Variable names can contain alphanumerical characters or the character
481underscore ("_") but should not start with a digit.
482
483 Example:
484
485 bind "fd@${FD_APP1}"
486
487 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
488
489 user "$HAPROXY_USER"
490
William Lallemand4d03e432019-06-14 15:35:37 +0200491Some variables are defined by HAProxy, they can be used in the configuration
492file, or could be inherited by a program (See 3.7. Programs):
William Lallemanddaf4cd22018-04-17 16:46:13 +0200493
William Lallemand4d03e432019-06-14 15:35:37 +0200494* HAPROXY_LOCALPEER: defined at the startup of the process which contains the
495 name of the local peer. (See "-L" in the management guide.)
496
497* HAPROXY_CFGFILES: list of the configuration files loaded by HAProxy,
498 separated by semicolons. Can be useful in the case you specified a
499 directory.
500
501* HAPROXY_MWORKER: In master-worker mode, this variable is set to 1.
502
John Roeslerfb2fce12019-07-10 15:45:51 -0500503* HAPROXY_CLI: configured listeners addresses of the stats socket for every
William Lallemand4d03e432019-06-14 15:35:37 +0200504 processes, separated by semicolons.
505
John Roeslerfb2fce12019-07-10 15:45:51 -0500506* HAPROXY_MASTER_CLI: In master-worker mode, listeners addresses of the master
William Lallemand4d03e432019-06-14 15:35:37 +0200507 CLI, separated by semicolons.
508
509See also "external-check command" for other variables.
William Lallemandb2f07452015-05-12 14:27:13 +0200510
5112.4. Time format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200512----------------
513
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100514Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100515values are generally expressed in milliseconds (unless explicitly stated
516otherwise) but may be expressed in any other unit by suffixing the unit to the
517numeric value. It is important to consider this because it will not be repeated
518for every keyword. Supported units are :
519
520 - us : microseconds. 1 microsecond = 1/1000000 second
521 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
522 - s : seconds. 1s = 1000ms
523 - m : minutes. 1m = 60s = 60000ms
524 - h : hours. 1h = 60m = 3600s = 3600000ms
525 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
526
527
Lukas Tribusaa83a312017-03-21 09:25:09 +00005282.5. Examples
Patrick Mezard35da19c2010-06-12 17:02:47 +0200529-------------
530
531 # Simple configuration for an HTTP proxy listening on port 80 on all
532 # interfaces and forwarding requests to a single backend "servers" with a
533 # single server "server1" listening on 127.0.0.1:8000
534 global
535 daemon
536 maxconn 256
537
538 defaults
539 mode http
540 timeout connect 5000ms
541 timeout client 50000ms
542 timeout server 50000ms
543
544 frontend http-in
545 bind *:80
546 default_backend servers
547
548 backend servers
549 server server1 127.0.0.1:8000 maxconn 32
550
551
552 # The same configuration defined with a single listen block. Shorter but
553 # less expressive, especially in HTTP mode.
554 global
555 daemon
556 maxconn 256
557
558 defaults
559 mode http
560 timeout connect 5000ms
561 timeout client 50000ms
562 timeout server 50000ms
563
564 listen http-in
565 bind *:80
566 server server1 127.0.0.1:8000 maxconn 32
567
568
569Assuming haproxy is in $PATH, test these configurations in a shell with:
570
Willy Tarreauccb289d2010-12-11 20:19:38 +0100571 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200572
573
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005743. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200575--------------------
576
577Parameters in the "global" section are process-wide and often OS-specific. They
578are generally set once for all and do not need being changed once correct. Some
579of them have command-line equivalents.
580
581The following keywords are supported in the "global" section :
582
583 * Process management and security
Emeric Brunc8e8d122012-10-02 18:42:10 +0200584 - ca-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200585 - chroot
Emeric Brunc8e8d122012-10-02 18:42:10 +0200586 - crt-base
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200587 - cpu-map
Willy Tarreau6a06a402007-07-15 20:15:28 +0200588 - daemon
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200589 - description
590 - deviceatlas-json-file
591 - deviceatlas-log-level
592 - deviceatlas-separator
593 - deviceatlas-properties-cookie
Simon Horman98637e52014-06-20 12:30:16 +0900594 - external-check
Willy Tarreau6a06a402007-07-15 20:15:28 +0200595 - gid
596 - group
Cyril Bonté203ec5a2017-03-23 22:44:13 +0100597 - hard-stop-after
Christopher Faulet98fbe952019-07-22 16:18:24 +0200598 - h1-case-adjust
599 - h1-case-adjust-file
Willy Tarreaud96f1122019-12-03 07:07:36 +0100600 - insecure-fork-wanted
Willy Tarreaua45a8b52019-12-06 16:31:45 +0100601 - insecure-setuid-wanted
Willy Tarreau6a06a402007-07-15 20:15:28 +0200602 - log
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200603 - log-tag
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100604 - log-send-hostname
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200605 - lua-load
William Lallemand27edc4b2019-05-07 17:49:33 +0200606 - mworker-max-reloads
Willy Tarreau6a06a402007-07-15 20:15:28 +0200607 - nbproc
Christopher Fauletbe0faa22017-08-29 15:37:10 +0200608 - nbthread
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200609 - node
Willy Tarreau6a06a402007-07-15 20:15:28 +0200610 - pidfile
Willy Tarreau1d549722016-02-16 12:41:57 +0100611 - presetenv
612 - resetenv
Willy Tarreau6a06a402007-07-15 20:15:28 +0200613 - uid
614 - ulimit-n
615 - user
Willy Tarreau636848a2019-04-15 19:38:50 +0200616 - set-dumpable
Willy Tarreau1d549722016-02-16 12:41:57 +0100617 - setenv
Willy Tarreaufbee7132007-10-18 13:53:22 +0200618 - stats
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200619 - ssl-default-bind-ciphers
Dirkjan Bussink415150f2018-09-14 11:14:21 +0200620 - ssl-default-bind-ciphersuites
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200621 - ssl-default-bind-options
622 - ssl-default-server-ciphers
Dirkjan Bussink415150f2018-09-14 11:14:21 +0200623 - ssl-default-server-ciphersuites
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200624 - ssl-default-server-options
625 - ssl-dh-param-file
Emeric Brun850efd52014-01-29 12:24:34 +0100626 - ssl-server-verify
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100627 - unix-bind
Willy Tarreau1d549722016-02-16 12:41:57 +0100628 - unsetenv
Thomas Holmesdb04f192015-05-18 13:21:39 +0100629 - 51degrees-data-file
630 - 51degrees-property-name-list
Dragan Dosen93b38d92015-06-29 16:43:25 +0200631 - 51degrees-property-separator
Dragan Dosenae6d39a2015-06-29 16:43:27 +0200632 - 51degrees-cache-size
Willy Tarreaub3cc9f22019-04-19 16:03:32 +0200633 - wurfl-data-file
634 - wurfl-information-list
635 - wurfl-information-list-separator
Willy Tarreaub3cc9f22019-04-19 16:03:32 +0200636 - wurfl-cache-size
William Dauchy0fec3ab2019-10-27 20:08:11 +0100637 - strict-limits
Willy Tarreaud72758d2010-01-12 10:42:19 +0100638
Willy Tarreau6a06a402007-07-15 20:15:28 +0200639 * Performance tuning
William Dauchy0a8824f2019-10-27 20:08:09 +0100640 - busy-polling
Willy Tarreau1746eec2014-04-25 10:46:47 +0200641 - max-spread-checks
Willy Tarreau6a06a402007-07-15 20:15:28 +0200642 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +0200643 - maxconnrate
William Lallemandd85f9172012-11-09 17:05:39 +0100644 - maxcomprate
William Lallemand072a2bf2012-11-20 17:01:01 +0100645 - maxcompcpuusage
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100646 - maxpipes
Willy Tarreau93e7c002013-10-07 18:51:07 +0200647 - maxsessrate
Willy Tarreau403edff2012-09-06 11:58:37 +0200648 - maxsslconn
Willy Tarreaue43d5322013-10-07 20:01:52 +0200649 - maxsslrate
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200650 - maxzlibmem
Willy Tarreau6a06a402007-07-15 20:15:28 +0200651 - noepoll
652 - nokqueue
Emmanuel Hocdet0ba4f482019-04-08 16:53:32 +0000653 - noevports
Willy Tarreau6a06a402007-07-15 20:15:28 +0200654 - nopoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100655 - nosplice
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300656 - nogetaddrinfo
Lukas Tribusa0bcbdc2016-09-12 21:42:20 +0000657 - noreuseport
Willy Tarreau75c62c22018-11-22 11:02:09 +0100658 - profiling.tasks
Willy Tarreaufe255b72007-10-14 23:09:26 +0200659 - spread-checks
Baptiste Assmann5626f482015-08-23 10:00:10 +0200660 - server-state-base
Baptiste Assmannef1f0fc2015-08-23 10:06:39 +0200661 - server-state-file
Grant Zhang872f9c22017-01-21 01:10:18 +0000662 - ssl-engine
Grant Zhangfa6c7ee2017-01-14 01:42:15 +0000663 - ssl-mode-async
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200664 - tune.buffers.limit
665 - tune.buffers.reserve
Willy Tarreau27a674e2009-08-17 07:23:33 +0200666 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200667 - tune.chksize
William Lallemandf3747832012-11-09 12:33:10 +0100668 - tune.comp.maxlevel
Willy Tarreaufe20e5b2017-07-27 11:42:14 +0200669 - tune.h2.header-table-size
Willy Tarreaue6baec02017-07-27 11:45:11 +0200670 - tune.h2.initial-window-size
Willy Tarreau5242ef82017-07-27 11:47:28 +0200671 - tune.h2.max-concurrent-streams
Willy Tarreau193b8c62012-11-22 00:17:38 +0100672 - tune.http.cookielen
Stéphane Cottin23e9e932017-05-18 08:58:41 +0200673 - tune.http.logurilen
Willy Tarreauac1932d2011-10-24 19:14:41 +0200674 - tune.http.maxhdr
Willy Tarreau7e312732014-02-12 16:35:14 +0100675 - tune.idletimer
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100676 - tune.lua.forced-yield
Willy Tarreau32f61e22015-03-18 17:54:59 +0100677 - tune.lua.maxmem
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100678 - tune.lua.session-timeout
679 - tune.lua.task-timeout
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +0200680 - tune.lua.service-timeout
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100681 - tune.maxaccept
682 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200683 - tune.maxrewrite
Willy Tarreauf3045d22015-04-29 16:24:50 +0200684 - tune.pattern.cache-size
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200685 - tune.pipesize
Willy Tarreaue803de22010-01-21 17:43:04 +0100686 - tune.rcvbuf.client
687 - tune.rcvbuf.server
Willy Tarreaub22fc302015-12-14 12:04:35 +0100688 - tune.recv_enough
Olivier Houchard1599b802018-05-24 18:59:04 +0200689 - tune.runqueue-depth
Willy Tarreaue803de22010-01-21 17:43:04 +0100690 - tune.sndbuf.client
691 - tune.sndbuf.server
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100692 - tune.ssl.cachesize
Willy Tarreaubfd59462013-02-21 07:46:09 +0100693 - tune.ssl.lifetime
Emeric Brun8dc60392014-05-09 13:52:00 +0200694 - tune.ssl.force-private-cache
Willy Tarreaubfd59462013-02-21 07:46:09 +0100695 - tune.ssl.maxrecord
Remi Gacognef46cd6e2014-06-12 14:58:40 +0200696 - tune.ssl.default-dh-param
Christopher Faulet31af49d2015-06-09 17:29:50 +0200697 - tune.ssl.ssl-ctx-cache-size
Thierry FOURNIER5bf77322017-02-25 12:45:22 +0100698 - tune.ssl.capture-cipherlist-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +0200699 - tune.vars.global-max-size
Christopher Fauletff2613e2016-11-09 11:36:17 +0100700 - tune.vars.proc-max-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +0200701 - tune.vars.reqres-max-size
702 - tune.vars.sess-max-size
703 - tune.vars.txn-max-size
William Lallemanda509e4c2012-11-07 16:54:34 +0100704 - tune.zlib.memlevel
705 - tune.zlib.windowsize
Willy Tarreaud72758d2010-01-12 10:42:19 +0100706
Willy Tarreau6a06a402007-07-15 20:15:28 +0200707 * Debugging
708 - debug
709 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200710
711
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007123.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200713------------------------------------
714
Emeric Brunc8e8d122012-10-02 18:42:10 +0200715ca-base <dir>
716 Assigns a default directory to fetch SSL CA certificates and CRLs from when a
Emeric Brunfd33a262012-10-11 16:28:27 +0200717 relative path is used with "ca-file" or "crl-file" directives. Absolute
718 locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200719
Willy Tarreau6a06a402007-07-15 20:15:28 +0200720chroot <jail dir>
721 Changes current directory to <jail dir> and performs a chroot() there before
722 dropping privileges. This increases the security level in case an unknown
723 vulnerability would be exploited, since it would make it very hard for the
724 attacker to exploit the system. This only works when the process is started
725 with superuser privileges. It is important to ensure that <jail_dir> is both
Davor Ocelice9ed2812017-12-25 17:49:28 +0100726 empty and non-writable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100727
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100728cpu-map [auto:]<process-set>[/<thread-set>] <cpu-set>...
729 On Linux 2.6 and above, it is possible to bind a process or a thread to a
730 specific CPU set. This means that the process or the thread will never run on
731 other CPUs. The "cpu-map" directive specifies CPU sets for process or thread
732 sets. The first argument is a process set, eventually followed by a thread
733 set. These sets have the format
734
735 all | odd | even | number[-[number]]
736
737 <number>> must be a number between 1 and 32 or 64, depending on the machine's
Davor Ocelice9ed2812017-12-25 17:49:28 +0100738 word size. Any process IDs above nbproc and any thread IDs above nbthread are
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100739 ignored. It is possible to specify a range with two such number delimited by
740 a dash ('-'). It also is possible to specify all processes at once using
Christopher Faulet1dcb9cb2017-11-22 10:24:40 +0100741 "all", only odd numbers using "odd" or even numbers using "even", just like
742 with the "bind-process" directive. The second and forthcoming arguments are
Davor Ocelice9ed2812017-12-25 17:49:28 +0100743 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 +0100744 range with two such numbers delimited by a dash ('-'). Multiple CPU numbers
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100745 or ranges may be specified, and the processes or threads will be allowed to
Davor Ocelice9ed2812017-12-25 17:49:28 +0100746 bind to all of them. Obviously, multiple "cpu-map" directives may be
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100747 specified. Each "cpu-map" directive will replace the previous ones when they
748 overlap. A thread will be bound on the intersection of its mapping and the
749 one of the process on which it is attached. If the intersection is null, no
750 specific binding will be set for the thread.
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100751
Christopher Fauletff4121f2017-11-22 16:38:49 +0100752 Ranges can be partially defined. The higher bound can be omitted. In such
753 case, it is replaced by the corresponding maximum value, 32 or 64 depending
754 on the machine's word size.
755
Christopher Faulet26028f62017-11-22 15:01:51 +0100756 The prefix "auto:" can be added before the process set to let HAProxy
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100757 automatically bind a process or a thread to a CPU by incrementing
758 process/thread and CPU sets. To be valid, both sets must have the same
759 size. No matter the declaration order of the CPU sets, it will be bound from
760 the lowest to the highest bound. Having a process and a thread range with the
761 "auto:" prefix is not supported. Only one range is supported, the other one
762 must be a fixed number.
Christopher Faulet26028f62017-11-22 15:01:51 +0100763
764 Examples:
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100765 cpu-map 1-4 0-3 # bind processes 1 to 4 on the first 4 CPUs
766
767 cpu-map 1/all 0-3 # bind all threads of the first process on the
768 # first 4 CPUs
769
770 cpu-map 1- 0- # will be replaced by "cpu-map 1-64 0-63"
771 # or "cpu-map 1-32 0-31" depending on the machine's
772 # word size.
773
Christopher Faulet26028f62017-11-22 15:01:51 +0100774 # all these lines bind the process 1 to the cpu 0, the process 2 to cpu 1
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100775 # and so on.
Christopher Faulet26028f62017-11-22 15:01:51 +0100776 cpu-map auto:1-4 0-3
777 cpu-map auto:1-4 0-1 2-3
778 cpu-map auto:1-4 3 2 1 0
779
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100780 # all these lines bind the thread 1 to the cpu 0, the thread 2 to cpu 1
781 # and so on.
782 cpu-map auto:1/1-4 0-3
783 cpu-map auto:1/1-4 0-1 2-3
784 cpu-map auto:1/1-4 3 2 1 0
785
Davor Ocelice9ed2812017-12-25 17:49:28 +0100786 # bind each process to exactly one CPU using all/odd/even keyword
Christopher Faulet26028f62017-11-22 15:01:51 +0100787 cpu-map auto:all 0-63
788 cpu-map auto:even 0-31
789 cpu-map auto:odd 32-63
790
791 # invalid cpu-map because process and CPU sets have different sizes.
792 cpu-map auto:1-4 0 # invalid
793 cpu-map auto:1 0-3 # invalid
794
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100795 # invalid cpu-map because automatic binding is used with a process range
796 # and a thread range.
797 cpu-map auto:all/all 0 # invalid
798 cpu-map auto:all/1-4 0 # invalid
799 cpu-map auto:1-4/all 0 # invalid
800
Emeric Brunc8e8d122012-10-02 18:42:10 +0200801crt-base <dir>
802 Assigns a default directory to fetch SSL certificates from when a relative
William Dauchy238ea3b2020-01-11 13:09:12 +0100803 path is used with "crtfile" or "crt" directives. Absolute locations specified
804 prevail and ignore "crt-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200805
Willy Tarreau6a06a402007-07-15 20:15:28 +0200806daemon
807 Makes the process fork into background. This is the recommended mode of
808 operation. It is equivalent to the command line "-D" argument. It can be
Lukas Tribusf46bf952017-11-21 12:39:34 +0100809 disabled by the command line "-db" argument. This option is ignored in
810 systemd mode.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200811
David Carlier8167f302015-06-01 13:50:06 +0200812deviceatlas-json-file <path>
813 Sets the path of the DeviceAtlas JSON data file to be loaded by the API.
Davor Ocelice9ed2812017-12-25 17:49:28 +0100814 The path must be a valid JSON data file and accessible by HAProxy process.
David Carlier8167f302015-06-01 13:50:06 +0200815
816deviceatlas-log-level <value>
Davor Ocelice9ed2812017-12-25 17:49:28 +0100817 Sets the level of information returned by the API. This directive is
David Carlier8167f302015-06-01 13:50:06 +0200818 optional and set to 0 by default if not set.
819
820deviceatlas-separator <char>
821 Sets the character separator for the API properties results. This directive
822 is optional and set to | by default if not set.
823
Cyril Bonté0306c4a2015-10-26 22:37:38 +0100824deviceatlas-properties-cookie <name>
Cyril Bonté307ee1e2015-09-28 23:16:06 +0200825 Sets the client cookie's name used for the detection if the DeviceAtlas
826 Client-side component was used during the request. This directive is optional
827 and set to DAPROPS by default if not set.
David Carlier29b3ca32015-09-25 14:09:21 +0100828
Simon Horman98637e52014-06-20 12:30:16 +0900829external-check
Willy Tarreaud96f1122019-12-03 07:07:36 +0100830 Allows the use of an external agent to perform health checks. This is
831 disabled by default as a security precaution, and even when enabled, checks
Willy Tarreaua45a8b52019-12-06 16:31:45 +0100832 may still fail unless "insecure-fork-wanted" is enabled as well. If the
833 program launched makes use of a setuid executable (it should really not),
834 you may also need to set "insecure-setuid-wanted" in the global section.
835 See "option external-check", and "insecure-fork-wanted", and
836 "insecure-setuid-wanted".
Simon Horman98637e52014-06-20 12:30:16 +0900837
Willy Tarreau6a06a402007-07-15 20:15:28 +0200838gid <number>
839 Changes the process' group ID to <number>. It is recommended that the group
840 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
841 be started with a user belonging to this group, or with superuser privileges.
Michael Schererab012dd2013-01-12 18:35:19 +0100842 Note that if haproxy is started from a user having supplementary groups, it
843 will only be able to drop these groups if started with superuser privileges.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200844 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100845
Willy Tarreau11770ce2019-12-03 08:29:22 +0100846group <group name>
847 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
848 See also "gid" and "user".
849
Cyril Bonté203ec5a2017-03-23 22:44:13 +0100850hard-stop-after <time>
851 Defines the maximum time allowed to perform a clean soft-stop.
852
853 Arguments :
854 <time> is the maximum time (by default in milliseconds) for which the
855 instance will remain alive when a soft-stop is received via the
856 SIGUSR1 signal.
857
858 This may be used to ensure that the instance will quit even if connections
859 remain opened during a soft-stop (for example with long timeouts for a proxy
860 in tcp mode). It applies both in TCP and HTTP mode.
861
862 Example:
863 global
864 hard-stop-after 30s
865
Christopher Faulet98fbe952019-07-22 16:18:24 +0200866h1-case-adjust <from> <to>
867 Defines the case adjustment to apply, when enabled, to the header name
868 <from>, to change it to <to> before sending it to HTTP/1 clients or
869 servers. <from> must be in lower case, and <from> and <to> must not differ
870 except for their case. It may be repeated if several header names need to be
871 ajusted. Duplicate entries are not allowed. If a lot of header names have to
872 be adjusted, it might be more convenient to use "h1-case-adjust-file".
873 Please note that no transformation will be applied unless "option
874 h1-case-adjust-bogus-client" or "option h1-case-adjust-bogus-server" is
875 specified in a proxy.
876
877 There is no standard case for header names because, as stated in RFC7230,
878 they are case-insensitive. So applications must handle them in a case-
879 insensitive manner. But some bogus applications violate the standards and
880 erroneously rely on the cases most commonly used by browsers. This problem
881 becomes critical with HTTP/2 because all header names must be exchanged in
882 lower case, and HAProxy follows the same convention. All header names are
883 sent in lower case to clients and servers, regardless of the HTTP version.
884
885 Applications which fail to properly process requests or responses may require
886 to temporarily use such workarounds to adjust header names sent to them for
887 the time it takes the application to be fixed. Please note that an
888 application which requires such workarounds might be vulnerable to content
889 smuggling attacks and must absolutely be fixed.
890
891 Example:
892 global
893 h1-case-adjust content-length Content-Length
894
895 See "h1-case-adjust-file", "option h1-case-adjust-bogus-client" and
896 "option h1-case-adjust-bogus-server".
897
898h1-case-adjust-file <hdrs-file>
899 Defines a file containing a list of key/value pairs used to adjust the case
900 of some header names before sending them to HTTP/1 clients or servers. The
901 file <hdrs-file> must contain 2 header names per line. The first one must be
902 in lower case and both must not differ except for their case. Lines which
903 start with '#' are ignored, just like empty lines. Leading and trailing tabs
904 and spaces are stripped. Duplicate entries are not allowed. Please note that
905 no transformation will be applied unless "option h1-case-adjust-bogus-client"
906 or "option h1-case-adjust-bogus-server" is specified in a proxy.
907
908 If this directive is repeated, only the last one will be processed. It is an
909 alternative to the directive "h1-case-adjust" if a lot of header names need
910 to be adjusted. Please read the risks associated with using this.
911
912 See "h1-case-adjust", "option h1-case-adjust-bogus-client" and
913 "option h1-case-adjust-bogus-server".
914
Willy Tarreaud96f1122019-12-03 07:07:36 +0100915insecure-fork-wanted
916 By default haproxy tries hard to prevent any thread and process creation
917 after it starts. Doing so is particularly important when using Lua files of
918 uncertain origin, and when experimenting with development versions which may
919 still contain bugs whose exploitability is uncertain. And generally speaking
920 it's good hygiene to make sure that no unexpected background activity can be
921 triggered by traffic. But this prevents external checks from working, and may
922 break some very specific Lua scripts which actively rely on the ability to
923 fork. This option is there to disable this protection. Note that it is a bad
924 idea to disable it, as a vulnerability in a library or within haproxy itself
925 will be easier to exploit once disabled. In addition, forking from Lua or
926 anywhere else is not reliable as the forked process may randomly embed a lock
927 set by another thread and never manage to finish an operation. As such it is
928 highly recommended that this option is never used and that any workload
929 requiring such a fork be reconsidered and moved to a safer solution (such as
930 agents instead of external checks). This option supports the "no" prefix to
931 disable it.
932
Willy Tarreaua45a8b52019-12-06 16:31:45 +0100933insecure-setuid-wanted
934 HAProxy doesn't need to call executables at run time (except when using
935 external checks which are strongly recommended against), and is even expected
936 to isolate itself into an empty chroot. As such, there basically is no valid
937 reason to allow a setuid executable to be called without the user being fully
938 aware of the risks. In a situation where haproxy would need to call external
939 checks and/or disable chroot, exploiting a vulnerability in a library or in
940 haproxy itself could lead to the execution of an external program. On Linux
941 it is possible to lock the process so that any setuid bit present on such an
942 executable is ignored. This significantly reduces the risk of privilege
943 escalation in such a situation. This is what haproxy does by default. In case
944 this causes a problem to an external check (for example one which would need
945 the "ping" command), then it is possible to disable this protection by
946 explicitly adding this directive in the global section. If enabled, it is
947 possible to turn it back off by prefixing it with the "no" keyword.
948
Frédéric Lécailled690dfa2019-04-25 10:52:17 +0200949log <address> [len <length>] [format <format>] [sample <ranges>:<smp_size>]
950 <facility> [max level [min level]]
Cyril Bonté3e954872018-03-20 23:30:27 +0100951 Adds a global syslog server. Several global servers can be defined. They
Davor Ocelice9ed2812017-12-25 17:49:28 +0100952 will receive logs for starts and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100953 configured with "log global".
954
955 <address> can be one of:
956
Willy Tarreau2769aa02007-12-27 18:26:09 +0100957 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100958 no port is specified, 514 is used by default (the standard syslog
959 port).
960
David du Colombier24bb5f52011-03-17 10:40:23 +0100961 - An IPv6 address followed by a colon and optionally a UDP port. If
962 no port is specified, 514 is used by default (the standard syslog
963 port).
964
Willy Tarreau5a32ecc2018-11-12 07:34:59 +0100965 - A filesystem path to a datagram UNIX domain socket, keeping in mind
Robert Tsai81ae1952007-12-05 10:47:29 +0100966 considerations for chroot (be sure the path is accessible inside
967 the chroot) and uid/gid (be sure the path is appropriately
Davor Ocelice9ed2812017-12-25 17:49:28 +0100968 writable).
Robert Tsai81ae1952007-12-05 10:47:29 +0100969
Willy Tarreau5a32ecc2018-11-12 07:34:59 +0100970 - A file descriptor number in the form "fd@<number>", which may point
971 to a pipe, terminal, or socket. In this case unbuffered logs are used
972 and one writev() call per log is performed. This is a bit expensive
973 but acceptable for most workloads. Messages sent this way will not be
974 truncated but may be dropped, in which case the DroppedLogs counter
975 will be incremented. The writev() call is atomic even on pipes for
976 messages up to PIPE_BUF size, which POSIX recommends to be at least
977 512 and which is 4096 bytes on most modern operating systems. Any
978 larger message may be interleaved with messages from other processes.
979 Exceptionally for debugging purposes the file descriptor may also be
980 directed to a file, but doing so will significantly slow haproxy down
981 as non-blocking calls will be ignored. Also there will be no way to
982 purge nor rotate this file without restarting the process. Note that
983 the configured syslog format is preserved, so the output is suitable
Willy Tarreauc1b06452018-11-12 11:57:56 +0100984 for use with a TCP syslog server. See also the "short" and "raw"
985 format below.
Willy Tarreau5a32ecc2018-11-12 07:34:59 +0100986
987 - "stdout" / "stderr", which are respectively aliases for "fd@1" and
988 "fd@2", see above.
989
Willy Tarreauc046d162019-08-30 15:24:59 +0200990 - A ring buffer in the form "ring@<name>", which will correspond to an
991 in-memory ring buffer accessible over the CLI using the "show events"
992 command, which will also list existing rings and their sizes. Such
993 buffers are lost on reload or restart but when used as a complement
994 this can help troubleshooting by having the logs instantly available.
995
William Lallemandb2f07452015-05-12 14:27:13 +0200996 You may want to reference some environment variables in the address
997 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +0100998
Willy Tarreau18324f52014-06-27 18:10:07 +0200999 <length> is an optional maximum line length. Log lines larger than this value
1000 will be truncated before being sent. The reason is that syslog
1001 servers act differently on log line length. All servers support the
1002 default value of 1024, but some servers simply drop larger lines
1003 while others do log them. If a server supports long lines, it may
1004 make sense to set this value here in order to avoid truncating long
1005 lines. Similarly, if a server drops long lines, it is preferable to
1006 truncate them before sending them. Accepted values are 80 to 65535
1007 inclusive. The default value of 1024 is generally fine for all
1008 standard usages. Some specific cases of long captures or
Davor Ocelice9ed2812017-12-25 17:49:28 +01001009 JSON-formatted logs may require larger values. You may also need to
1010 increase "tune.http.logurilen" if your request URIs are truncated.
Willy Tarreau18324f52014-06-27 18:10:07 +02001011
Dragan Dosen7ad31542015-09-28 17:16:47 +02001012 <format> is the log format used when generating syslog messages. It may be
1013 one of the following :
1014
1015 rfc3164 The RFC3164 syslog message format. This is the default.
1016 (https://tools.ietf.org/html/rfc3164)
1017
1018 rfc5424 The RFC5424 syslog message format.
1019 (https://tools.ietf.org/html/rfc5424)
1020
Willy Tarreaue8746a02018-11-12 08:45:00 +01001021 short A message containing only a level between angle brackets such as
1022 '<3>', followed by the text. The PID, date, time, process name
1023 and system name are omitted. This is designed to be used with a
1024 local log server. This format is compatible with what the systemd
1025 logger consumes.
1026
Willy Tarreauc1b06452018-11-12 11:57:56 +01001027 raw A message containing only the text. The level, PID, date, time,
1028 process name and system name are omitted. This is designed to be
1029 used in containers or during development, where the severity only
1030 depends on the file descriptor used (stdout/stderr).
1031
Frédéric Lécailled690dfa2019-04-25 10:52:17 +02001032 <ranges> A list of comma-separated ranges to identify the logs to sample.
1033 This is used to balance the load of the logs to send to the log
1034 server. The limits of the ranges cannot be null. They are numbered
1035 from 1. The size or period (in number of logs) of the sample must be
1036 set with <sample_size> parameter.
1037
1038 <sample_size>
1039 The size of the sample in number of logs to consider when balancing
1040 their logging loads. It is used to balance the load of the logs to
1041 send to the syslog server. This size must be greater or equal to the
1042 maximum of the high limits of the ranges.
1043 (see also <ranges> parameter).
1044
Robert Tsai81ae1952007-12-05 10:47:29 +01001045 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +02001046
Willy Tarreaue8746a02018-11-12 08:45:00 +01001047 kern user mail daemon auth syslog lpr news
1048 uucp cron auth2 ftp ntp audit alert cron2
1049 local0 local1 local2 local3 local4 local5 local6 local7
1050
Willy Tarreauc1b06452018-11-12 11:57:56 +01001051 Note that the facility is ignored for the "short" and "raw"
1052 formats, but still required as a positional field. It is
1053 recommended to use "daemon" in this case to make it clear that
1054 it's only supposed to be used locally.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001055
1056 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +02001057 all messages are sent. If a maximum level is specified, only messages with a
1058 severity at least as important as this level will be sent. An optional minimum
1059 level can be specified. If it is set, logs emitted with a more severe level
1060 than this one will be capped to this level. This is used to avoid sending
1061 "emerg" messages on all terminals on some default syslog configurations.
1062 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +02001063
Cyril Bontédc4d9032012-04-08 21:57:39 +02001064 emerg alert crit err warning notice info debug
Willy Tarreau6a06a402007-07-15 20:15:28 +02001065
Joe Williamsdf5b38f2010-12-29 17:05:48 +01001066log-send-hostname [<string>]
1067 Sets the hostname field in the syslog header. If optional "string" parameter
1068 is set the header is set to the string contents, otherwise uses the hostname
1069 of the system. Generally used if one is not relaying logs through an
1070 intermediate syslog server or for simply customizing the hostname printed in
1071 the logs.
1072
Kevinm48936af2010-12-22 16:08:21 +00001073log-tag <string>
1074 Sets the tag field in the syslog header to this string. It defaults to the
1075 program name as launched from the command line, which usually is "haproxy".
1076 Sometimes it can be useful to differentiate between multiple processes
Willy Tarreau094af4e2015-01-07 15:03:42 +01001077 running on the same host. See also the per-proxy "log-tag" directive.
Kevinm48936af2010-12-22 16:08:21 +00001078
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001079lua-load <file>
1080 This global directive loads and executes a Lua file. This directive can be
1081 used multiple times.
1082
William Lallemand4cfede82017-11-24 22:02:34 +01001083master-worker [no-exit-on-failure]
William Lallemande202b1e2017-06-01 17:38:56 +02001084 Master-worker mode. It is equivalent to the command line "-W" argument.
1085 This mode will launch a "master" which will monitor the "workers". Using
1086 this mode, you can reload HAProxy directly by sending a SIGUSR2 signal to
Davor Ocelice9ed2812017-12-25 17:49:28 +01001087 the master. The master-worker mode is compatible either with the foreground
William Lallemande202b1e2017-06-01 17:38:56 +02001088 or daemon mode. It is recommended to use this mode with multiprocess and
1089 systemd.
William Lallemand4cfede82017-11-24 22:02:34 +01001090 By default, if a worker exits with a bad return code, in the case of a
1091 segfault for example, all workers will be killed, and the master will leave.
1092 It is convenient to combine this behavior with Restart=on-failure in a
1093 systemd unit file in order to relaunch the whole process. If you don't want
1094 this behavior, you must use the keyword "no-exit-on-failure".
William Lallemande202b1e2017-06-01 17:38:56 +02001095
William Lallemand4cfede82017-11-24 22:02:34 +01001096 See also "-W" in the management guide.
William Lallemande202b1e2017-06-01 17:38:56 +02001097
William Lallemand27edc4b2019-05-07 17:49:33 +02001098mworker-max-reloads <number>
1099 In master-worker mode, this option limits the number of time a worker can
John Roeslerfb2fce12019-07-10 15:45:51 -05001100 survive to a reload. If the worker did not leave after a reload, once its
William Lallemand27edc4b2019-05-07 17:49:33 +02001101 number of reloads is greater than this number, the worker will receive a
1102 SIGTERM. This option helps to keep under control the number of workers.
1103 See also "show proc" in the Management Guide.
1104
Willy Tarreau6a06a402007-07-15 20:15:28 +02001105nbproc <number>
1106 Creates <number> processes when going daemon. This requires the "daemon"
1107 mode. By default, only one process is created, which is the recommended mode
1108 of operation. For systems limited to small sets of file descriptors per
Willy Tarreau149ab772019-01-26 14:27:06 +01001109 process, it may be needed to fork multiple daemons. When set to a value
1110 larger than 1, threads are automatically disabled. USING MULTIPLE PROCESSES
Willy Tarreau1f672a82019-01-26 14:20:55 +01001111 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon" and
1112 "nbthread".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001113
Christopher Fauletbe0faa22017-08-29 15:37:10 +02001114nbthread <number>
1115 This setting is only available when support for threads was built in. It
Willy Tarreau26f6ae12019-02-02 12:56:15 +01001116 makes haproxy run on <number> threads. This is exclusive with "nbproc". While
1117 "nbproc" historically used to be the only way to use multiple processors, it
1118 also involved a number of shortcomings related to the lack of synchronization
1119 between processes (health-checks, peers, stick-tables, stats, ...) which do
1120 not affect threads. As such, any modern configuration is strongly encouraged
Willy Tarreau149ab772019-01-26 14:27:06 +01001121 to migrate away from "nbproc" to "nbthread". "nbthread" also works when
1122 HAProxy is started in foreground. On some platforms supporting CPU affinity,
1123 when nbproc is not used, the default "nbthread" value is automatically set to
1124 the number of CPUs the process is bound to upon startup. This means that the
1125 thread count can easily be adjusted from the calling process using commands
1126 like "taskset" or "cpuset". Otherwise, this value defaults to 1. The default
1127 value is reported in the output of "haproxy -vv". See also "nbproc".
Christopher Fauletbe0faa22017-08-29 15:37:10 +02001128
Willy Tarreau6a06a402007-07-15 20:15:28 +02001129pidfile <pidfile>
Davor Ocelice9ed2812017-12-25 17:49:28 +01001130 Writes PIDs of all daemons into file <pidfile>. This option is equivalent to
Willy Tarreau6a06a402007-07-15 20:15:28 +02001131 the "-p" command line argument. The file must be accessible to the user
1132 starting the process. See also "daemon".
1133
Willy Tarreau1d549722016-02-16 12:41:57 +01001134presetenv <name> <value>
1135 Sets environment variable <name> to value <value>. If the variable exists, it
1136 is NOT overwritten. The changes immediately take effect so that the next line
1137 in the configuration file sees the new value. See also "setenv", "resetenv",
1138 and "unsetenv".
1139
1140resetenv [<name> ...]
1141 Removes all environment variables except the ones specified in argument. It
1142 allows to use a clean controlled environment before setting new values with
1143 setenv or unsetenv. Please note that some internal functions may make use of
1144 some environment variables, such as time manipulation functions, but also
1145 OpenSSL or even external checks. This must be used with extreme care and only
1146 after complete validation. The changes immediately take effect so that the
1147 next line in the configuration file sees the new environment. See also
1148 "setenv", "presetenv", and "unsetenv".
1149
Christopher Fauletff4121f2017-11-22 16:38:49 +01001150stats bind-process [ all | odd | even | <process_num>[-[process_num>]] ] ...
Willy Tarreau35b7b162012-10-22 23:17:18 +02001151 Limits the stats socket to a certain set of processes numbers. By default the
1152 stats socket is bound to all processes, causing a warning to be emitted when
1153 nbproc is greater than 1 because there is no way to select the target process
1154 when connecting. However, by using this setting, it becomes possible to pin
1155 the stats socket to a specific set of processes, typically the first one. The
1156 warning will automatically be disabled when this setting is used, whatever
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001157 the number of processes used. The maximum process ID depends on the machine's
Christopher Fauletff4121f2017-11-22 16:38:49 +01001158 word size (32 or 64). Ranges can be partially defined. The higher bound can
1159 be omitted. In such case, it is replaced by the corresponding maximum
1160 value. A better option consists in using the "process" setting of the "stats
1161 socket" line to force the process on each line.
Willy Tarreau35b7b162012-10-22 23:17:18 +02001162
Baptiste Assmann5626f482015-08-23 10:00:10 +02001163server-state-base <directory>
1164 Specifies the directory prefix to be prepended in front of all servers state
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02001165 file names which do not start with a '/'. See also "server-state-file",
1166 "load-server-state-from-file" and "server-state-file-name".
Baptiste Assmannef1f0fc2015-08-23 10:06:39 +02001167
1168server-state-file <file>
1169 Specifies the path to the file containing state of servers. If the path starts
1170 with a slash ('/'), it is considered absolute, otherwise it is considered
1171 relative to the directory specified using "server-state-base" (if set) or to
1172 the current directory. Before reloading HAProxy, it is possible to save the
1173 servers' current state using the stats command "show servers state". The
1174 output of this command must be written in the file pointed by <file>. When
1175 starting up, before handling traffic, HAProxy will read, load and apply state
1176 for each server found in the file and available in its current running
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02001177 configuration. See also "server-state-base" and "show servers state",
1178 "load-server-state-from-file" and "server-state-file-name"
Baptiste Assmann5626f482015-08-23 10:00:10 +02001179
Willy Tarreau1d549722016-02-16 12:41:57 +01001180setenv <name> <value>
1181 Sets environment variable <name> to value <value>. If the variable exists, it
1182 is overwritten. The changes immediately take effect so that the next line in
1183 the configuration file sees the new value. See also "presetenv", "resetenv",
1184 and "unsetenv".
1185
Willy Tarreau636848a2019-04-15 19:38:50 +02001186set-dumpable
1187 This option is better left disabled by default and enabled only upon a
William Dauchyec730982019-10-27 20:08:10 +01001188 developer's request. If it has been enabled, it may still be forcibly
1189 disabled by prefixing it with the "no" keyword. It has no impact on
1190 performance nor stability but will try hard to re-enable core dumps that were
1191 possibly disabled by file size limitations (ulimit -f), core size limitations
1192 (ulimit -c), or "dumpability" of a process after changing its UID/GID (such
1193 as /proc/sys/fs/suid_dumpable on Linux). Core dumps might still be limited by
1194 the current directory's permissions (check what directory the file is started
1195 from), the chroot directory's permission (it may be needed to temporarily
1196 disable the chroot directive or to move it to a dedicated writable location),
1197 or any other system-specific constraint. For example, some Linux flavours are
1198 notorious for replacing the default core file with a path to an executable
1199 not even installed on the system (check /proc/sys/kernel/core_pattern). Often,
1200 simply writing "core", "core.%p" or "/var/log/core/core.%p" addresses the
1201 issue. When trying to enable this option waiting for a rare issue to
1202 re-appear, it's often a good idea to first try to obtain such a dump by
1203 issuing, for example, "kill -11" to the haproxy process and verify that it
1204 leaves a core where expected when dying.
Willy Tarreau636848a2019-04-15 19:38:50 +02001205
Willy Tarreau610f04b2014-02-13 11:36:41 +01001206ssl-default-bind-ciphers <ciphers>
1207 This setting is only available when support for OpenSSL was built in. It sets
1208 the default string describing the list of cipher algorithms ("cipher suite")
Bertrand Jacquin8cf7c1e2019-02-03 18:35:25 +00001209 that are negotiated during the SSL/TLS handshake up to TLSv1.2 for all
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001210 "bind" lines which do not explicitly define theirs. The format of the string
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001211 is defined in "man 1 ciphers" from OpenSSL man pages. For background
1212 information and recommendations see e.g.
1213 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
1214 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
1215 cipher configuration, please check the "ssl-default-bind-ciphersuites" keyword.
1216 Please check the "bind" keyword for more information.
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001217
1218ssl-default-bind-ciphersuites <ciphersuites>
1219 This setting is only available when support for OpenSSL was built in and
1220 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default string
1221 describing the list of cipher algorithms ("cipher suite") that are negotiated
1222 during the TLSv1.3 handshake for all "bind" lines which do not explicitly define
1223 theirs. The format of the string is defined in
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001224 "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For
1225 cipher configuration for TLSv1.2 and earlier, please check the
1226 "ssl-default-bind-ciphers" keyword. Please check the "bind" keyword for more
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001227 information.
Willy Tarreau610f04b2014-02-13 11:36:41 +01001228
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001229ssl-default-bind-options [<option>]...
1230 This setting is only available when support for OpenSSL was built in. It sets
1231 default ssl-options to force on all "bind" lines. Please check the "bind"
1232 keyword to see available options.
1233
1234 Example:
1235 global
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +02001236 ssl-default-bind-options ssl-min-ver TLSv1.0 no-tls-tickets
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001237
Willy Tarreau610f04b2014-02-13 11:36:41 +01001238ssl-default-server-ciphers <ciphers>
1239 This setting is only available when support for OpenSSL was built in. It
1240 sets the default string describing the list of cipher algorithms that are
Bertrand Jacquin8cf7c1e2019-02-03 18:35:25 +00001241 negotiated during the SSL/TLS handshake up to TLSv1.2 with the server,
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001242 for all "server" lines which do not explicitly define theirs. The format of
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001243 the string is defined in "man 1 ciphers" from OpenSSL man pages. For background
1244 information and recommendations see e.g.
1245 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
1246 (https://mozilla.github.io/server-side-tls/ssl-config-generator/).
1247 For TLSv1.3 cipher configuration, please check the
1248 "ssl-default-server-ciphersuites" keyword. Please check the "server" keyword
1249 for more information.
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001250
1251ssl-default-server-ciphersuites <ciphersuites>
1252 This setting is only available when support for OpenSSL was built in and
1253 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default
1254 string describing the list of cipher algorithms that are negotiated during
1255 the TLSv1.3 handshake with the server, for all "server" lines which do not
1256 explicitly define theirs. The format of the string is defined in
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001257 "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For
1258 cipher configuration for TLSv1.2 and earlier, please check the
1259 "ssl-default-server-ciphers" keyword. Please check the "server" keyword for
1260 more information.
Willy Tarreau610f04b2014-02-13 11:36:41 +01001261
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001262ssl-default-server-options [<option>]...
1263 This setting is only available when support for OpenSSL was built in. It sets
1264 default ssl-options to force on all "server" lines. Please check the "server"
1265 keyword to see available options.
1266
Remi Gacogne47783ef2015-05-29 15:53:22 +02001267ssl-dh-param-file <file>
1268 This setting is only available when support for OpenSSL was built in. It sets
1269 the default DH parameters that are used during the SSL/TLS handshake when
1270 ephemeral Diffie-Hellman (DHE) key exchange is used, for all "bind" lines
Davor Ocelice9ed2812017-12-25 17:49:28 +01001271 which do not explicitly define theirs. It will be overridden by custom DH
Remi Gacogne47783ef2015-05-29 15:53:22 +02001272 parameters found in a bind certificate file if any. If custom DH parameters
Cyril Bonté307ee1e2015-09-28 23:16:06 +02001273 are not specified either by using ssl-dh-param-file or by setting them
1274 directly in the certificate file, pre-generated DH parameters of the size
1275 specified by tune.ssl.default-dh-param will be used. Custom parameters are
1276 known to be more secure and therefore their use is recommended.
Remi Gacogne47783ef2015-05-29 15:53:22 +02001277 Custom DH parameters may be generated by using the OpenSSL command
1278 "openssl dhparam <size>", where size should be at least 2048, as 1024-bit DH
1279 parameters should not be considered secure anymore.
1280
Emeric Brun850efd52014-01-29 12:24:34 +01001281ssl-server-verify [none|required]
1282 The default behavior for SSL verify on servers side. If specified to 'none',
1283 servers certificates are not verified. The default is 'required' except if
1284 forced using cmdline option '-dV'.
1285
Willy Tarreauabb175f2012-09-24 12:43:26 +02001286stats socket [<address:port>|<path>] [param*]
1287 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
1288 Connections to this socket will return various statistics outputs and even
1289 allow some commands to be issued to change some runtime settings. Please
Willy Tarreau1af20c72017-06-23 16:01:14 +02001290 consult section 9.3 "Unix Socket commands" of Management Guide for more
Kevin Decherf949c7202015-10-13 23:26:44 +02001291 details.
Willy Tarreau6162db22009-10-10 17:13:00 +02001292
Willy Tarreauabb175f2012-09-24 12:43:26 +02001293 All parameters supported by "bind" lines are supported, for instance to
1294 restrict access to some users or their access rights. Please consult
1295 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +02001296
1297stats timeout <timeout, in milliseconds>
1298 The default timeout on the stats socket is set to 10 seconds. It is possible
1299 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +01001300 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +02001301
1302stats maxconn <connections>
1303 By default, the stats socket is limited to 10 concurrent connections. It is
1304 possible to change this value with "stats maxconn".
1305
Willy Tarreau6a06a402007-07-15 20:15:28 +02001306uid <number>
1307 Changes the process' user ID to <number>. It is recommended that the user ID
1308 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
1309 be started with superuser privileges in order to be able to switch to another
1310 one. See also "gid" and "user".
1311
1312ulimit-n <number>
1313 Sets the maximum number of per-process file-descriptors to <number>. By
1314 default, it is automatically computed, so it is recommended not to use this
1315 option.
1316
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001317unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
1318 [ group <group> ] [ gid <gid> ]
1319
1320 Fixes common settings to UNIX listening sockets declared in "bind" statements.
1321 This is mainly used to simplify declaration of those UNIX sockets and reduce
1322 the risk of errors, since those settings are most commonly required but are
1323 also process-specific. The <prefix> setting can be used to force all socket
1324 path to be relative to that directory. This might be needed to access another
1325 component's chroot. Note that those paths are resolved before haproxy chroots
1326 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
1327 all have the same meaning as their homonyms used by the "bind" statement. If
1328 both are specified, the "bind" statement has priority, meaning that the
1329 "unix-bind" settings may be seen as process-wide default settings.
1330
Willy Tarreau1d549722016-02-16 12:41:57 +01001331unsetenv [<name> ...]
1332 Removes environment variables specified in arguments. This can be useful to
1333 hide some sensitive information that are occasionally inherited from the
1334 user's environment during some operations. Variables which did not exist are
1335 silently ignored so that after the operation, it is certain that none of
1336 these variables remain. The changes immediately take effect so that the next
1337 line in the configuration file will not see these variables. See also
1338 "setenv", "presetenv", and "resetenv".
1339
Willy Tarreau6a06a402007-07-15 20:15:28 +02001340user <user name>
1341 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
1342 See also "uid" and "group".
1343
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02001344node <name>
1345 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
1346
1347 This statement is useful in HA configurations where two or more processes or
1348 servers share the same IP address. By setting a different node-name on all
1349 nodes, it becomes easy to immediately spot what server is handling the
1350 traffic.
1351
1352description <text>
1353 Add a text that describes the instance.
1354
1355 Please note that it is required to escape certain characters (# for example)
1356 and this text is inserted into a html page so you should avoid using
1357 "<" and ">" characters.
1358
Thomas Holmesdb04f192015-05-18 13:21:39 +0100135951degrees-data-file <file path>
1360 The path of the 51Degrees data file to provide device detection services. The
Davor Ocelice9ed2812017-12-25 17:49:28 +01001361 file should be unzipped and accessible by HAProxy with relevant permissions.
Thomas Holmesdb04f192015-05-18 13:21:39 +01001362
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001363 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001364 compiled with USE_51DEGREES.
1365
Ben Shillitof25e8e52016-12-02 14:25:37 +0000136651degrees-property-name-list [<string> ...]
Thomas Holmesdb04f192015-05-18 13:21:39 +01001367 A list of 51Degrees property names to be load from the dataset. A full list
1368 of names is available on the 51Degrees website:
1369 https://51degrees.com/resources/property-dictionary
1370
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001371 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001372 compiled with USE_51DEGREES.
1373
Dragan Dosen93b38d92015-06-29 16:43:25 +0200137451degrees-property-separator <char>
Thomas Holmesdb04f192015-05-18 13:21:39 +01001375 A char that will be appended to every property value in a response header
1376 containing 51Degrees results. If not set that will be set as ','.
1377
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001378 Please note that this option is only available when haproxy has been
1379 compiled with USE_51DEGREES.
1380
138151degrees-cache-size <number>
1382 Sets the size of the 51Degrees converter cache to <number> entries. This
1383 is an LRU cache which reminds previous device detections and their results.
1384 By default, this cache is disabled.
1385
1386 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001387 compiled with USE_51DEGREES.
1388
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001389wurfl-data-file <file path>
1390 The path of the WURFL data file to provide device detection services. The
1391 file should be accessible by HAProxy with relevant permissions.
1392
1393 Please note that this option is only available when haproxy has been compiled
1394 with USE_WURFL=1.
1395
1396wurfl-information-list [<capability>]*
1397 A space-delimited list of WURFL capabilities, virtual capabilities, property
1398 names we plan to use in injected headers. A full list of capability and
1399 virtual capability names is available on the Scientiamobile website :
1400
1401 https://www.scientiamobile.com/wurflCapability
1402
1403 Valid WURFL properties are:
1404 - wurfl_id Contains the device ID of the matched device.
1405
1406 - wurfl_root_id Contains the device root ID of the matched
1407 device.
1408
1409 - wurfl_isdevroot Tells if the matched device is a root device.
1410 Possible values are "TRUE" or "FALSE".
1411
1412 - wurfl_useragent The original useragent coming with this
1413 particular web request.
1414
1415 - wurfl_api_version Contains a string representing the currently
1416 used Libwurfl API version.
1417
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001418 - wurfl_info A string containing information on the parsed
1419 wurfl.xml and its full path.
1420
1421 - wurfl_last_load_time Contains the UNIX timestamp of the last time
1422 WURFL has been loaded successfully.
1423
1424 - wurfl_normalized_useragent The normalized useragent.
1425
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001426 Please note that this option is only available when haproxy has been compiled
1427 with USE_WURFL=1.
1428
1429wurfl-information-list-separator <char>
1430 A char that will be used to separate values in a response header containing
1431 WURFL results. If not set that a comma (',') will be used by default.
1432
1433 Please note that this option is only available when haproxy has been compiled
1434 with USE_WURFL=1.
1435
1436wurfl-patch-file [<file path>]
1437 A list of WURFL patch file paths. Note that patches are loaded during startup
1438 thus before the chroot.
1439
1440 Please note that this option is only available when haproxy has been compiled
1441 with USE_WURFL=1.
1442
paulborilebad132c2019-04-18 11:57:04 +02001443wurfl-cache-size <size>
1444 Sets the WURFL Useragent cache size. For faster lookups, already processed user
1445 agents are kept in a LRU cache :
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001446 - "0" : no cache is used.
paulborilebad132c2019-04-18 11:57:04 +02001447 - <size> : size of lru cache in elements.
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001448
1449 Please note that this option is only available when haproxy has been compiled
1450 with USE_WURFL=1.
1451
William Dauchy0fec3ab2019-10-27 20:08:11 +01001452strict-limits
1453 Makes process fail at startup when a setrlimit fails. Haproxy is tries to set
1454 the best setrlimit according to what has been calculated. If it fails, it
1455 will emit a warning. Use this option if you want an explicit failure of
1456 haproxy when those limits fail. This option is disabled by default. If it has
1457 been enabled, it may still be forcibly disabled by prefixing it with the "no"
1458 keyword.
1459
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014603.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +02001461-----------------------
1462
Willy Tarreaubeb859a2018-11-22 18:07:59 +01001463busy-polling
1464 In some situations, especially when dealing with low latency on processors
1465 supporting a variable frequency or when running inside virtual machines, each
1466 time the process waits for an I/O using the poller, the processor goes back
1467 to sleep or is offered to another VM for a long time, and it causes
1468 excessively high latencies. This option provides a solution preventing the
1469 processor from sleeping by always using a null timeout on the pollers. This
1470 results in a significant latency reduction (30 to 100 microseconds observed)
1471 at the expense of a risk to overheat the processor. It may even be used with
1472 threads, in which case improperly bound threads may heavily conflict,
1473 resulting in a worse performance and high values for the CPU stolen fields
1474 in "show info" output, indicating which threads are misconfigured. It is
1475 important not to let the process run on the same processor as the network
1476 interrupts when this option is used. It is also better to avoid using it on
1477 multiple CPU threads sharing the same core. This option is disabled by
1478 default. If it has been enabled, it may still be forcibly disabled by
1479 prefixing it with the "no" keyword. It is ignored by the "select" and
1480 "poll" pollers.
1481
William Dauchy3894d972019-12-28 15:36:02 +01001482 This option is automatically disabled on old processes in the context of
1483 seamless reload; it avoids too much cpu conflicts when multiple processes
1484 stay around for some time waiting for the end of their current connections.
1485
Willy Tarreau1746eec2014-04-25 10:46:47 +02001486max-spread-checks <delay in milliseconds>
1487 By default, haproxy tries to spread the start of health checks across the
1488 smallest health check interval of all the servers in a farm. The principle is
1489 to avoid hammering services running on the same server. But when using large
1490 check intervals (10 seconds or more), the last servers in the farm take some
1491 time before starting to be tested, which can be a problem. This parameter is
1492 used to enforce an upper bound on delay between the first and the last check,
1493 even if the servers' check intervals are larger. When servers run with
1494 shorter intervals, their intervals will be respected though.
1495
Willy Tarreau6a06a402007-07-15 20:15:28 +02001496maxconn <number>
1497 Sets the maximum per-process number of concurrent connections to <number>. It
1498 is equivalent to the command-line argument "-n". Proxies will stop accepting
1499 connections when this limit is reached. The "ulimit-n" parameter is
Willy Tarreau8274e102014-06-19 15:31:25 +02001500 automatically adjusted according to this value. See also "ulimit-n". Note:
1501 the "select" poller cannot reliably use more than 1024 file descriptors on
1502 some platforms. If your platform only supports select and reports "select
1503 FAILED" on startup, you need to reduce maxconn until it works (slightly
Willy Tarreaub28f3442019-03-04 08:13:43 +01001504 below 500 in general). If this value is not set, it will automatically be
1505 calculated based on the current file descriptors limit reported by the
1506 "ulimit -n" command, possibly reduced to a lower value if a memory limit
1507 is enforced, based on the buffer size, memory allocated to compression, SSL
1508 cache size, and use or not of SSL and the associated maxsslconn (which can
1509 also be automatic).
Willy Tarreau6a06a402007-07-15 20:15:28 +02001510
Willy Tarreau81c25d02011-09-07 15:17:21 +02001511maxconnrate <number>
1512 Sets the maximum per-process number of connections per second to <number>.
1513 Proxies will stop accepting connections when this limit is reached. It can be
1514 used to limit the global capacity regardless of each frontend capacity. It is
1515 important to note that this can only be used as a service protection measure,
1516 as there will not necessarily be a fair share between frontends when the
1517 limit is reached, so it's a good idea to also limit each frontend to some
1518 value close to its expected share. Also, lowering tune.maxaccept can improve
1519 fairness.
1520
William Lallemandd85f9172012-11-09 17:05:39 +01001521maxcomprate <number>
1522 Sets the maximum per-process input compression rate to <number> kilobytes
Davor Ocelice9ed2812017-12-25 17:49:28 +01001523 per second. For each session, if the maximum is reached, the compression
William Lallemandd85f9172012-11-09 17:05:39 +01001524 level will be decreased during the session. If the maximum is reached at the
1525 beginning of a session, the session will not compress at all. If the maximum
1526 is not reached, the compression level will be increased up to
Davor Ocelice9ed2812017-12-25 17:49:28 +01001527 tune.comp.maxlevel. A value of zero means there is no limit, this is the
William Lallemandd85f9172012-11-09 17:05:39 +01001528 default value.
1529
William Lallemand072a2bf2012-11-20 17:01:01 +01001530maxcompcpuusage <number>
1531 Sets the maximum CPU usage HAProxy can reach before stopping the compression
1532 for new requests or decreasing the compression level of current requests.
1533 It works like 'maxcomprate' but measures CPU usage instead of incoming data
1534 bandwidth. The value is expressed in percent of the CPU used by haproxy. In
1535 case of multiple processes (nbproc > 1), each process manages its individual
1536 usage. A value of 100 disable the limit. The default value is 100. Setting
1537 a lower value will prevent the compression work from slowing the whole
1538 process down and from introducing high latencies.
1539
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001540maxpipes <number>
1541 Sets the maximum per-process number of pipes to <number>. Currently, pipes
1542 are only used by kernel-based tcp splicing. Since a pipe contains two file
1543 descriptors, the "ulimit-n" value will be increased accordingly. The default
1544 value is maxconn/4, which seems to be more than enough for most heavy usages.
1545 The splice code dynamically allocates and releases pipes, and can fall back
1546 to standard copy, so setting this value too low may only impact performance.
1547
Willy Tarreau93e7c002013-10-07 18:51:07 +02001548maxsessrate <number>
1549 Sets the maximum per-process number of sessions per second to <number>.
1550 Proxies will stop accepting connections when this limit is reached. It can be
1551 used to limit the global capacity regardless of each frontend capacity. It is
1552 important to note that this can only be used as a service protection measure,
1553 as there will not necessarily be a fair share between frontends when the
1554 limit is reached, so it's a good idea to also limit each frontend to some
1555 value close to its expected share. Also, lowering tune.maxaccept can improve
1556 fairness.
1557
Willy Tarreau403edff2012-09-06 11:58:37 +02001558maxsslconn <number>
1559 Sets the maximum per-process number of concurrent SSL connections to
1560 <number>. By default there is no SSL-specific limit, which means that the
1561 global maxconn setting will apply to all connections. Setting this limit
1562 avoids having openssl use too much memory and crash when malloc returns NULL
1563 (since it unfortunately does not reliably check for such conditions). Note
1564 that the limit applies both to incoming and outgoing connections, so one
1565 connection which is deciphered then ciphered accounts for 2 SSL connections.
Willy Tarreaud0256482015-01-15 21:45:22 +01001566 If this value is not set, but a memory limit is enforced, this value will be
1567 automatically computed based on the memory limit, maxconn, the buffer size,
1568 memory allocated to compression, SSL cache size, and use of SSL in either
1569 frontends, backends or both. If neither maxconn nor maxsslconn are specified
1570 when there is a memory limit, haproxy will automatically adjust these values
1571 so that 100% of the connections can be made over SSL with no risk, and will
1572 consider the sides where it is enabled (frontend, backend, both).
Willy Tarreau403edff2012-09-06 11:58:37 +02001573
Willy Tarreaue43d5322013-10-07 20:01:52 +02001574maxsslrate <number>
1575 Sets the maximum per-process number of SSL sessions per second to <number>.
1576 SSL listeners will stop accepting connections when this limit is reached. It
1577 can be used to limit the global SSL CPU usage regardless of each frontend
1578 capacity. It is important to note that this can only be used as a service
1579 protection measure, as there will not necessarily be a fair share between
1580 frontends when the limit is reached, so it's a good idea to also limit each
1581 frontend to some value close to its expected share. It is also important to
1582 note that the sessions are accounted before they enter the SSL stack and not
1583 after, which also protects the stack against bad handshakes. Also, lowering
1584 tune.maxaccept can improve fairness.
1585
William Lallemand9d5f5482012-11-07 16:12:57 +01001586maxzlibmem <number>
1587 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
1588 When the maximum amount is reached, future sessions will not compress as long
1589 as RAM is unavailable. When sets to 0, there is no limit.
William Lallemande3a7d992012-11-20 11:25:20 +01001590 The default value is 0. The value is available in bytes on the UNIX socket
1591 with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is
1592 "ZlibMemUsage" in bytes.
1593
Willy Tarreau6a06a402007-07-15 20:15:28 +02001594noepoll
1595 Disables the use of the "epoll" event polling system on Linux. It is
1596 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +01001597 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001598
1599nokqueue
1600 Disables the use of the "kqueue" event polling system on BSD. It is
1601 equivalent to the command-line argument "-dk". The next polling system
1602 used will generally be "poll". See also "nopoll".
1603
Emmanuel Hocdet0ba4f482019-04-08 16:53:32 +00001604noevports
1605 Disables the use of the event ports event polling system on SunOS systems
1606 derived from Solaris 10 and later. It is equivalent to the command-line
1607 argument "-dv". The next polling system used will generally be "poll". See
1608 also "nopoll".
1609
Willy Tarreau6a06a402007-07-15 20:15:28 +02001610nopoll
1611 Disables the use of the "poll" event polling system. It is equivalent to the
1612 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001613 It should never be needed to disable "poll" since it's available on all
Emmanuel Hocdet0ba4f482019-04-08 16:53:32 +00001614 platforms supported by HAProxy. See also "nokqueue", "noepoll" and
1615 "noevports".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001616
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001617nosplice
1618 Disables the use of kernel tcp splicing between sockets on Linux. It is
Davor Ocelice9ed2812017-12-25 17:49:28 +01001619 equivalent to the command line argument "-dS". Data will then be copied
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001620 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001621 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001622 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
1623 be used. This option makes it easier to globally disable kernel splicing in
1624 case of doubt. See also "option splice-auto", "option splice-request" and
1625 "option splice-response".
1626
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001627nogetaddrinfo
1628 Disables the use of getaddrinfo(3) for name resolving. It is equivalent to
1629 the command line argument "-dG". Deprecated gethostbyname(3) will be used.
1630
Lukas Tribusa0bcbdc2016-09-12 21:42:20 +00001631noreuseport
1632 Disables the use of SO_REUSEPORT - see socket(7). It is equivalent to the
1633 command line argument "-dR".
1634
Willy Tarreaud2d33482019-04-25 17:09:07 +02001635profiling.tasks { auto | on | off }
1636 Enables ('on') or disables ('off') per-task CPU profiling. When set to 'auto'
1637 the profiling automatically turns on a thread when it starts to suffer from
1638 an average latency of 1000 microseconds or higher as reported in the
1639 "avg_loop_us" activity field, and automatically turns off when the latency
John Roeslerfb2fce12019-07-10 15:45:51 -05001640 returns below 990 microseconds (this value is an average over the last 1024
Willy Tarreaud2d33482019-04-25 17:09:07 +02001641 loops so it does not vary quickly and tends to significantly smooth short
1642 spikes). It may also spontaneously trigger from time to time on overloaded
1643 systems, containers, or virtual machines, or when the system swaps (which
1644 must absolutely never happen on a load balancer).
1645
1646 CPU profiling per task can be very convenient to report where the time is
1647 spent and which requests have what effect on which other request. Enabling
1648 it will typically affect the overall's performance by less than 1%, thus it
1649 is recommended to leave it to the default 'auto' value so that it only
1650 operates when a problem is identified. This feature requires a system
Willy Tarreau75c62c22018-11-22 11:02:09 +01001651 supporting the clock_gettime(2) syscall with clock identifiers
1652 CLOCK_MONOTONIC and CLOCK_THREAD_CPUTIME_ID, otherwise the reported time will
1653 be zero. This option may be changed at run time using "set profiling" on the
1654 CLI.
1655
Willy Tarreaufe255b72007-10-14 23:09:26 +02001656spread-checks <0..50, in percent>
Simon Hormand60d6912013-11-25 10:46:36 +09001657 Sometimes it is desirable to avoid sending agent and health checks to
1658 servers at exact intervals, for instance when many logical servers are
1659 located on the same physical server. With the help of this parameter, it
1660 becomes possible to add some randomness in the check interval between 0
1661 and +/- 50%. A value between 2 and 5 seems to show good results. The
1662 default value remains at 0.
Willy Tarreaufe255b72007-10-14 23:09:26 +02001663
Davor Ocelice9ed2812017-12-25 17:49:28 +01001664ssl-engine <name> [algo <comma-separated list of algorithms>]
Grant Zhang872f9c22017-01-21 01:10:18 +00001665 Sets the OpenSSL engine to <name>. List of valid values for <name> may be
Davor Ocelice9ed2812017-12-25 17:49:28 +01001666 obtained using the command "openssl engine". This statement may be used
Grant Zhang872f9c22017-01-21 01:10:18 +00001667 multiple times, it will simply enable multiple crypto engines. Referencing an
1668 unsupported engine will prevent haproxy from starting. Note that many engines
1669 will lead to lower HTTPS performance than pure software with recent
1670 processors. The optional command "algo" sets the default algorithms an ENGINE
1671 will supply using the OPENSSL function ENGINE_set_default_string(). A value
Davor Ocelice9ed2812017-12-25 17:49:28 +01001672 of "ALL" uses the engine for all cryptographic operations. If no list of
1673 algo is specified then the value of "ALL" is used. A comma-separated list
Grant Zhang872f9c22017-01-21 01:10:18 +00001674 of different algorithms may be specified, including: RSA, DSA, DH, EC, RAND,
1675 CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. This is the same format that
1676 openssl configuration file uses:
1677 https://www.openssl.org/docs/man1.0.2/apps/config.html
1678
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00001679ssl-mode-async
1680 Adds SSL_MODE_ASYNC mode to the SSL context. This enables asynchronous TLS
Emeric Brun3854e012017-05-17 20:42:48 +02001681 I/O operations if asynchronous capable SSL engines are used. The current
Emeric Brunb5e42a82017-06-06 12:35:14 +00001682 implementation supports a maximum of 32 engines. The Openssl ASYNC API
1683 doesn't support moving read/write buffers and is not compliant with
1684 haproxy's buffer management. So the asynchronous mode is disabled on
John Roeslerfb2fce12019-07-10 15:45:51 -05001685 read/write operations (it is only enabled during initial and renegotiation
Emeric Brunb5e42a82017-06-06 12:35:14 +00001686 handshakes).
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00001687
Willy Tarreau33cb0652014-12-23 22:52:37 +01001688tune.buffers.limit <number>
1689 Sets a hard limit on the number of buffers which may be allocated per process.
1690 The default value is zero which means unlimited. The minimum non-zero value
1691 will always be greater than "tune.buffers.reserve" and should ideally always
1692 be about twice as large. Forcing this value can be particularly useful to
1693 limit the amount of memory a process may take, while retaining a sane
Davor Ocelice9ed2812017-12-25 17:49:28 +01001694 behavior. When this limit is reached, sessions which need a buffer wait for
Willy Tarreau33cb0652014-12-23 22:52:37 +01001695 another one to be released by another session. Since buffers are dynamically
1696 allocated and released, the waiting time is very short and not perceptible
1697 provided that limits remain reasonable. In fact sometimes reducing the limit
1698 may even increase performance by increasing the CPU cache's efficiency. Tests
1699 have shown good results on average HTTP traffic with a limit to 1/10 of the
1700 expected global maxconn setting, which also significantly reduces memory
1701 usage. The memory savings come from the fact that a number of connections
1702 will not allocate 2*tune.bufsize. It is best not to touch this value unless
1703 advised to do so by an haproxy core developer.
1704
Willy Tarreau1058ae72014-12-23 22:40:40 +01001705tune.buffers.reserve <number>
1706 Sets the number of buffers which are pre-allocated and reserved for use only
1707 during memory shortage conditions resulting in failed memory allocations. The
1708 minimum value is 2 and is also the default. There is no reason a user would
1709 want to change this value, it's mostly aimed at haproxy core developers.
1710
Willy Tarreau27a674e2009-08-17 07:23:33 +02001711tune.bufsize <number>
1712 Sets the buffer size to this size (in bytes). Lower values allow more
1713 sessions to coexist in the same amount of RAM, and higher values allow some
1714 applications with very large cookies to work. The default value is 16384 and
1715 can be changed at build time. It is strongly recommended not to change this
1716 from the default value, as very low values will break some services such as
1717 statistics, and values larger than default size will increase memory usage,
1718 possibly causing the system to run out of memory. At least the global maxconn
Willy Tarreau45a66cc2017-11-24 11:28:00 +01001719 parameter should be decreased by the same factor as this one is increased. In
1720 addition, use of HTTP/2 mandates that this value must be 16384 or more. If an
1721 HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +04001722 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
Willy Tarreauc77d3642018-12-12 06:19:42 +01001723 than this size, haproxy will return HTTP 502 (Bad Gateway). Note that the
1724 value set using this parameter will automatically be rounded up to the next
1725 multiple of 8 on 32-bit machines and 16 on 64-bit machines.
Willy Tarreau27a674e2009-08-17 07:23:33 +02001726
Willy Tarreau43961d52010-10-04 20:39:20 +02001727tune.chksize <number>
1728 Sets the check buffer size to this size (in bytes). Higher values may help
1729 find string or regex patterns in very large pages, though doing so may imply
1730 more memory and CPU usage. The default value is 16384 and can be changed at
1731 build time. It is not recommended to change this value, but to use better
1732 checks whenever possible.
1733
William Lallemandf3747832012-11-09 12:33:10 +01001734tune.comp.maxlevel <number>
1735 Sets the maximum compression level. The compression level affects CPU
1736 usage during compression. This value affects CPU usage during compression.
1737 Each session using compression initializes the compression algorithm with
1738 this value. The default value is 1.
1739
Willy Tarreauc299e1e2019-02-27 11:35:12 +01001740tune.fail-alloc
1741 If compiled with DEBUG_FAIL_ALLOC, gives the percentage of chances an
1742 allocation attempt fails. Must be between 0 (no failure) and 100 (no
1743 success). This is useful to debug and make sure memory failures are handled
1744 gracefully.
1745
Willy Tarreaufe20e5b2017-07-27 11:42:14 +02001746tune.h2.header-table-size <number>
1747 Sets the HTTP/2 dynamic header table size. It defaults to 4096 bytes and
1748 cannot be larger than 65536 bytes. A larger value may help certain clients
1749 send more compact requests, depending on their capabilities. This amount of
1750 memory is consumed for each HTTP/2 connection. It is recommended not to
1751 change it.
1752
Willy Tarreaue6baec02017-07-27 11:45:11 +02001753tune.h2.initial-window-size <number>
1754 Sets the HTTP/2 initial window size, which is the number of bytes the client
Davor Ocelice9ed2812017-12-25 17:49:28 +01001755 can upload before waiting for an acknowledgment from haproxy. This setting
1756 only affects payload contents (i.e. the body of POST requests), not headers.
Willy Tarreaue6baec02017-07-27 11:45:11 +02001757 The default value is 65535, which roughly allows up to 5 Mbps of upload
1758 bandwidth per client over a network showing a 100 ms ping time, or 500 Mbps
1759 over a 1-ms local network. It can make sense to increase this value to allow
1760 faster uploads, or to reduce it to increase fairness when dealing with many
1761 clients. It doesn't affect resource usage.
1762
Willy Tarreau5242ef82017-07-27 11:47:28 +02001763tune.h2.max-concurrent-streams <number>
1764 Sets the HTTP/2 maximum number of concurrent streams per connection (ie the
1765 number of outstanding requests on a single connection). The default value is
1766 100. A larger one may slightly improve page load time for complex sites when
1767 visited over high latency networks, but increases the amount of resources a
1768 single client may allocate. A value of zero disables the limit so a single
1769 client may create as many streams as allocatable by haproxy. It is highly
1770 recommended not to change this value.
1771
Willy Tarreaua24b35c2019-02-21 13:24:36 +01001772tune.h2.max-frame-size <number>
1773 Sets the HTTP/2 maximum frame size that haproxy announces it is willing to
1774 receive to its peers. The default value is the largest between 16384 and the
1775 buffer size (tune.bufsize). In any case, haproxy will not announce support
1776 for frame sizes larger than buffers. The main purpose of this setting is to
1777 allow to limit the maximum frame size setting when using large buffers. Too
1778 large frame sizes might have performance impact or cause some peers to
1779 misbehave. It is highly recommended not to change this value.
1780
Willy Tarreau193b8c62012-11-22 00:17:38 +01001781tune.http.cookielen <number>
1782 Sets the maximum length of captured cookies. This is the maximum value that
1783 the "capture cookie xxx len yyy" will be allowed to take, and any upper value
1784 will automatically be truncated to this one. It is important not to set too
1785 high a value because all cookie captures still allocate this size whatever
1786 their configured value (they share a same pool). This value is per request
1787 per response, so the memory allocated is twice this value per connection.
1788 When not specified, the limit is set to 63 characters. It is recommended not
1789 to change this value.
1790
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001791tune.http.logurilen <number>
Davor Ocelice9ed2812017-12-25 17:49:28 +01001792 Sets the maximum length of request URI in logs. This prevents truncating long
1793 request URIs with valuable query strings in log lines. This is not related
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001794 to syslog limits. If you increase this limit, you may also increase the
Davor Ocelice9ed2812017-12-25 17:49:28 +01001795 'log ... len yyy' parameter. Your syslog daemon may also need specific
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001796 configuration directives too.
1797 The default value is 1024.
1798
Willy Tarreauac1932d2011-10-24 19:14:41 +02001799tune.http.maxhdr <number>
1800 Sets the maximum number of headers in a request. When a request comes with a
1801 number of headers greater than this value (including the first line), it is
1802 rejected with a "400 Bad Request" status code. Similarly, too large responses
1803 are blocked with "502 Bad Gateway". The default value is 101, which is enough
1804 for all usages, considering that the widely deployed Apache server uses the
1805 same limit. It can be useful to push this limit further to temporarily allow
Christopher Faulet50174f32017-06-21 16:31:35 +02001806 a buggy application to work by the time it gets fixed. The accepted range is
1807 1..32767. Keep in mind that each new header consumes 32bits of memory for
1808 each session, so don't push this limit too high.
Willy Tarreauac1932d2011-10-24 19:14:41 +02001809
Willy Tarreau7e312732014-02-12 16:35:14 +01001810tune.idletimer <timeout>
1811 Sets the duration after which haproxy will consider that an empty buffer is
1812 probably associated with an idle stream. This is used to optimally adjust
1813 some packet sizes while forwarding large and small data alternatively. The
1814 decision to use splice() or to send large buffers in SSL is modulated by this
1815 parameter. The value is in milliseconds between 0 and 65535. A value of zero
1816 means that haproxy will not try to detect idle streams. The default is 1000,
Davor Ocelice9ed2812017-12-25 17:49:28 +01001817 which seems to correctly detect end user pauses (e.g. read a page before
John Roeslerfb2fce12019-07-10 15:45:51 -05001818 clicking). There should be no reason for changing this value. Please check
Willy Tarreau7e312732014-02-12 16:35:14 +01001819 tune.ssl.maxrecord below.
1820
Willy Tarreau7ac908b2019-02-27 12:02:18 +01001821tune.listener.multi-queue { on | off }
1822 Enables ('on') or disables ('off') the listener's multi-queue accept which
1823 spreads the incoming traffic to all threads a "bind" line is allowed to run
1824 on instead of taking them for itself. This provides a smoother traffic
1825 distribution and scales much better, especially in environments where threads
1826 may be unevenly loaded due to external activity (network interrupts colliding
1827 with one thread for example). This option is enabled by default, but it may
1828 be forcefully disabled for troubleshooting or for situations where it is
1829 estimated that the operating system already provides a good enough
1830 distribution and connections are extremely short-lived.
1831
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001832tune.lua.forced-yield <number>
1833 This directive forces the Lua engine to execute a yield each <number> of
Tim Düsterhus4896c442016-11-29 02:15:19 +01001834 instructions executed. This permits interrupting a long script and allows the
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001835 HAProxy scheduler to process other tasks like accepting connections or
1836 forwarding traffic. The default value is 10000 instructions. If HAProxy often
Davor Ocelice9ed2812017-12-25 17:49:28 +01001837 executes some Lua code but more responsiveness is required, this value can be
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001838 lowered. If the Lua code is quite long and its result is absolutely required
1839 to process the data, the <number> can be increased.
1840
Willy Tarreau32f61e22015-03-18 17:54:59 +01001841tune.lua.maxmem
1842 Sets the maximum amount of RAM in megabytes per process usable by Lua. By
1843 default it is zero which means unlimited. It is important to set a limit to
1844 ensure that a bug in a script will not result in the system running out of
1845 memory.
1846
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001847tune.lua.session-timeout <timeout>
1848 This is the execution timeout for the Lua sessions. This is useful for
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02001849 preventing infinite loops or spending too much time in Lua. This timeout
1850 counts only the pure Lua runtime. If the Lua does a sleep, the sleep is
Davor Ocelice9ed2812017-12-25 17:49:28 +01001851 not taken in account. The default timeout is 4s.
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001852
1853tune.lua.task-timeout <timeout>
1854 Purpose is the same as "tune.lua.session-timeout", but this timeout is
1855 dedicated to the tasks. By default, this timeout isn't set because a task may
1856 remain alive during of the lifetime of HAProxy. For example, a task used to
1857 check servers.
1858
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02001859tune.lua.service-timeout <timeout>
1860 This is the execution timeout for the Lua services. This is useful for
1861 preventing infinite loops or spending too much time in Lua. This timeout
1862 counts only the pure Lua runtime. If the Lua does a sleep, the sleep is
Davor Ocelice9ed2812017-12-25 17:49:28 +01001863 not taken in account. The default timeout is 4s.
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02001864
Willy Tarreaua0250ba2008-01-06 11:22:57 +01001865tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +01001866 Sets the maximum number of consecutive connections a process may accept in a
1867 row before switching to other work. In single process mode, higher numbers
1868 give better performance at high connection rates. However in multi-process
1869 modes, keeping a bit of fairness between processes generally is better to
1870 increase performance. This value applies individually to each listener, so
1871 that the number of processes a listener is bound to is taken into account.
1872 This value defaults to 64. In multi-process mode, it is divided by twice
1873 the number of processes the listener is bound to. Setting this value to -1
1874 completely disables the limitation. It should normally not be needed to tweak
1875 this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +01001876
1877tune.maxpollevents <number>
1878 Sets the maximum amount of events that can be processed at once in a call to
1879 the polling system. The default value is adapted to the operating system. It
1880 has been noticed that reducing it below 200 tends to slightly decrease
1881 latency at the expense of network bandwidth, and increasing it above 200
1882 tends to trade latency for slightly increased bandwidth.
1883
Willy Tarreau27a674e2009-08-17 07:23:33 +02001884tune.maxrewrite <number>
1885 Sets the reserved buffer space to this size in bytes. The reserved space is
1886 used for header rewriting or appending. The first reads on sockets will never
1887 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
1888 bufsize, though that does not make much sense since there are rarely large
1889 numbers of headers to add. Setting it too high prevents processing of large
1890 requests or responses. Setting it too low prevents addition of new headers
1891 to already large requests or to POST requests. It is generally wise to set it
1892 to about 1024. It is automatically readjusted to half of bufsize if it is
1893 larger than that. This means you don't have to worry about it when changing
1894 bufsize.
1895
Willy Tarreauf3045d22015-04-29 16:24:50 +02001896tune.pattern.cache-size <number>
1897 Sets the size of the pattern lookup cache to <number> entries. This is an LRU
1898 cache which reminds previous lookups and their results. It is used by ACLs
1899 and maps on slow pattern lookups, namely the ones using the "sub", "reg",
1900 "dir", "dom", "end", "bin" match methods as well as the case-insensitive
1901 strings. It applies to pattern expressions which means that it will be able
1902 to memorize the result of a lookup among all the patterns specified on a
1903 configuration line (including all those loaded from files). It automatically
1904 invalidates entries which are updated using HTTP actions or on the CLI. The
1905 default cache size is set to 10000 entries, which limits its footprint to
Willy Tarreau403bfbb2019-10-23 06:59:31 +02001906 about 5 MB per process/thread on 32-bit systems and 8 MB per process/thread
1907 on 64-bit systems, as caches are thread/process local. There is a very low
Willy Tarreauf3045d22015-04-29 16:24:50 +02001908 risk of collision in this cache, which is in the order of the size of the
1909 cache divided by 2^64. Typically, at 10000 requests per second with the
1910 default cache size of 10000 entries, there's 1% chance that a brute force
1911 attack could cause a single collision after 60 years, or 0.1% after 6 years.
1912 This is considered much lower than the risk of a memory corruption caused by
1913 aging components. If this is not acceptable, the cache can be disabled by
1914 setting this parameter to 0.
1915
Willy Tarreaubd9a0a72011-10-23 21:14:29 +02001916tune.pipesize <number>
1917 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
1918 are the default size for the system. But sometimes when using TCP splicing,
1919 it can improve performance to increase pipe sizes, especially if it is
1920 suspected that pipes are not filled and that many calls to splice() are
1921 performed. This has an impact on the kernel's memory footprint, so this must
1922 not be changed if impacts are not understood.
1923
Olivier Houchard88698d92019-04-16 19:07:22 +02001924tune.pool-low-fd-ratio <number>
1925 This setting sets the max number of file descriptors (in percentage) used by
1926 haproxy globally against the maximum number of file descriptors haproxy can
1927 use before we stop putting connection into the idle pool for reuse. The
1928 default is 20.
1929
1930tune.pool-high-fd-ratio <number>
1931 This setting sets the max number of file descriptors (in percentage) used by
1932 haproxy globally against the maximum number of file descriptors haproxy can
1933 use before we start killing idle connections when we can't reuse a connection
1934 and we have to create a new one. The default is 25 (one quarter of the file
1935 descriptor will mean that roughly half of the maximum front connections can
1936 keep an idle connection behind, anything beyond this probably doesn't make
John Roeslerfb2fce12019-07-10 15:45:51 -05001937 much sense in the general case when targeting connection reuse).
Olivier Houchard88698d92019-04-16 19:07:22 +02001938
Willy Tarreaue803de22010-01-21 17:43:04 +01001939tune.rcvbuf.client <number>
1940tune.rcvbuf.server <number>
1941 Forces the kernel socket receive buffer size on the client or the server side
1942 to the specified value in bytes. This value applies to all TCP/HTTP frontends
1943 and backends. It should normally never be set, and the default size (0) lets
John Roeslerfb2fce12019-07-10 15:45:51 -05001944 the kernel auto-tune this value depending on the amount of available memory.
Davor Ocelice9ed2812017-12-25 17:49:28 +01001945 However it can sometimes help to set it to very low values (e.g. 4096) in
Willy Tarreaue803de22010-01-21 17:43:04 +01001946 order to save kernel memory by preventing it from buffering too large amounts
1947 of received data. Lower values will significantly increase CPU usage though.
1948
Willy Tarreaub22fc302015-12-14 12:04:35 +01001949tune.recv_enough <number>
Davor Ocelice9ed2812017-12-25 17:49:28 +01001950 HAProxy uses some hints to detect that a short read indicates the end of the
Willy Tarreaub22fc302015-12-14 12:04:35 +01001951 socket buffers. One of them is that a read returns more than <recv_enough>
1952 bytes, which defaults to 10136 (7 segments of 1448 each). This default value
1953 may be changed by this setting to better deal with workloads involving lots
1954 of short messages such as telnet or SSH sessions.
1955
Olivier Houchard1599b802018-05-24 18:59:04 +02001956tune.runqueue-depth <number>
John Roeslerfb2fce12019-07-10 15:45:51 -05001957 Sets the maximum amount of task that can be processed at once when running
Olivier Houchard1599b802018-05-24 18:59:04 +02001958 tasks. The default value is 200. Increasing it may incur latency when
1959 dealing with I/Os, making it too small can incur extra overhead.
1960
Willy Tarreaue803de22010-01-21 17:43:04 +01001961tune.sndbuf.client <number>
1962tune.sndbuf.server <number>
1963 Forces the kernel socket send buffer size on the client or the server side to
1964 the specified value in bytes. This value applies to all TCP/HTTP frontends
1965 and backends. It should normally never be set, and the default size (0) lets
John Roeslerfb2fce12019-07-10 15:45:51 -05001966 the kernel auto-tune this value depending on the amount of available memory.
Davor Ocelice9ed2812017-12-25 17:49:28 +01001967 However it can sometimes help to set it to very low values (e.g. 4096) in
Willy Tarreaue803de22010-01-21 17:43:04 +01001968 order to save kernel memory by preventing it from buffering too large amounts
1969 of received data. Lower values will significantly increase CPU usage though.
1970 Another use case is to prevent write timeouts with extremely slow clients due
1971 to the kernel waiting for a large part of the buffer to be read before
1972 notifying haproxy again.
1973
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001974tune.ssl.cachesize <number>
Emeric Brunaf9619d2012-11-28 18:47:52 +01001975 Sets the size of the global SSL session cache, in a number of blocks. A block
1976 is large enough to contain an encoded session without peer certificate.
1977 An encoded session with peer certificate is stored in multiple blocks
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001978 depending on the size of the peer certificate. A block uses approximately
Emeric Brunaf9619d2012-11-28 18:47:52 +01001979 200 bytes of memory. The default value may be forced at build time, otherwise
Davor Ocelice9ed2812017-12-25 17:49:28 +01001980 defaults to 20000. When the cache is full, the most idle entries are purged
Emeric Brunaf9619d2012-11-28 18:47:52 +01001981 and reassigned. Higher values reduce the occurrence of such a purge, hence
1982 the number of CPU-intensive SSL handshakes by ensuring that all users keep
1983 their session as long as possible. All entries are pre-allocated upon startup
Emeric Brun22890a12012-12-28 14:41:32 +01001984 and are shared between all processes if "nbproc" is greater than 1. Setting
1985 this value to 0 disables the SSL session cache.
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001986
Emeric Brun8dc60392014-05-09 13:52:00 +02001987tune.ssl.force-private-cache
Lukas Tribus27935782018-10-01 02:00:16 +02001988 This option disables SSL session cache sharing between all processes. It
Emeric Brun8dc60392014-05-09 13:52:00 +02001989 should normally not be used since it will force many renegotiations due to
1990 clients hitting a random process. But it may be required on some operating
1991 systems where none of the SSL cache synchronization method may be used. In
1992 this case, adding a first layer of hash-based load balancing before the SSL
1993 layer might limit the impact of the lack of session sharing.
1994
Emeric Brun4f65bff2012-11-16 15:11:00 +01001995tune.ssl.lifetime <timeout>
1996 Sets how long a cached SSL session may remain valid. This time is expressed
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001997 in seconds and defaults to 300 (5 min). It is important to understand that it
Emeric Brun4f65bff2012-11-16 15:11:00 +01001998 does not guarantee that sessions will last that long, because if the cache is
1999 full, the longest idle sessions will be purged despite their configured
2000 lifetime. The real usefulness of this setting is to prevent sessions from
2001 being used for too long.
2002
Willy Tarreaubfd59462013-02-21 07:46:09 +01002003tune.ssl.maxrecord <number>
2004 Sets the maximum amount of bytes passed to SSL_write() at a time. Default
2005 value 0 means there is no limit. Over SSL/TLS, the client can decipher the
2006 data only once it has received a full record. With large records, it means
2007 that clients might have to download up to 16kB of data before starting to
2008 process them. Limiting the value can improve page load times on browsers
2009 located over high latency or low bandwidth networks. It is suggested to find
2010 optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over
2011 Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled),
2012 keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and
2013 2859 gave good results during tests. Use "strace -e trace=write" to find the
Davor Ocelice9ed2812017-12-25 17:49:28 +01002014 best value. HAProxy will automatically switch to this setting after an idle
Willy Tarreau7e312732014-02-12 16:35:14 +01002015 stream has been detected (see tune.idletimer above).
Willy Tarreaubfd59462013-02-21 07:46:09 +01002016
Remi Gacognef46cd6e2014-06-12 14:58:40 +02002017tune.ssl.default-dh-param <number>
2018 Sets the maximum size of the Diffie-Hellman parameters used for generating
2019 the ephemeral/temporary Diffie-Hellman key in case of DHE key exchange. The
2020 final size will try to match the size of the server's RSA (or DSA) key (e.g,
2021 a 2048 bits temporary DH key for a 2048 bits RSA key), but will not exceed
2022 this maximum value. Default value if 1024. Only 1024 or higher values are
2023 allowed. Higher values will increase the CPU load, and values greater than
2024 1024 bits are not supported by Java 7 and earlier clients. This value is not
Remi Gacogne47783ef2015-05-29 15:53:22 +02002025 used if static Diffie-Hellman parameters are supplied either directly
2026 in the certificate file or by using the ssl-dh-param-file parameter.
Remi Gacognef46cd6e2014-06-12 14:58:40 +02002027
Christopher Faulet31af49d2015-06-09 17:29:50 +02002028tune.ssl.ssl-ctx-cache-size <number>
2029 Sets the size of the cache used to store generated certificates to <number>
2030 entries. This is a LRU cache. Because generating a SSL certificate
2031 dynamically is expensive, they are cached. The default cache size is set to
2032 1000 entries.
2033
Thierry FOURNIER5bf77322017-02-25 12:45:22 +01002034tune.ssl.capture-cipherlist-size <number>
2035 Sets the maximum size of the buffer used for capturing client-hello cipher
2036 list. If the value is 0 (default value) the capture is disabled, otherwise
2037 a buffer is allocated for each SSL/TLS connection.
2038
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02002039tune.vars.global-max-size <size>
Christopher Fauletff2613e2016-11-09 11:36:17 +01002040tune.vars.proc-max-size <size>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02002041tune.vars.reqres-max-size <size>
2042tune.vars.sess-max-size <size>
2043tune.vars.txn-max-size <size>
Christopher Fauletff2613e2016-11-09 11:36:17 +01002044 These five tunes help to manage the maximum amount of memory used by the
2045 variables system. "global" limits the overall amount of memory available for
2046 all scopes. "proc" limits the memory for the process scope, "sess" limits the
2047 memory for the session scope, "txn" for the transaction scope, and "reqres"
2048 limits the memory for each request or response processing.
2049 Memory accounting is hierarchical, meaning more coarse grained limits include
2050 the finer grained ones: "proc" includes "sess", "sess" includes "txn", and
2051 "txn" includes "reqres".
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02002052
Daniel Schneller0b547052016-03-21 20:46:57 +01002053 For example, when "tune.vars.sess-max-size" is limited to 100,
2054 "tune.vars.txn-max-size" and "tune.vars.reqres-max-size" cannot exceed
2055 100 either. If we create a variable "txn.var" that contains 100 bytes,
2056 all available space is consumed.
2057 Notice that exceeding the limits at runtime will not result in an error
2058 message, but values might be cut off or corrupted. So make sure to accurately
2059 plan for the amount of space needed to store all your variables.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02002060
William Lallemanda509e4c2012-11-07 16:54:34 +01002061tune.zlib.memlevel <number>
2062 Sets the memLevel parameter in zlib initialization for each session. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03002063 defines how much memory should be allocated for the internal compression
William Lallemanda509e4c2012-11-07 16:54:34 +01002064 state. A value of 1 uses minimum memory but is slow and reduces compression
Davor Ocelice9ed2812017-12-25 17:49:28 +01002065 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
William Lallemanda509e4c2012-11-07 16:54:34 +01002066 between 1 and 9. The default value is 8.
2067
2068tune.zlib.windowsize <number>
2069 Sets the window size (the size of the history buffer) as a parameter of the
2070 zlib initialization for each session. Larger values of this parameter result
Davor Ocelice9ed2812017-12-25 17:49:28 +01002071 in better compression at the expense of memory usage. Can be a value between
2072 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002073
Willy Tarreauc57f0e22009-05-10 13:12:33 +020020743.3. Debugging
2075--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02002076
2077debug
2078 Enables debug mode which dumps to stdout all exchanges, and disables forking
2079 into background. It is the equivalent of the command-line argument "-d". It
2080 should never be used in a production configuration since it may prevent full
2081 system startup.
2082
2083quiet
2084 Do not display any message during startup. It is equivalent to the command-
2085 line argument "-q".
2086
Emeric Brunf099e792010-09-27 12:05:28 +02002087
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010020883.4. Userlists
2089--------------
2090It is possible to control access to frontend/backend/listen sections or to
2091http stats by allowing only authenticated and authorized users. To do this,
2092it is required to create at least one userlist and to define users.
2093
2094userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +01002095 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002096 used to store authentication & authorization data for independent customers.
2097
2098group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +01002099 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002100 attach users to this group by using a comma separated list of names
2101 proceeded by "users" keyword.
2102
Cyril Bontéf0c60612010-02-06 14:44:47 +01002103user <username> [password|insecure-password <password>]
2104 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002105 Adds user <username> to the current userlist. Both secure (encrypted) and
2106 insecure (unencrypted) passwords can be used. Encrypted passwords are
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01002107 evaluated using the crypt(3) function, so depending on the system's
2108 capabilities, different algorithms are supported. For example, modern Glibc
2109 based Linux systems support MD5, SHA-256, SHA-512, and, of course, the
2110 classic DES-based method of encrypting passwords.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002111
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01002112 Attention: Be aware that using encrypted passwords might cause significantly
2113 increased CPU usage, depending on the number of requests, and the algorithm
2114 used. For any of the hashed variants, the password for each request must
2115 be processed through the chosen algorithm, before it can be compared to the
2116 value specified in the config file. Most current algorithms are deliberately
2117 designed to be expensive to compute to achieve resistance against brute
2118 force attacks. They do not simply salt/hash the clear text password once,
2119 but thousands of times. This can quickly become a major factor in haproxy's
2120 overall CPU consumption!
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002121
2122 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +01002123 userlist L1
2124 group G1 users tiger,scott
2125 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002126
Cyril Bontéf0c60612010-02-06 14:44:47 +01002127 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
2128 user scott insecure-password elgato
2129 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002130
Cyril Bontéf0c60612010-02-06 14:44:47 +01002131 userlist L2
2132 group G1
2133 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002134
Cyril Bontéf0c60612010-02-06 14:44:47 +01002135 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
2136 user scott insecure-password elgato groups G1,G2
2137 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002138
2139 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002140
Emeric Brunf099e792010-09-27 12:05:28 +02002141
21423.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +02002143----------
Emeric Brun94900952015-06-11 18:25:54 +02002144It is possible to propagate entries of any data-types in stick-tables between
2145several haproxy instances over TCP connections in a multi-master fashion. Each
2146instance pushes its local updates and insertions to remote peers. The pushed
2147values overwrite remote ones without aggregation. Interrupted exchanges are
2148automatically detected and recovered from the last known point.
2149In addition, during a soft restart, the old process connects to the new one
2150using such a TCP connection to push all its entries before the new process
2151tries to connect to other peers. That ensures very fast replication during a
2152reload, it typically takes a fraction of a second even for large tables.
2153Note that Server IDs are used to identify servers remotely, so it is important
2154that configurations look similar or at least that the same IDs are forced on
2155each server on all participants.
Emeric Brunf099e792010-09-27 12:05:28 +02002156
2157peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002158 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +02002159 which is referenced by one or more stick-tables.
2160
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002161bind [<address>]:<port_range> [, ...] [param*]
2162 Defines the binding parameters of the local peer of this "peers" section.
2163 Such lines are not supported with "peer" line in the same "peers" section.
2164
Willy Tarreau77e4bd12015-05-01 20:02:17 +02002165disabled
2166 Disables a peers section. It disables both listening and any synchronization
2167 related to this section. This is provided to disable synchronization of stick
2168 tables without having to comment out all "peers" references.
2169
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002170default-bind [param*]
2171 Defines the binding parameters for the local peer, excepted its address.
2172
2173default-server [param*]
2174 Change default options for a server in a "peers" section.
2175
2176 Arguments:
2177 <param*> is a list of parameters for this server. The "default-server"
2178 keyword accepts an important number of options and has a complete
2179 section dedicated to it. Please refer to section 5 for more
2180 details.
2181
2182
2183 See also: "server" and section 5 about server options
2184
Willy Tarreau77e4bd12015-05-01 20:02:17 +02002185enable
2186 This re-enables a disabled peers section which was previously disabled.
2187
Frédéric Lécailleb6f759b2019-11-05 09:57:45 +01002188log <address> [len <length>] [format <format>] [sample <ranges>:<smp_size>]
2189 <facility> [<level> [<minlevel>]]
2190 "peers" sections support the same "log" keyword as for the proxies to
2191 log information about the "peers" listener. See "log" option for proxies for
2192 more details.
2193
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002194peer <peername> <ip>:<port> [param*]
Emeric Brunf099e792010-09-27 12:05:28 +02002195 Defines a peer inside a peers section.
2196 If <peername> is set to the local peer name (by default hostname, or forced
2197 using "-L" command line option), haproxy will listen for incoming remote peer
2198 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
2199 to join the remote peer, and <peername> is used at the protocol level to
2200 identify and validate the remote peer on the server side.
2201
2202 During a soft restart, local peer <ip>:<port> is used by the old instance to
2203 connect the new one and initiate a complete replication (teaching process).
2204
2205 It is strongly recommended to have the exact same peers declaration on all
2206 peers and to only rely on the "-L" command line argument to change the local
2207 peer name. This makes it easier to maintain coherent configuration files
2208 across all peers.
2209
William Lallemandb2f07452015-05-12 14:27:13 +02002210 You may want to reference some environment variables in the address
2211 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01002212
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002213 Note: "peer" keyword may transparently be replaced by "server" keyword (see
2214 "server" keyword explanation below).
2215
2216server <peername> [<ip>:<port>] [param*]
Michael Prokop4438c602019-05-24 10:25:45 +02002217 As previously mentioned, "peer" keyword may be replaced by "server" keyword
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002218 with a support for all "server" parameters found in 5.2 paragraph.
2219 If the underlying peer is local, <ip>:<port> parameters must not be present.
2220 These parameters must be provided on a "bind" line (see "bind" keyword
2221 of this "peers" section).
2222 Some of these parameters are irrelevant for "peers" sections.
2223
2224
Cyril Bontédc4d9032012-04-08 21:57:39 +02002225 Example:
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002226 # The old way.
Emeric Brunf099e792010-09-27 12:05:28 +02002227 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +01002228 peer haproxy1 192.168.0.1:1024
2229 peer haproxy2 192.168.0.2:1024
2230 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +02002231
2232 backend mybackend
2233 mode tcp
2234 balance roundrobin
2235 stick-table type ip size 20k peers mypeers
2236 stick on src
2237
Willy Tarreauf7b30a92010-12-06 22:59:17 +01002238 server srv1 192.168.0.30:80
2239 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +02002240
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002241 Example:
2242 peers mypeers
2243 bind 127.0.0.11:10001 ssl crt mycerts/pem
2244 default-server ssl verify none
2245 server hostA 127.0.0.10:10000
2246 server hostB #local peer
Emeric Brunf099e792010-09-27 12:05:28 +02002247
Frédéric Lécaille4f5b77c2019-03-18 14:05:58 +01002248
2249table <tablename> type {ip | integer | string [len <length>] | binary [len <length>]}
2250 size <size> [expire <expire>] [nopurge] [store <data_type>]*
2251
2252 Configure a stickiness table for the current section. This line is parsed
2253 exactly the same way as the "stick-table" keyword in others section, except
John Roeslerfb2fce12019-07-10 15:45:51 -05002254 for the "peers" argument which is not required here and with an additional
Frédéric Lécaille4f5b77c2019-03-18 14:05:58 +01002255 mandatory first parameter to designate the stick-table. Contrary to others
2256 sections, there may be several "table" lines in "peers" sections (see also
2257 "stick-table" keyword).
2258
2259 Also be aware of the fact that "peers" sections have their own stick-table
2260 namespaces to avoid collisions between stick-table names identical in
2261 different "peers" section. This is internally handled prepending the "peers"
2262 sections names to the name of the stick-tables followed by a '/' character.
2263 If somewhere else in the configuration file you have to refer to such
2264 stick-tables declared in "peers" sections you must use the prefixed version
2265 of the stick-table name as follows:
2266
2267 peers mypeers
2268 peer A ...
2269 peer B ...
2270 table t1 ...
2271
2272 frontend fe1
2273 tcp-request content track-sc0 src table mypeers/t1
2274
2275 This is also this prefixed version of the stick-table names which must be
2276 used to refer to stick-tables through the CLI.
2277
2278 About "peers" protocol, as only "peers" belonging to the same section may
2279 communicate with each others, there is no need to do such a distinction.
2280 Several "peers" sections may declare stick-tables with the same name.
2281 This is shorter version of the stick-table name which is sent over the network.
2282 There is only a '/' character as prefix to avoid stick-table name collisions between
2283 stick-tables declared as backends and stick-table declared in "peers" sections
2284 as follows in this weird but supported configuration:
2285
2286 peers mypeers
2287 peer A ...
2288 peer B ...
2289 table t1 type string size 10m store gpc0
2290
2291 backend t1
2292 stick-table type string size 10m store gpc0 peers mypeers
2293
2294 Here "t1" table declared in "mypeeers" section has "mypeers/t1" as global name.
2295 "t1" table declared as a backend as "t1" as global name. But at peer protocol
2296 level the former table is named "/t1", the latter is again named "t1".
2297
Simon Horman51a1cf62015-02-03 13:00:44 +090022983.6. Mailers
2299------------
2300It is possible to send email alerts when the state of servers changes.
2301If configured email alerts are sent to each mailer that is configured
2302in a mailers section. Email is sent to mailers using SMTP.
2303
Pieter Baauw386a1272015-08-16 15:26:24 +02002304mailers <mailersect>
Simon Horman51a1cf62015-02-03 13:00:44 +09002305 Creates a new mailer list with the name <mailersect>. It is an
2306 independent section which is referenced by one or more proxies.
2307
2308mailer <mailername> <ip>:<port>
2309 Defines a mailer inside a mailers section.
2310
2311 Example:
2312 mailers mymailers
2313 mailer smtp1 192.168.0.1:587
2314 mailer smtp2 192.168.0.2:587
2315
2316 backend mybackend
2317 mode tcp
2318 balance roundrobin
2319
2320 email-alert mailers mymailers
2321 email-alert from test1@horms.org
2322 email-alert to test2@horms.org
2323
2324 server srv1 192.168.0.30:80
2325 server srv2 192.168.0.31:80
2326
Pieter Baauw235fcfc2016-02-13 15:33:40 +01002327timeout mail <time>
2328 Defines the time available for a mail/connection to be made and send to
2329 the mail-server. If not defined the default value is 10 seconds. To allow
2330 for at least two SYN-ACK packets to be send during initial TCP handshake it
2331 is advised to keep this value above 4 seconds.
2332
2333 Example:
2334 mailers mymailers
2335 timeout mail 20s
2336 mailer smtp1 192.168.0.1:587
Simon Horman51a1cf62015-02-03 13:00:44 +09002337
William Lallemandc9515522019-06-12 16:32:11 +020023383.7. Programs
2339-------------
2340In master-worker mode, it is possible to launch external binaries with the
2341master, these processes are called programs. These programs are launched and
2342managed the same way as the workers.
2343
2344During a reload of HAProxy, those processes are dealing with the same
2345sequence as a worker:
2346
2347 - the master is re-executed
2348 - the master sends a SIGUSR1 signal to the program
2349 - if "option start-on-reload" is not disabled, the master launches a new
2350 instance of the program
2351
2352During a stop, or restart, a SIGTERM is sent to the programs.
2353
2354program <name>
2355 This is a new program section, this section will create an instance <name>
2356 which is visible in "show proc" on the master CLI. (See "9.4. Master CLI" in
2357 the management guide).
2358
2359command <command> [arguments*]
2360 Define the command to start with optional arguments. The command is looked
2361 up in the current PATH if it does not include an absolute path. This is a
2362 mandatory option of the program section. Arguments containing spaces must
2363 be enclosed in quotes or double quotes or be prefixed by a backslash.
2364
Andrew Heberle97236962019-07-12 11:50:26 +08002365user <user name>
2366 Changes the executed command user ID to the <user name> from /etc/passwd.
2367 See also "group".
2368
2369group <group name>
2370 Changes the executed command group ID to the <group name> from /etc/group.
2371 See also "user".
2372
William Lallemandc9515522019-06-12 16:32:11 +02002373option start-on-reload
2374no option start-on-reload
2375 Start (or not) a new instance of the program upon a reload of the master.
2376 The default is to start a new instance. This option may only be used in a
2377 program section.
2378
2379
Willy Tarreauc57f0e22009-05-10 13:12:33 +020023804. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +02002381----------
Willy Tarreau0ba27502007-12-24 16:55:16 +01002382
Willy Tarreau6a06a402007-07-15 20:15:28 +02002383Proxy configuration can be located in a set of sections :
William Lallemand6e62fb62015-04-28 16:55:23 +02002384 - defaults [<name>]
Willy Tarreau6a06a402007-07-15 20:15:28 +02002385 - frontend <name>
2386 - backend <name>
2387 - listen <name>
2388
2389A "defaults" section sets default parameters for all other sections following
2390its declaration. Those default parameters are reset by the next "defaults"
2391section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +01002392section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002393
2394A "frontend" section describes a set of listening sockets accepting client
2395connections.
2396
2397A "backend" section describes a set of servers to which the proxy will connect
2398to forward incoming connections.
2399
2400A "listen" section defines a complete proxy with its frontend and backend
2401parts combined in one section. It is generally useful for TCP-only traffic.
2402
Willy Tarreau0ba27502007-12-24 16:55:16 +01002403All proxy names must be formed from upper and lower case letters, digits,
2404'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
2405case-sensitive, which means that "www" and "WWW" are two different proxies.
2406
2407Historically, all proxy names could overlap, it just caused troubles in the
2408logs. Since the introduction of content switching, it is mandatory that two
2409proxies with overlapping capabilities (frontend/backend) have different names.
2410However, it is still permitted that a frontend and a backend share the same
2411name, as this configuration seems to be commonly encountered.
2412
2413Right now, two major proxy modes are supported : "tcp", also known as layer 4,
2414and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002415bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002416protocol, and can interact with it by allowing, blocking, switching, adding,
2417modifying, or removing arbitrary contents in requests or responses, based on
2418arbitrary criteria.
2419
Willy Tarreau70dffda2014-01-30 03:07:23 +01002420In HTTP mode, the processing applied to requests and responses flowing over
2421a connection depends in the combination of the frontend's HTTP options and
Julien Pivotto21ad3152019-12-10 13:11:17 +01002422the backend's. HAProxy supports 3 connection modes :
Willy Tarreau70dffda2014-01-30 03:07:23 +01002423
2424 - KAL : keep alive ("option http-keep-alive") which is the default mode : all
2425 requests and responses are processed, and connections remain open but idle
2426 between responses and new requests.
2427
Willy Tarreau70dffda2014-01-30 03:07:23 +01002428 - SCL: server close ("option http-server-close") : the server-facing
2429 connection is closed after the end of the response is received, but the
2430 client-facing connection remains open.
2431
Christopher Faulet315b39c2018-09-21 16:26:19 +02002432 - CLO: close ("option httpclose"): the connection is closed after the end of
2433 the response and "Connection: close" appended in both directions.
Willy Tarreau70dffda2014-01-30 03:07:23 +01002434
2435The effective mode that will be applied to a connection passing through a
2436frontend and a backend can be determined by both proxy modes according to the
2437following matrix, but in short, the modes are symmetric, keep-alive is the
Christopher Faulet315b39c2018-09-21 16:26:19 +02002438weakest option and close is the strongest.
Willy Tarreau70dffda2014-01-30 03:07:23 +01002439
Christopher Faulet315b39c2018-09-21 16:26:19 +02002440 Backend mode
Willy Tarreau70dffda2014-01-30 03:07:23 +01002441
Christopher Faulet315b39c2018-09-21 16:26:19 +02002442 | KAL | SCL | CLO
2443 ----+-----+-----+----
2444 KAL | KAL | SCL | CLO
2445 ----+-----+-----+----
Christopher Faulet315b39c2018-09-21 16:26:19 +02002446 mode SCL | SCL | SCL | CLO
2447 ----+-----+-----+----
2448 CLO | CLO | CLO | CLO
Willy Tarreau70dffda2014-01-30 03:07:23 +01002449
Willy Tarreau0ba27502007-12-24 16:55:16 +01002450
Willy Tarreau70dffda2014-01-30 03:07:23 +01002451
Willy Tarreauc57f0e22009-05-10 13:12:33 +020024524.1. Proxy keywords matrix
2453--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01002454
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002455The following list of keywords is supported. Most of them may only be used in a
2456limited set of section types. Some of them are marked as "deprecated" because
2457they are inherited from an old syntax which may be confusing or functionally
2458limited, and there are new recommended keywords to replace them. Keywords
Davor Ocelice9ed2812017-12-25 17:49:28 +01002459marked with "(*)" can be optionally inverted using the "no" prefix, e.g. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002460option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02002461and must be disabled for a specific instance. Such options may also be prefixed
2462with "default" in order to restore default settings regardless of what has been
2463specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002464
Willy Tarreau6a06a402007-07-15 20:15:28 +02002465
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002466 keyword defaults frontend listen backend
2467------------------------------------+----------+----------+---------+---------
2468acl - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002469backlog X X X -
2470balance X - X X
2471bind - X X -
2472bind-process X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002473capture cookie - X X -
2474capture request header - X X -
2475capture response header - X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02002476compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002477cookie X - X X
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02002478declare capture - X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002479default-server X - X X
2480default_backend X X X -
2481description - X X X
2482disabled X X X X
2483dispatch - - X X
Simon Horman51a1cf62015-02-03 13:00:44 +09002484email-alert from X X X X
Simon Horman64e34162015-02-06 11:11:57 +09002485email-alert level X X X X
Simon Horman51a1cf62015-02-03 13:00:44 +09002486email-alert mailers X X X X
2487email-alert myhostname X X X X
2488email-alert to X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002489enabled X X X X
2490errorfile X X X X
2491errorloc X X X X
2492errorloc302 X X X X
2493-- keyword -------------------------- defaults - frontend - listen -- backend -
2494errorloc303 X X X X
Cyril Bonté4288c5a2018-03-12 22:02:59 +01002495force-persist - - X X
Christopher Fauletc3fe5332016-04-07 15:30:10 +02002496filter - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002497fullconn X - X X
2498grace X X X X
2499hash-type X - X X
2500http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +01002501http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02002502http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002503http-request - X X X
Willy Tarreaue365c0b2013-06-11 16:06:12 +02002504http-response - X X X
Willy Tarreau30631952015-08-06 15:05:24 +02002505http-reuse X - X X
Baptiste Assmann2c42ef52013-10-09 21:57:02 +02002506http-send-name-header - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002507id - X X X
Cyril Bonté4288c5a2018-03-12 22:02:59 +01002508ignore-persist - - X X
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02002509load-server-state-from-file X - X X
William Lallemand0f99e342011-10-12 17:50:54 +02002510log (*) X X X X
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01002511log-format X X X -
Dragan Dosen7ad31542015-09-28 17:16:47 +02002512log-format-sd X X X -
Willy Tarreau094af4e2015-01-07 15:03:42 +01002513log-tag X X X X
Willy Tarreauc35362a2014-04-25 13:58:37 +02002514max-keep-alive-queue X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002515maxconn X X X -
2516mode X X X X
2517monitor fail - X X -
2518monitor-net X X X -
2519monitor-uri X X X -
2520option abortonclose (*) X - X X
2521option accept-invalid-http-request (*) X X X -
2522option accept-invalid-http-response (*) X - X X
2523option allbackups (*) X - X X
2524option checkcache (*) X - X X
2525option clitcpka (*) X X X -
2526option contstats (*) X X X -
2527option dontlog-normal (*) X X X -
2528option dontlognull (*) X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002529-- keyword -------------------------- defaults - frontend - listen -- backend -
2530option forwardfor X X X X
Christopher Faulet98fbe952019-07-22 16:18:24 +02002531option h1-case-adjust-bogus-client (*) X X X -
2532option h1-case-adjust-bogus-server (*) X - X X
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02002533option http-buffer-request (*) X X X X
Willy Tarreau82649f92015-05-01 22:40:51 +02002534option http-ignore-probes (*) X X X -
Willy Tarreau16bfb022010-01-16 19:48:41 +01002535option http-keep-alive (*) X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02002536option http-no-delay (*) X X X X
Christopher Faulet98db9762018-09-21 10:25:19 +02002537option http-pretend-keepalive (*) X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002538option http-server-close (*) X X X X
2539option http-use-proxy-header (*) X X X -
2540option httpchk X - X X
2541option httpclose (*) X X X X
Freddy Spierenburge88b7732019-03-25 14:35:17 +01002542option httplog X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002543option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002544option independent-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02002545option ldap-check X - X X
Simon Horman98637e52014-06-20 12:30:16 +09002546option external-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002547option log-health-checks (*) X - X X
2548option log-separate-errors (*) X X X -
2549option logasap (*) X X X -
2550option mysql-check X - X X
2551option nolinger (*) X X X X
2552option originalto X X X X
2553option persist (*) X - X X
Baptiste Assmann809e22a2015-10-12 20:22:55 +02002554option pgsql-check X - X X
2555option prefer-last-server (*) X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002556option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02002557option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002558option smtpchk X - X X
2559option socket-stats (*) X X X -
2560option splice-auto (*) X X X X
2561option splice-request (*) X X X X
2562option splice-response (*) X X X X
Christopher Fauletba7bc162016-11-07 21:07:38 +01002563option spop-check - - - X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002564option srvtcpka (*) X - X X
2565option ssl-hello-chk X - X X
2566-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreaued179852013-12-16 01:07:00 +01002567option tcp-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002568option tcp-smart-accept (*) X X X -
2569option tcp-smart-connect (*) X - X X
2570option tcpka X X X X
2571option tcplog X X X X
2572option transparent (*) X - X X
Simon Horman98637e52014-06-20 12:30:16 +09002573external-check command X - X X
2574external-check path X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002575persist rdp-cookie X - X X
2576rate-limit sessions X X X -
2577redirect - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002578-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002579retries X - X X
Olivier Houcharda254a372019-04-05 15:30:12 +02002580retry-on X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002581server - - X X
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02002582server-state-file-name X - X X
Frédéric Lécaillecb4502e2017-04-20 13:36:25 +02002583server-template - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002584source X - X X
Baptiste Assmann5a549212015-10-12 20:30:24 +02002585stats admin - X X X
2586stats auth X X X X
2587stats enable X X X X
2588stats hide-version X X X X
2589stats http-request - X X X
2590stats realm X X X X
2591stats refresh X X X X
2592stats scope X X X X
2593stats show-desc X X X X
2594stats show-legends X X X X
2595stats show-node X X X X
2596stats uri X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002597-- keyword -------------------------- defaults - frontend - listen -- backend -
2598stick match - - X X
2599stick on - - X X
2600stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02002601stick store-response - - X X
Adam Spiers68af3c12017-04-06 16:31:39 +01002602stick-table - X X X
Willy Tarreau938c7fe2014-04-25 14:21:39 +02002603tcp-check connect - - X X
2604tcp-check expect - - X X
2605tcp-check send - - X X
2606tcp-check send-binary - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02002607tcp-request connection - X X -
2608tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02002609tcp-request inspect-delay - X X X
Willy Tarreau4f614292016-10-21 17:49:36 +02002610tcp-request session - X X -
Emeric Brun0a3b67f2010-09-24 15:34:53 +02002611tcp-response content - - X X
2612tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002613timeout check X - X X
2614timeout client X X X -
Willy Tarreau05cdd962014-05-10 14:30:07 +02002615timeout client-fin X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002616timeout connect X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002617timeout http-keep-alive X X X X
2618timeout http-request X X X X
2619timeout queue X - X X
2620timeout server X - X X
Willy Tarreau05cdd962014-05-10 14:30:07 +02002621timeout server-fin X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002622timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02002623timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002624transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01002625unique-id-format X X X -
2626unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002627use_backend - X X -
Christopher Fauletb30b3102019-09-12 23:03:09 +02002628use-fcgi-app - - X X
Willy Tarreau4a5cade2012-04-05 21:09:48 +02002629use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002630------------------------------------+----------+----------+---------+---------
2631 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02002632
Willy Tarreau0ba27502007-12-24 16:55:16 +01002633
Willy Tarreauc57f0e22009-05-10 13:12:33 +020026344.2. Alphabetically sorted keywords reference
2635---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01002636
2637This section provides a description of each keyword and its usage.
2638
2639
2640acl <aclname> <criterion> [flags] [operator] <value> ...
2641 Declare or complete an access list.
2642 May be used in sections : defaults | frontend | listen | backend
2643 no | yes | yes | yes
2644 Example:
2645 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
2646 acl invalid_src src_port 0:1023
2647 acl local_dst hdr(host) -i localhost
2648
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002649 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002650
2651
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01002652backlog <conns>
2653 Give hints to the system about the approximate listen backlog desired size
2654 May be used in sections : defaults | frontend | listen | backend
2655 yes | yes | yes | no
2656 Arguments :
2657 <conns> is the number of pending connections. Depending on the operating
2658 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02002659 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01002660
2661 In order to protect against SYN flood attacks, one solution is to increase
2662 the system's SYN backlog size. Depending on the system, sometimes it is just
2663 tunable via a system parameter, sometimes it is not adjustable at all, and
2664 sometimes the system relies on hints given by the application at the time of
2665 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
2666 to the listen() syscall. On systems which can make use of this value, it can
2667 sometimes be useful to be able to specify a different value, hence this
2668 backlog parameter.
2669
2670 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
2671 used as a hint and the system accepts up to the smallest greater power of
2672 two, and never more than some limits (usually 32768).
2673
2674 See also : "maxconn" and the target operating system's tuning guide.
2675
2676
Willy Tarreau0ba27502007-12-24 16:55:16 +01002677balance <algorithm> [ <arguments> ]
Willy Tarreau226071e2014-04-10 11:55:45 +02002678balance url_param <param> [check_post]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002679 Define the load balancing algorithm to be used in a backend.
2680 May be used in sections : defaults | frontend | listen | backend
2681 yes | no | yes | yes
2682 Arguments :
2683 <algorithm> is the algorithm used to select a server when doing load
2684 balancing. This only applies when no persistence information
2685 is available, or when a connection is redispatched to another
2686 server. <algorithm> may be one of the following :
2687
2688 roundrobin Each server is used in turns, according to their weights.
2689 This is the smoothest and fairest algorithm when the server's
2690 processing time remains equally distributed. This algorithm
2691 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02002692 on the fly for slow starts for instance. It is limited by
Godbacha34bdc02013-07-22 07:44:53 +08002693 design to 4095 active servers per backend. Note that in some
Willy Tarreau9757a382009-10-03 12:56:50 +02002694 large farms, when a server becomes up after having been down
2695 for a very short time, it may sometimes take a few hundreds
2696 requests for it to be re-integrated into the farm and start
2697 receiving traffic. This is normal, though very rare. It is
2698 indicated here in case you would have the chance to observe
2699 it, so that you don't worry.
2700
2701 static-rr Each server is used in turns, according to their weights.
2702 This algorithm is as similar to roundrobin except that it is
2703 static, which means that changing a server's weight on the
2704 fly will have no effect. On the other hand, it has no design
2705 limitation on the number of servers, and when a server goes
2706 up, it is always immediately reintroduced into the farm, once
2707 the full map is recomputed. It also uses slightly less CPU to
2708 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01002709
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01002710 leastconn The server with the lowest number of connections receives the
2711 connection. Round-robin is performed within groups of servers
2712 of the same load to ensure that all servers will be used. Use
2713 of this algorithm is recommended where very long sessions are
2714 expected, such as LDAP, SQL, TSE, etc... but is not very well
2715 suited for protocols using short sessions such as HTTP. This
2716 algorithm is dynamic, which means that server weights may be
2717 adjusted on the fly for slow starts for instance.
2718
Willy Tarreauf09c6602012-02-13 17:12:08 +01002719 first The first server with available connection slots receives the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03002720 connection. The servers are chosen from the lowest numeric
Willy Tarreauf09c6602012-02-13 17:12:08 +01002721 identifier to the highest (see server parameter "id"), which
2722 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02002723 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01002724 not make sense to use this algorithm without setting maxconn.
2725 The purpose of this algorithm is to always use the smallest
2726 number of servers so that extra servers can be powered off
2727 during non-intensive hours. This algorithm ignores the server
2728 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02002729 or IMAP than HTTP, though it can be useful there too. In
2730 order to use this algorithm efficiently, it is recommended
2731 that a cloud controller regularly checks server usage to turn
2732 them off when unused, and regularly checks backend queue to
2733 turn new servers on when the queue inflates. Alternatively,
2734 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01002735
Willy Tarreau0ba27502007-12-24 16:55:16 +01002736 source The source IP address is hashed and divided by the total
2737 weight of the running servers to designate which server will
2738 receive the request. This ensures that the same client IP
2739 address will always reach the same server as long as no
2740 server goes down or up. If the hash result changes due to the
2741 number of running servers changing, many clients will be
2742 directed to a different server. This algorithm is generally
2743 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002744 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01002745 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002746 static by default, which means that changing a server's
2747 weight on the fly will have no effect, but this can be
2748 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002749
Oskar Stolc8dc41842012-05-19 10:19:54 +01002750 uri This algorithm hashes either the left part of the URI (before
2751 the question mark) or the whole URI (if the "whole" parameter
2752 is present) and divides the hash value by the total weight of
2753 the running servers. The result designates which server will
2754 receive the request. This ensures that the same URI will
2755 always be directed to the same server as long as no server
2756 goes up or down. This is used with proxy caches and
2757 anti-virus proxies in order to maximize the cache hit rate.
2758 Note that this algorithm may only be used in an HTTP backend.
2759 This algorithm is static by default, which means that
2760 changing a server's weight on the fly will have no effect,
2761 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002762
Oskar Stolc8dc41842012-05-19 10:19:54 +01002763 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02002764 "depth", both followed by a positive integer number. These
2765 options may be helpful when it is needed to balance servers
2766 based on the beginning of the URI only. The "len" parameter
2767 indicates that the algorithm should only consider that many
2768 characters at the beginning of the URI to compute the hash.
2769 Note that having "len" set to 1 rarely makes sense since most
2770 URIs start with a leading "/".
2771
2772 The "depth" parameter indicates the maximum directory depth
2773 to be used to compute the hash. One level is counted for each
2774 slash in the request. If both parameters are specified, the
2775 evaluation stops when either is reached.
2776
Willy Tarreau0ba27502007-12-24 16:55:16 +01002777 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002778 the query string of each HTTP GET request.
2779
2780 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02002781 request entity will be searched for the parameter argument,
2782 when it is not found in a query string after a question mark
Willy Tarreau226071e2014-04-10 11:55:45 +02002783 ('?') in the URL. The message body will only start to be
2784 analyzed once either the advertised amount of data has been
2785 received or the request buffer is full. In the unlikely event
2786 that chunked encoding is used, only the first chunk is
Cyril Bontédc4d9032012-04-08 21:57:39 +02002787 scanned. Parameter values separated by a chunk boundary, may
Willy Tarreau226071e2014-04-10 11:55:45 +02002788 be randomly balanced if at all. This keyword used to support
2789 an optional <max_wait> parameter which is now ignored.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002790
2791 If the parameter is found followed by an equal sign ('=') and
2792 a value, then the value is hashed and divided by the total
2793 weight of the running servers. The result designates which
2794 server will receive the request.
2795
2796 This is used to track user identifiers in requests and ensure
2797 that a same user ID will always be sent to the same server as
2798 long as no server goes up or down. If no value is found or if
2799 the parameter is not found, then a round robin algorithm is
2800 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002801 backend. This algorithm is static by default, which means
2802 that changing a server's weight on the fly will have no
2803 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002804
Cyril Bontédc4d9032012-04-08 21:57:39 +02002805 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
2806 request. Just as with the equivalent ACL 'hdr()' function,
2807 the header name in parenthesis is not case sensitive. If the
2808 header is absent or if it does not contain any value, the
2809 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01002810
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002811 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01002812 reducing the hash algorithm to the main domain part with some
2813 specific headers such as 'Host'. For instance, in the Host
2814 value "haproxy.1wt.eu", only "1wt" will be considered.
2815
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002816 This algorithm is static by default, which means that
2817 changing a server's weight on the fly will have no effect,
2818 but this can be changed using "hash-type".
2819
Willy Tarreau21c741a2019-01-14 18:14:27 +01002820 random
2821 random(<draws>)
2822 A random number will be used as the key for the consistent
Willy Tarreau760e81d2018-05-03 07:20:40 +02002823 hashing function. This means that the servers' weights are
2824 respected, dynamic weight changes immediately take effect, as
2825 well as new server additions. Random load balancing can be
2826 useful with large farms or when servers are frequently added
Willy Tarreau21c741a2019-01-14 18:14:27 +01002827 or removed as it may avoid the hammering effect that could
2828 result from roundrobin or leastconn in this situation. The
2829 hash-balance-factor directive can be used to further improve
2830 fairness of the load balancing, especially in situations
2831 where servers show highly variable response times. When an
2832 argument <draws> is present, it must be an integer value one
2833 or greater, indicating the number of draws before selecting
2834 the least loaded of these servers. It was indeed demonstrated
2835 that picking the least loaded of two servers is enough to
2836 significantly improve the fairness of the algorithm, by
2837 always avoiding to pick the most loaded server within a farm
2838 and getting rid of any bias that could be induced by the
2839 unfair distribution of the consistent list. Higher values N
2840 will take away N-1 of the highest loaded servers at the
2841 expense of performance. With very high values, the algorithm
2842 will converge towards the leastconn's result but much slower.
2843 The default value is 2, which generally shows very good
2844 distribution and performance. This algorithm is also known as
2845 the Power of Two Random Choices and is described here :
2846 http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf
Willy Tarreau760e81d2018-05-03 07:20:40 +02002847
Emeric Brun736aa232009-06-30 17:56:00 +02002848 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02002849 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02002850 The RDP cookie <name> (or "mstshash" if omitted) will be
2851 looked up and hashed for each incoming TCP request. Just as
2852 with the equivalent ACL 'req_rdp_cookie()' function, the name
2853 is not case-sensitive. This mechanism is useful as a degraded
2854 persistence mode, as it makes it possible to always send the
2855 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002856 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02002857 used instead.
2858
2859 Note that for this to work, the frontend must ensure that an
2860 RDP cookie is already present in the request buffer. For this
2861 you must use 'tcp-request content accept' rule combined with
2862 a 'req_rdp_cookie_cnt' ACL.
2863
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002864 This algorithm is static by default, which means that
2865 changing a server's weight on the fly will have no effect,
2866 but this can be changed using "hash-type".
2867
Cyril Bontédc4d9032012-04-08 21:57:39 +02002868 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09002869
Willy Tarreau0ba27502007-12-24 16:55:16 +01002870 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02002871 algorithms. Right now, only "url_param" and "uri" support an
2872 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002873
Willy Tarreau3cd9af22009-03-15 14:06:41 +01002874 The load balancing algorithm of a backend is set to roundrobin when no other
2875 algorithm, mode nor option have been set. The algorithm may only be set once
2876 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002877
Lukas Tribus80512b12018-10-27 20:07:40 +02002878 With authentication schemes that require the same connection like NTLM, URI
John Roeslerfb2fce12019-07-10 15:45:51 -05002879 based algorithms must not be used, as they would cause subsequent requests
Lukas Tribus80512b12018-10-27 20:07:40 +02002880 to be routed to different backend servers, breaking the invalid assumptions
2881 NTLM relies on.
2882
Willy Tarreau0ba27502007-12-24 16:55:16 +01002883 Examples :
2884 balance roundrobin
2885 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002886 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01002887 balance hdr(User-Agent)
2888 balance hdr(host)
2889 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002890
2891 Note: the following caveats and limitations on using the "check_post"
2892 extension with "url_param" must be considered :
2893
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002894 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002895 to determine if the parameters will be found in the body or entity which
2896 may contain binary data. Therefore another method may be required to
2897 restrict consideration of POST requests that have no URL parameters in
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02002898 the body. (see acl http_end)
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002899
2900 - using a <max_wait> value larger than the request buffer size does not
2901 make sense and is useless. The buffer size is set at build time, and
2902 defaults to 16 kB.
2903
2904 - Content-Encoding is not supported, the parameter search will probably
2905 fail; and load balancing will fall back to Round Robin.
2906
2907 - Expect: 100-continue is not supported, load balancing will fall back to
2908 Round Robin.
2909
Lukas Tribus23953682017-04-28 13:24:30 +00002910 - Transfer-Encoding (RFC7230 3.3.1) is only supported in the first chunk.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002911 If the entire parameter value is not present in the first chunk, the
2912 selection of server is undefined (actually, defined by how little
2913 actually appeared in the first chunk).
2914
2915 - This feature does not support generation of a 100, 411 or 501 response.
2916
2917 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002918 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002919 white space or control characters are found, indicating the end of what
2920 might be a URL parameter list. This is probably not a concern with SGML
2921 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002922
Willy Tarreau294d0f02015-08-10 19:40:12 +02002923 See also : "dispatch", "cookie", "transparent", "hash-type" and "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002924
2925
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002926bind [<address>]:<port_range> [, ...] [param*]
2927bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002928 Define one or several listening addresses and/or ports in a frontend.
2929 May be used in sections : defaults | frontend | listen | backend
2930 no | yes | yes | no
2931 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01002932 <address> is optional and can be a host name, an IPv4 address, an IPv6
2933 address, or '*'. It designates the address the frontend will
2934 listen on. If unset, all IPv4 addresses of the system will be
2935 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01002936 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreau24709282013-03-10 21:32:12 +01002937 Optionally, an address family prefix may be used before the
2938 address to force the family regardless of the address format,
2939 which can be useful to specify a path to a unix socket with
2940 no slash ('/'). Currently supported prefixes are :
2941 - 'ipv4@' -> address is always IPv4
2942 - 'ipv6@' -> address is always IPv6
2943 - 'unix@' -> address is a path to a local unix socket
Willy Tarreau70f72e02014-07-08 00:37:50 +02002944 - 'abns@' -> address is in abstract namespace (Linux only).
2945 Note: since abstract sockets are not "rebindable", they
2946 do not cope well with multi-process mode during
2947 soft-restart, so it is better to avoid them if
2948 nbproc is greater than 1. The effect is that if the
2949 new process fails to start, only one of the old ones
2950 will be able to rebind to the socket.
Willy Tarreau40aa0702013-03-10 23:51:38 +01002951 - 'fd@<n>' -> use file descriptor <n> inherited from the
2952 parent. The fd must be bound and may or may not already
2953 be listening.
William Lallemand2fe7dd02018-09-11 16:51:29 +02002954 - 'sockpair@<n>'-> like fd@ but you must use the fd of a
2955 connected unix socket or of a socketpair. The bind waits
2956 to receive a FD over the unix socket and uses it as if it
2957 was the FD of an accept(). Should be used carefully.
William Lallemandb2f07452015-05-12 14:27:13 +02002958 You may want to reference some environment variables in the
2959 address parameter, see section 2.3 about environment
2960 variables.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01002961
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002962 <port_range> is either a unique TCP port, or a port range for which the
2963 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002964 above. The port is mandatory for TCP listeners. Note that in
2965 the case of an IPv6 address, the port is always the number
2966 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002967 - a numerical port (ex: '80')
2968 - a dash-delimited ports range explicitly stating the lower
2969 and upper bounds (ex: '2000-2100') which are included in
2970 the range.
2971
2972 Particular care must be taken against port ranges, because
2973 every <address:port> couple consumes one socket (= a file
2974 descriptor), so it's easy to consume lots of descriptors
2975 with a simple range, and to run out of sockets. Also, each
2976 <address:port> couple must be used only once among all
2977 instances running on a same system. Please note that binding
2978 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002979 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002980 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002981
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002982 <path> is a UNIX socket path beginning with a slash ('/'). This is
Davor Ocelice9ed2812017-12-25 17:49:28 +01002983 alternative to the TCP listening port. HAProxy will then
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002984 receive UNIX connections on the socket located at this place.
2985 The path must begin with a slash and by default is absolute.
2986 It can be relative to the prefix defined by "unix-bind" in
2987 the global section. Note that the total length of the prefix
2988 followed by the socket path cannot exceed some system limits
2989 for UNIX sockets, which commonly are set to 107 characters.
2990
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002991 <param*> is a list of parameters common to all sockets declared on the
2992 same line. These numerous parameters depend on OS and build
2993 options and have a complete section dedicated to them. Please
2994 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002995
Willy Tarreau0ba27502007-12-24 16:55:16 +01002996 It is possible to specify a list of address:port combinations delimited by
2997 commas. The frontend will then listen on all of these addresses. There is no
2998 fixed limit to the number of addresses and ports which can be listened on in
2999 a frontend, as well as there is no limit to the number of "bind" statements
3000 in a frontend.
3001
3002 Example :
3003 listen http_proxy
3004 bind :80,:443
3005 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01003006 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01003007
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02003008 listen http_https_proxy
3009 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02003010 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02003011
Willy Tarreau24709282013-03-10 21:32:12 +01003012 listen http_https_proxy_explicit
3013 bind ipv6@:80
3014 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
3015 bind unix@ssl-frontend.sock user root mode 600 accept-proxy
3016
Willy Tarreaudad36a32013-03-11 01:20:04 +01003017 listen external_bind_app1
William Lallemandb2f07452015-05-12 14:27:13 +02003018 bind "fd@${FD_APP1}"
Willy Tarreaudad36a32013-03-11 01:20:04 +01003019
Willy Tarreau55dcaf62015-09-27 15:03:15 +02003020 Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
3021 sun_path length is used for the address length. Some other programs
3022 such as socat use the string length only by default. Pass the option
3023 ",unix-tightsocklen=0" to any abstract socket definition in socat to
3024 make it compatible with HAProxy's.
3025
Willy Tarreauceb24bc2010-11-09 12:46:41 +01003026 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02003027 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003028
3029
Christopher Fauletff4121f2017-11-22 16:38:49 +01003030bind-process [ all | odd | even | <process_num>[-[<process_num>]] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003031 Limit visibility of an instance to a certain set of processes numbers.
3032 May be used in sections : defaults | frontend | listen | backend
3033 yes | yes | yes | yes
3034 Arguments :
3035 all All process will see this instance. This is the default. It
3036 may be used to override a default value.
3037
Willy Tarreaua9db57e2013-01-18 11:29:29 +01003038 odd This instance will be enabled on processes 1,3,5,...63. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003039 option may be combined with other numbers.
3040
Willy Tarreaua9db57e2013-01-18 11:29:29 +01003041 even This instance will be enabled on processes 2,4,6,...64. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003042 option may be combined with other numbers. Do not use it
3043 with less than 2 processes otherwise some instances might be
3044 missing from all processes.
3045
Christopher Fauletff4121f2017-11-22 16:38:49 +01003046 process_num The instance will be enabled on this process number or range,
Willy Tarreaua9db57e2013-01-18 11:29:29 +01003047 whose values must all be between 1 and 32 or 64 depending on
Christopher Fauletff4121f2017-11-22 16:38:49 +01003048 the machine's word size. Ranges can be partially defined. The
3049 higher bound can be omitted. In such case, it is replaced by
3050 the corresponding maximum value. If a proxy is bound to
3051 process numbers greater than the configured global.nbproc, it
3052 will either be forced to process #1 if a single process was
Willy Tarreau102df612014-05-07 23:56:38 +02003053 specified, or to all processes otherwise.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003054
3055 This keyword limits binding of certain instances to certain processes. This
3056 is useful in order not to have too many processes listening to the same
3057 ports. For instance, on a dual-core machine, it might make sense to set
3058 'nbproc 2' in the global section, then distributes the listeners among 'odd'
3059 and 'even' instances.
3060
Willy Tarreaua9db57e2013-01-18 11:29:29 +01003061 At the moment, it is not possible to reference more than 32 or 64 processes
3062 using this keyword, but this should be more than enough for most setups.
3063 Please note that 'all' really means all processes regardless of the machine's
3064 word size, and is not limited to the first 32 or 64.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003065
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02003066 Each "bind" line may further be limited to a subset of the proxy's processes,
3067 please consult the "process" bind keyword in section 5.1.
3068
Willy Tarreaub369a042014-09-16 13:21:03 +02003069 When a frontend has no explicit "bind-process" line, it tries to bind to all
3070 the processes referenced by its "bind" lines. That means that frontends can
3071 easily adapt to their listeners' processes.
3072
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003073 If some backends are referenced by frontends bound to other processes, the
3074 backend automatically inherits the frontend's processes.
3075
3076 Example :
3077 listen app_ip1
3078 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02003079 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003080
3081 listen app_ip2
3082 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02003083 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003084
3085 listen management
3086 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02003087 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003088
Willy Tarreau110ecc12012-11-15 17:50:01 +01003089 listen management
3090 bind 10.0.0.4:80
3091 bind-process 1-4
3092
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02003093 See also : "nbproc" in global section, and "process" in section 5.1.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003094
3095
Willy Tarreau0ba27502007-12-24 16:55:16 +01003096capture cookie <name> len <length>
3097 Capture and log a cookie in the request and in the response.
3098 May be used in sections : defaults | frontend | listen | backend
3099 no | yes | yes | no
3100 Arguments :
3101 <name> is the beginning of the name of the cookie to capture. In order
3102 to match the exact name, simply suffix the name with an equal
3103 sign ('='). The full name will appear in the logs, which is
3104 useful with application servers which adjust both the cookie name
Davor Ocelice9ed2812017-12-25 17:49:28 +01003105 and value (e.g. ASPSESSIONXXX).
Willy Tarreau0ba27502007-12-24 16:55:16 +01003106
3107 <length> is the maximum number of characters to report in the logs, which
3108 include the cookie name, the equal sign and the value, all in the
3109 standard "name=value" form. The string will be truncated on the
3110 right if it exceeds <length>.
3111
3112 Only the first cookie is captured. Both the "cookie" request headers and the
3113 "set-cookie" response headers are monitored. This is particularly useful to
3114 check for application bugs causing session crossing or stealing between
3115 users, because generally the user's cookies can only change on a login page.
3116
3117 When the cookie was not presented by the client, the associated log column
3118 will report "-". When a request does not cause a cookie to be assigned by the
3119 server, a "-" is reported in the response column.
3120
3121 The capture is performed in the frontend only because it is necessary that
3122 the log format does not change for a given frontend depending on the
3123 backends. This may change in the future. Note that there can be only one
Willy Tarreau193b8c62012-11-22 00:17:38 +01003124 "capture cookie" statement in a frontend. The maximum capture length is set
3125 by the global "tune.http.cookielen" setting and defaults to 63 characters. It
3126 is not possible to specify a capture in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003127
3128 Example:
3129 capture cookie ASPSESSION len 32
3130
3131 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003132 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003133
3134
3135capture request header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01003136 Capture and log the last occurrence of the specified request header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003137 May be used in sections : defaults | frontend | listen | backend
3138 no | yes | yes | no
3139 Arguments :
3140 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003141 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01003142 appear in the requests, with the first letter of each word in
3143 upper case. The header name will not appear in the logs, only the
3144 value is reported, but the position in the logs is respected.
3145
3146 <length> is the maximum number of characters to extract from the value and
3147 report in the logs. The string will be truncated on the right if
3148 it exceeds <length>.
3149
Willy Tarreau4460d032012-11-21 23:37:37 +01003150 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01003151 value will be added to the logs between braces ('{}'). If multiple headers
3152 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003153 in the same order they were declared in the configuration. Non-existent
3154 headers will be logged just as an empty string. Common uses for request
3155 header captures include the "Host" field in virtual hosting environments, the
3156 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003157 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003158 environments to find where the request came from.
3159
3160 Note that when capturing headers such as "User-agent", some spaces may be
3161 logged, making the log analysis more difficult. Thus be careful about what
3162 you log if you know your log parser is not smart enough to rely on the
3163 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003164
Willy Tarreau0900abb2012-11-22 00:21:46 +01003165 There is no limit to the number of captured request headers nor to their
3166 length, though it is wise to keep them low to limit memory usage per session.
3167 In order to keep log format consistent for a same frontend, header captures
3168 can only be declared in a frontend. It is not possible to specify a capture
3169 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003170
3171 Example:
3172 capture request header Host len 15
3173 capture request header X-Forwarded-For len 15
Cyril Bontéd1b0f7c2015-10-26 22:37:39 +01003174 capture request header Referer len 15
Willy Tarreau0ba27502007-12-24 16:55:16 +01003175
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003176 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01003177 about logging.
3178
3179
3180capture response header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01003181 Capture and log the last occurrence of the specified response header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003182 May be used in sections : defaults | frontend | listen | backend
3183 no | yes | yes | no
3184 Arguments :
3185 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003186 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01003187 appear in the response, with the first letter of each word in
3188 upper case. The header name will not appear in the logs, only the
3189 value is reported, but the position in the logs is respected.
3190
3191 <length> is the maximum number of characters to extract from the value and
3192 report in the logs. The string will be truncated on the right if
3193 it exceeds <length>.
3194
Willy Tarreau4460d032012-11-21 23:37:37 +01003195 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01003196 result will be added to the logs between braces ('{}') after the captured
3197 request headers. If multiple headers are captured, they will be delimited by
3198 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003199 the configuration. Non-existent headers will be logged just as an empty
3200 string. Common uses for response header captures include the "Content-length"
3201 header which indicates how many bytes are expected to be returned, the
3202 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003203
Willy Tarreau0900abb2012-11-22 00:21:46 +01003204 There is no limit to the number of captured response headers nor to their
3205 length, though it is wise to keep them low to limit memory usage per session.
3206 In order to keep log format consistent for a same frontend, header captures
3207 can only be declared in a frontend. It is not possible to specify a capture
3208 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003209
3210 Example:
3211 capture response header Content-length len 9
3212 capture response header Location len 15
3213
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003214 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01003215 about logging.
3216
3217
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003218compression algo <algorithm> ...
3219compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02003220compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02003221 Enable HTTP compression.
3222 May be used in sections : defaults | frontend | listen | backend
3223 yes | yes | yes | yes
3224 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003225 algo is followed by the list of supported compression algorithms.
3226 type is followed by the list of MIME types that will be compressed.
3227 offload makes haproxy work as a compression offloader only (see notes).
3228
3229 The currently supported algorithms are :
Willy Tarreauc91840a2015-03-28 17:00:39 +01003230 identity this is mostly for debugging, and it was useful for developing
3231 the compression feature. Identity does not apply any change on
3232 data.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003233
Willy Tarreauc91840a2015-03-28 17:00:39 +01003234 gzip applies gzip compression. This setting is only available when
Baptiste Assmannf085d632015-12-21 17:57:32 +01003235 support for zlib or libslz was built in.
Willy Tarreauc91840a2015-03-28 17:00:39 +01003236
3237 deflate same as "gzip", but with deflate algorithm and zlib format.
3238 Note that this algorithm has ambiguous support on many
3239 browsers and no support at all from recent ones. It is
3240 strongly recommended not to use it for anything else than
3241 experimentation. This setting is only available when support
Baptiste Assmannf085d632015-12-21 17:57:32 +01003242 for zlib or libslz was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003243
Willy Tarreauc91840a2015-03-28 17:00:39 +01003244 raw-deflate same as "deflate" without the zlib wrapper, and used as an
3245 alternative when the browser wants "deflate". All major
3246 browsers understand it and despite violating the standards,
3247 it is known to work better than "deflate", at least on MSIE
3248 and some versions of Safari. Do not use it in conjunction
3249 with "deflate", use either one or the other since both react
3250 to the same Accept-Encoding token. This setting is only
Baptiste Assmannf085d632015-12-21 17:57:32 +01003251 available when support for zlib or libslz was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003252
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04003253 Compression will be activated depending on the Accept-Encoding request
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003254 header. With identity, it does not take care of that header.
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04003255 If backend servers support HTTP compression, these directives
3256 will be no-op: haproxy will see the compressed response and will not
3257 compress again. If backend servers do not support HTTP compression and
3258 there is Accept-Encoding header in request, haproxy will compress the
3259 matching response.
Willy Tarreau70737d12012-10-27 00:34:28 +02003260
3261 The "offload" setting makes haproxy remove the Accept-Encoding header to
3262 prevent backend servers from compressing responses. It is strongly
3263 recommended not to do this because this means that all the compression work
3264 will be done on the single point where haproxy is located. However in some
3265 deployment scenarios, haproxy may be installed in front of a buggy gateway
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04003266 with broken HTTP compression implementation which can't be turned off.
3267 In that case haproxy can be used to prevent that gateway from emitting
3268 invalid payloads. In this case, simply removing the header in the
3269 configuration does not work because it applies before the header is parsed,
3270 so that prevents haproxy from compressing. The "offload" setting should
Willy Tarreauffea9fd2014-07-12 16:37:02 +02003271 then be used for such scenarios. Note: for now, the "offload" setting is
3272 ignored when set in a defaults section.
William Lallemand82fe75c2012-10-23 10:25:10 +02003273
William Lallemand05097442012-11-20 12:14:28 +01003274 Compression is disabled when:
Baptiste Assmann650d53d2013-01-05 15:44:44 +01003275 * the request does not advertise a supported compression algorithm in the
3276 "Accept-Encoding" header
3277 * the response message is not HTTP/1.1
Tim Duesterhusbb48c9a2019-01-30 23:46:04 +01003278 * HTTP status code is not one of 200, 201, 202, or 203
Baptiste Assmann650d53d2013-01-05 15:44:44 +01003279 * response contain neither a "Content-Length" header nor a
3280 "Transfer-Encoding" whose last value is "chunked"
3281 * response contains a "Content-Type" header whose first value starts with
3282 "multipart"
3283 * the response contains the "no-transform" value in the "Cache-control"
3284 header
3285 * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7
3286 and later
3287 * The response contains a "Content-Encoding" header, indicating that the
3288 response is already compressed (see compression offload)
Tim Duesterhusbb48c9a2019-01-30 23:46:04 +01003289 * The response contains an invalid "ETag" header or multiple ETag headers
William Lallemand05097442012-11-20 12:14:28 +01003290
Tim Duesterhusb229f012019-01-29 16:38:56 +01003291 Note: The compression does not emit the Warning header.
William Lallemand05097442012-11-20 12:14:28 +01003292
William Lallemand82fe75c2012-10-23 10:25:10 +02003293 Examples :
3294 compression algo gzip
3295 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01003296
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003297
Willy Tarreau55165fe2009-05-10 12:02:55 +02003298cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02003299 [ postonly ] [ preserve ] [ httponly ] [ secure ]
3300 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Olivier Houchard4e694042017-03-14 20:01:29 +01003301 [ dynamic ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01003302 Enable cookie-based persistence in a backend.
3303 May be used in sections : defaults | frontend | listen | backend
3304 yes | no | yes | yes
3305 Arguments :
3306 <name> is the name of the cookie which will be monitored, modified or
3307 inserted in order to bring persistence. This cookie is sent to
3308 the client via a "Set-Cookie" header in the response, and is
3309 brought back by the client in a "Cookie" header in all requests.
3310 Special care should be taken to choose a name which does not
3311 conflict with any likely application cookie. Also, if the same
Davor Ocelice9ed2812017-12-25 17:49:28 +01003312 backends are subject to be used by the same clients (e.g.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003313 HTTP/HTTPS), care should be taken to use different cookie names
3314 between all backends if persistence between them is not desired.
3315
3316 rewrite This keyword indicates that the cookie will be provided by the
3317 server and that haproxy will have to modify its value to set the
3318 server's identifier in it. This mode is handy when the management
3319 of complex combinations of "Set-cookie" and "Cache-control"
3320 headers is left to the application. The application can then
3321 decide whether or not it is appropriate to emit a persistence
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003322 cookie. Since all responses should be monitored, this mode
3323 doesn't work in HTTP tunnel mode. Unless the application
Davor Ocelice9ed2812017-12-25 17:49:28 +01003324 behavior is very complex and/or broken, it is advised not to
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003325 start with this mode for new deployments. This keyword is
3326 incompatible with "insert" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003327
3328 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02003329 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003330
Willy Tarreaua79094d2010-08-31 22:54:15 +02003331 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003332 server. When used without the "preserve" option, if the server
Michael Prokop4438c602019-05-24 10:25:45 +02003333 emits a cookie with the same name, it will be removed before
Davor Ocelice9ed2812017-12-25 17:49:28 +01003334 processing. For this reason, this mode can be used to upgrade
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003335 existing configurations running in the "rewrite" mode. The cookie
3336 will only be a session cookie and will not be stored on the
3337 client's disk. By default, unless the "indirect" option is added,
3338 the server will see the cookies emitted by the client. Due to
3339 caching effects, it is generally wise to add the "nocache" or
3340 "postonly" keywords (see below). The "insert" keyword is not
3341 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003342
3343 prefix This keyword indicates that instead of relying on a dedicated
3344 cookie for the persistence, an existing one will be completed.
3345 This may be needed in some specific environments where the client
3346 does not support more than one single cookie and the application
3347 already needs it. In this case, whenever the server sets a cookie
3348 named <name>, it will be prefixed with the server's identifier
3349 and a delimiter. The prefix will be removed from all client
3350 requests so that the server still finds the cookie it emitted.
3351 Since all requests and responses are subject to being modified,
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003352 this mode doesn't work with tunnel mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02003353 not compatible with "rewrite" and "insert". Note: it is highly
3354 recommended not to use "indirect" with "prefix", otherwise server
3355 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003356
Willy Tarreaua79094d2010-08-31 22:54:15 +02003357 indirect When this option is specified, no cookie will be emitted to a
3358 client which already has a valid one for the server which has
3359 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003360 it will be removed, unless the "preserve" option is also set. In
3361 "insert" mode, this will additionally remove cookies from the
3362 requests transmitted to the server, making the persistence
3363 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02003364 Note: it is highly recommended not to use "indirect" with
3365 "prefix", otherwise server cookie updates would not be sent to
3366 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003367
3368 nocache This option is recommended in conjunction with the insert mode
3369 when there is a cache between the client and HAProxy, as it
3370 ensures that a cacheable response will be tagged non-cacheable if
3371 a cookie needs to be inserted. This is important because if all
3372 persistence cookies are added on a cacheable home page for
3373 instance, then all customers will then fetch the page from an
3374 outer cache and will all share the same persistence cookie,
3375 leading to one server receiving much more traffic than others.
3376 See also the "insert" and "postonly" options.
3377
3378 postonly This option ensures that cookie insertion will only be performed
3379 on responses to POST requests. It is an alternative to the
3380 "nocache" option, because POST responses are not cacheable, so
3381 this ensures that the persistence cookie will never get cached.
3382 Since most sites do not need any sort of persistence before the
3383 first POST which generally is a login request, this is a very
3384 efficient method to optimize caching without risking to find a
3385 persistence cookie in the cache.
3386 See also the "insert" and "nocache" options.
3387
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003388 preserve This option may only be used with "insert" and/or "indirect". It
3389 allows the server to emit the persistence cookie itself. In this
3390 case, if a cookie is found in the response, haproxy will leave it
3391 untouched. This is useful in order to end persistence after a
3392 logout request for instance. For this, the server just has to
Davor Ocelice9ed2812017-12-25 17:49:28 +01003393 emit a cookie with an invalid value (e.g. empty) or with a date in
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003394 the past. By combining this mechanism with the "disable-on-404"
3395 check option, it is possible to perform a completely graceful
3396 shutdown because users will definitely leave the server after
3397 they logout.
3398
Willy Tarreau4992dd22012-05-31 21:02:17 +02003399 httponly This option tells haproxy to add an "HttpOnly" cookie attribute
3400 when a cookie is inserted. This attribute is used so that a
3401 user agent doesn't share the cookie with non-HTTP components.
3402 Please check RFC6265 for more information on this attribute.
3403
3404 secure This option tells haproxy to add a "Secure" cookie attribute when
3405 a cookie is inserted. This attribute is used so that a user agent
3406 never emits this cookie over non-secure channels, which means
3407 that a cookie learned with this flag will be presented only over
3408 SSL/TLS connections. Please check RFC6265 for more information on
3409 this attribute.
3410
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02003411 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003412 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01003413 name. If the domain begins with a dot, the browser is allowed to
3414 use it for any host ending with that name. It is also possible to
3415 specify several domain names by invoking this option multiple
3416 times. Some browsers might have small limits on the number of
3417 domains, so be careful when doing that. For the record, sending
3418 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02003419
Willy Tarreau996a92c2010-10-13 19:30:47 +02003420 maxidle This option allows inserted cookies to be ignored after some idle
3421 time. It only works with insert-mode cookies. When a cookie is
3422 sent to the client, the date this cookie was emitted is sent too.
3423 Upon further presentations of this cookie, if the date is older
3424 than the delay indicated by the parameter (in seconds), it will
3425 be ignored. Otherwise, it will be refreshed if needed when the
3426 response is sent to the client. This is particularly useful to
3427 prevent users who never close their browsers from remaining for
Davor Ocelice9ed2812017-12-25 17:49:28 +01003428 too long on the same server (e.g. after a farm size change). When
Willy Tarreau996a92c2010-10-13 19:30:47 +02003429 this option is set and a cookie has no date, it is always
3430 accepted, but gets refreshed in the response. This maintains the
3431 ability for admins to access their sites. Cookies that have a
3432 date in the future further than 24 hours are ignored. Doing so
3433 lets admins fix timezone issues without risking kicking users off
3434 the site.
3435
3436 maxlife This option allows inserted cookies to be ignored after some life
3437 time, whether they're in use or not. It only works with insert
3438 mode cookies. When a cookie is first sent to the client, the date
3439 this cookie was emitted is sent too. Upon further presentations
3440 of this cookie, if the date is older than the delay indicated by
3441 the parameter (in seconds), it will be ignored. If the cookie in
3442 the request has no date, it is accepted and a date will be set.
3443 Cookies that have a date in the future further than 24 hours are
3444 ignored. Doing so lets admins fix timezone issues without risking
3445 kicking users off the site. Contrary to maxidle, this value is
3446 not refreshed, only the first visit date counts. Both maxidle and
3447 maxlife may be used at the time. This is particularly useful to
3448 prevent users who never close their browsers from remaining for
Davor Ocelice9ed2812017-12-25 17:49:28 +01003449 too long on the same server (e.g. after a farm size change). This
Willy Tarreau996a92c2010-10-13 19:30:47 +02003450 is stronger than the maxidle method in that it forces a
3451 redispatch after some absolute delay.
3452
Olivier Houchard4e694042017-03-14 20:01:29 +01003453 dynamic Activate dynamic cookies. When used, a session cookie is
3454 dynamically created for each server, based on the IP and port
3455 of the server, and a secret key, specified in the
3456 "dynamic-cookie-key" backend directive.
3457 The cookie will be regenerated each time the IP address change,
3458 and is only generated for IPv4/IPv6.
3459
Willy Tarreau0ba27502007-12-24 16:55:16 +01003460 There can be only one persistence cookie per HTTP backend, and it can be
3461 declared in a defaults section. The value of the cookie will be the value
3462 indicated after the "cookie" keyword in a "server" statement. If no cookie
3463 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02003464
Willy Tarreau0ba27502007-12-24 16:55:16 +01003465 Examples :
3466 cookie JSESSIONID prefix
3467 cookie SRV insert indirect nocache
3468 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02003469 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01003470
Willy Tarreau294d0f02015-08-10 19:40:12 +02003471 See also : "balance source", "capture cookie", "server" and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003472
Willy Tarreau983e01e2010-01-11 18:42:06 +01003473
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02003474declare capture [ request | response ] len <length>
3475 Declares a capture slot.
3476 May be used in sections : defaults | frontend | listen | backend
3477 no | yes | yes | no
3478 Arguments:
3479 <length> is the length allowed for the capture.
3480
3481 This declaration is only available in the frontend or listen section, but the
3482 reserved slot can be used in the backends. The "request" keyword allocates a
3483 capture slot for use in the request, and "response" allocates a capture slot
3484 for use in the response.
3485
3486 See also: "capture-req", "capture-res" (sample converters),
Baptiste Assmann5ac425c2015-10-21 23:13:46 +02003487 "capture.req.hdr", "capture.res.hdr" (sample fetches),
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02003488 "http-request capture" and "http-response capture".
3489
3490
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003491default-server [param*]
3492 Change default options for a server in a backend
3493 May be used in sections : defaults | frontend | listen | backend
3494 yes | no | yes | yes
3495 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01003496 <param*> is a list of parameters for this server. The "default-server"
3497 keyword accepts an important number of options and has a complete
3498 section dedicated to it. Please refer to section 5 for more
3499 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003500
Willy Tarreau983e01e2010-01-11 18:42:06 +01003501 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003502 default-server inter 1000 weight 13
3503
3504 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01003505
Willy Tarreau983e01e2010-01-11 18:42:06 +01003506
Willy Tarreau0ba27502007-12-24 16:55:16 +01003507default_backend <backend>
3508 Specify the backend to use when no "use_backend" rule has been matched.
3509 May be used in sections : defaults | frontend | listen | backend
3510 yes | yes | yes | no
3511 Arguments :
3512 <backend> is the name of the backend to use.
3513
3514 When doing content-switching between frontend and backends using the
3515 "use_backend" keyword, it is often useful to indicate which backend will be
3516 used when no rule has matched. It generally is the dynamic backend which
3517 will catch all undetermined requests.
3518
Willy Tarreau0ba27502007-12-24 16:55:16 +01003519 Example :
3520
3521 use_backend dynamic if url_dyn
3522 use_backend static if url_css url_img extension_img
3523 default_backend dynamic
3524
Willy Tarreau98d04852015-05-26 12:18:29 +02003525 See also : "use_backend"
Willy Tarreau2769aa02007-12-27 18:26:09 +01003526
Willy Tarreau0ba27502007-12-24 16:55:16 +01003527
Baptiste Assmann27f51342013-10-09 06:51:49 +02003528description <string>
3529 Describe a listen, frontend or backend.
3530 May be used in sections : defaults | frontend | listen | backend
3531 no | yes | yes | yes
3532 Arguments : string
3533
3534 Allows to add a sentence to describe the related object in the HAProxy HTML
3535 stats page. The description will be printed on the right of the object name
3536 it describes.
3537 No need to backslash spaces in the <string> arguments.
3538
3539
Willy Tarreau0ba27502007-12-24 16:55:16 +01003540disabled
3541 Disable a proxy, frontend or backend.
3542 May be used in sections : defaults | frontend | listen | backend
3543 yes | yes | yes | yes
3544 Arguments : none
3545
3546 The "disabled" keyword is used to disable an instance, mainly in order to
3547 liberate a listening port or to temporarily disable a service. The instance
3548 will still be created and its configuration will be checked, but it will be
3549 created in the "stopped" state and will appear as such in the statistics. It
3550 will not receive any traffic nor will it send any health-checks or logs. It
3551 is possible to disable many instances at once by adding the "disabled"
3552 keyword in a "defaults" section.
3553
3554 See also : "enabled"
3555
3556
Willy Tarreau5ce94572010-06-07 14:35:41 +02003557dispatch <address>:<port>
3558 Set a default server address
3559 May be used in sections : defaults | frontend | listen | backend
3560 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003561 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02003562
3563 <address> is the IPv4 address of the default server. Alternatively, a
3564 resolvable hostname is supported, but this name will be resolved
3565 during start-up.
3566
3567 <ports> is a mandatory port specification. All connections will be sent
3568 to this port, and it is not permitted to use port offsets as is
3569 possible with normal servers.
3570
Willy Tarreau787aed52011-04-15 06:45:37 +02003571 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02003572 server can take the connection. In the past it was used to forward non
3573 persistent connections to an auxiliary load balancer. Due to its simple
3574 syntax, it has also been used for simple TCP relays. It is recommended not to
3575 use it for more clarity, and to use the "server" directive instead.
3576
3577 See also : "server"
3578
Olivier Houchard4e694042017-03-14 20:01:29 +01003579
3580dynamic-cookie-key <string>
3581 Set the dynamic cookie secret key for a backend.
3582 May be used in sections : defaults | frontend | listen | backend
3583 yes | no | yes | yes
3584 Arguments : The secret key to be used.
3585
3586 When dynamic cookies are enabled (see the "dynamic" directive for cookie),
Davor Ocelice9ed2812017-12-25 17:49:28 +01003587 a dynamic cookie is created for each server (unless one is explicitly
Olivier Houchard4e694042017-03-14 20:01:29 +01003588 specified on the "server" line), using a hash of the IP address of the
3589 server, the TCP port, and the secret key.
Davor Ocelice9ed2812017-12-25 17:49:28 +01003590 That way, we can ensure session persistence across multiple load-balancers,
Olivier Houchard4e694042017-03-14 20:01:29 +01003591 even if servers are dynamically added or removed.
Willy Tarreau5ce94572010-06-07 14:35:41 +02003592
Willy Tarreau0ba27502007-12-24 16:55:16 +01003593enabled
3594 Enable a proxy, frontend or backend.
3595 May be used in sections : defaults | frontend | listen | backend
3596 yes | yes | yes | yes
3597 Arguments : none
3598
3599 The "enabled" keyword is used to explicitly enable an instance, when the
3600 defaults has been set to "disabled". This is very rarely used.
3601
3602 See also : "disabled"
3603
3604
3605errorfile <code> <file>
3606 Return a file contents instead of errors generated by HAProxy
3607 May be used in sections : defaults | frontend | listen | backend
3608 yes | yes | yes | yes
3609 Arguments :
3610 <code> is the HTTP status code. Currently, HAProxy is capable of
Florian Tham9205fea2020-01-08 13:35:30 +01003611 generating codes 200, 400, 403, 404, 405, 408, 410, 425, 429, 500,
3612 502, 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003613
3614 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003615 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01003616 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01003617 error pages, and to use absolute paths, since files are read
3618 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003619
3620 It is important to understand that this keyword is not meant to rewrite
3621 errors returned by the server, but errors detected and returned by HAProxy.
3622 This is why the list of supported errors is limited to a small set.
3623
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003624 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
3625
Willy Tarreau0ba27502007-12-24 16:55:16 +01003626 The files are returned verbatim on the TCP socket. This allows any trick such
3627 as redirections to another URL or site, as well as tricks to clean cookies,
3628 force enable or disable caching, etc... The package provides default error
3629 files returning the same contents as default errors.
3630
Willy Tarreau59140a22009-02-22 12:02:30 +01003631 The files should not exceed the configured buffer size (BUFSIZE), which
3632 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
Davor Ocelice9ed2812017-12-25 17:49:28 +01003633 not to put any reference to local contents (e.g. images) in order to avoid
Willy Tarreau59140a22009-02-22 12:02:30 +01003634 loops between the client and HAProxy when all servers are down, causing an
3635 error to be returned instead of an image. For better HTTP compliance, it is
3636 recommended that all header lines end with CR-LF and not LF alone.
3637
Willy Tarreau0ba27502007-12-24 16:55:16 +01003638 The files are read at the same time as the configuration and kept in memory.
3639 For this reason, the errors continue to be returned even when the process is
3640 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01003641 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01003642 403 status code and interrogating a blocked URL.
3643
3644 See also : "errorloc", "errorloc302", "errorloc303"
3645
Willy Tarreau59140a22009-02-22 12:02:30 +01003646 Example :
3647 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
Willy Tarreau989222a2016-01-15 10:26:26 +01003648 errorfile 408 /dev/null # work around Chrome pre-connect bug
Willy Tarreau59140a22009-02-22 12:02:30 +01003649 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
3650 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
3651
Willy Tarreau2769aa02007-12-27 18:26:09 +01003652
3653errorloc <code> <url>
3654errorloc302 <code> <url>
3655 Return an HTTP redirection to a URL instead of errors generated by HAProxy
3656 May be used in sections : defaults | frontend | listen | backend
3657 yes | yes | yes | yes
3658 Arguments :
3659 <code> is the HTTP status code. Currently, HAProxy is capable of
Florian Tham9205fea2020-01-08 13:35:30 +01003660 generating codes 200, 400, 403, 404, 405, 408, 410, 425, 429, 500,
3661 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003662
3663 <url> it is the exact contents of the "Location" header. It may contain
3664 either a relative URI to an error page hosted on the same site,
3665 or an absolute URI designating an error page on another site.
3666 Special care should be given to relative URIs to avoid redirect
Davor Ocelice9ed2812017-12-25 17:49:28 +01003667 loops if the URI itself may generate the same error (e.g. 500).
Willy Tarreau2769aa02007-12-27 18:26:09 +01003668
3669 It is important to understand that this keyword is not meant to rewrite
3670 errors returned by the server, but errors detected and returned by HAProxy.
3671 This is why the list of supported errors is limited to a small set.
3672
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003673 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
3674
Willy Tarreau2769aa02007-12-27 18:26:09 +01003675 Note that both keyword return the HTTP 302 status code, which tells the
3676 client to fetch the designated URL using the same HTTP method. This can be
3677 quite problematic in case of non-GET methods such as POST, because the URL
3678 sent to the client might not be allowed for something other than GET. To
Willy Tarreau989222a2016-01-15 10:26:26 +01003679 work around this problem, please use "errorloc303" which send the HTTP 303
Willy Tarreau2769aa02007-12-27 18:26:09 +01003680 status code, indicating to the client that the URL must be fetched with a GET
3681 request.
3682
3683 See also : "errorfile", "errorloc303"
3684
3685
3686errorloc303 <code> <url>
3687 Return an HTTP redirection to a URL instead of errors generated by HAProxy
3688 May be used in sections : defaults | frontend | listen | backend
3689 yes | yes | yes | yes
3690 Arguments :
3691 <code> is the HTTP status code. Currently, HAProxy is capable of
Florian Tham9205fea2020-01-08 13:35:30 +01003692 generating codes 200, 400, 403, 404, 405, 408, 410, 425, 429, 500,
3693 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003694
3695 <url> it is the exact contents of the "Location" header. It may contain
3696 either a relative URI to an error page hosted on the same site,
3697 or an absolute URI designating an error page on another site.
3698 Special care should be given to relative URIs to avoid redirect
Davor Ocelice9ed2812017-12-25 17:49:28 +01003699 loops if the URI itself may generate the same error (e.g. 500).
Willy Tarreau2769aa02007-12-27 18:26:09 +01003700
3701 It is important to understand that this keyword is not meant to rewrite
3702 errors returned by the server, but errors detected and returned by HAProxy.
3703 This is why the list of supported errors is limited to a small set.
3704
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003705 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
3706
Willy Tarreau2769aa02007-12-27 18:26:09 +01003707 Note that both keyword return the HTTP 303 status code, which tells the
3708 client to fetch the designated URL using the same HTTP GET method. This
3709 solves the usual problems associated with "errorloc" and the 302 code. It is
3710 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003711 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003712
3713 See also : "errorfile", "errorloc", "errorloc302"
3714
3715
Simon Horman51a1cf62015-02-03 13:00:44 +09003716email-alert from <emailaddr>
3717 Declare the from email address to be used in both the envelope and header
Davor Ocelice9ed2812017-12-25 17:49:28 +01003718 of email alerts. This is the address that email alerts are sent from.
Simon Horman51a1cf62015-02-03 13:00:44 +09003719 May be used in sections: defaults | frontend | listen | backend
3720 yes | yes | yes | yes
3721
3722 Arguments :
3723
3724 <emailaddr> is the from email address to use when sending email alerts
3725
3726 Also requires "email-alert mailers" and "email-alert to" to be set
3727 and if so sending email alerts is enabled for the proxy.
3728
Simon Horman64e34162015-02-06 11:11:57 +09003729 See also : "email-alert level", "email-alert mailers",
Cyril Bonté307ee1e2015-09-28 23:16:06 +02003730 "email-alert myhostname", "email-alert to", section 3.6 about
3731 mailers.
Simon Horman64e34162015-02-06 11:11:57 +09003732
3733
3734email-alert level <level>
3735 Declare the maximum log level of messages for which email alerts will be
3736 sent. This acts as a filter on the sending of email alerts.
3737 May be used in sections: defaults | frontend | listen | backend
3738 yes | yes | yes | yes
3739
3740 Arguments :
3741
3742 <level> One of the 8 syslog levels:
3743 emerg alert crit err warning notice info debug
3744 The above syslog levels are ordered from lowest to highest.
3745
3746 By default level is alert
3747
3748 Also requires "email-alert from", "email-alert mailers" and
3749 "email-alert to" to be set and if so sending email alerts is enabled
3750 for the proxy.
3751
Simon Horman1421e212015-04-30 13:10:35 +09003752 Alerts are sent when :
3753
3754 * An un-paused server is marked as down and <level> is alert or lower
3755 * A paused server is marked as down and <level> is notice or lower
3756 * A server is marked as up or enters the drain state and <level>
3757 is notice or lower
3758 * "option log-health-checks" is enabled, <level> is info or lower,
3759 and a health check status update occurs
3760
Simon Horman64e34162015-02-06 11:11:57 +09003761 See also : "email-alert from", "email-alert mailers",
3762 "email-alert myhostname", "email-alert to",
Simon Horman51a1cf62015-02-03 13:00:44 +09003763 section 3.6 about mailers.
3764
3765
3766email-alert mailers <mailersect>
3767 Declare the mailers to be used when sending email alerts
3768 May be used in sections: defaults | frontend | listen | backend
3769 yes | yes | yes | yes
3770
3771 Arguments :
3772
3773 <mailersect> is the name of the mailers section to send email alerts.
3774
3775 Also requires "email-alert from" and "email-alert to" to be set
3776 and if so sending email alerts is enabled for the proxy.
3777
Simon Horman64e34162015-02-06 11:11:57 +09003778 See also : "email-alert from", "email-alert level", "email-alert myhostname",
3779 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09003780
3781
3782email-alert myhostname <hostname>
3783 Declare the to hostname address to be used when communicating with
3784 mailers.
3785 May be used in sections: defaults | frontend | listen | backend
3786 yes | yes | yes | yes
3787
3788 Arguments :
3789
Baptiste Assmann738bad92015-12-21 15:27:53 +01003790 <hostname> is the hostname to use when communicating with mailers
Simon Horman51a1cf62015-02-03 13:00:44 +09003791
3792 By default the systems hostname is used.
3793
3794 Also requires "email-alert from", "email-alert mailers" and
3795 "email-alert to" to be set and if so sending email alerts is enabled
3796 for the proxy.
3797
Simon Horman64e34162015-02-06 11:11:57 +09003798 See also : "email-alert from", "email-alert level", "email-alert mailers",
3799 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09003800
3801
3802email-alert to <emailaddr>
Davor Ocelice9ed2812017-12-25 17:49:28 +01003803 Declare both the recipient address in the envelope and to address in the
Simon Horman51a1cf62015-02-03 13:00:44 +09003804 header of email alerts. This is the address that email alerts are sent to.
3805 May be used in sections: defaults | frontend | listen | backend
3806 yes | yes | yes | yes
3807
3808 Arguments :
3809
3810 <emailaddr> is the to email address to use when sending email alerts
3811
3812 Also requires "email-alert mailers" and "email-alert to" to be set
3813 and if so sending email alerts is enabled for the proxy.
3814
Simon Horman64e34162015-02-06 11:11:57 +09003815 See also : "email-alert from", "email-alert level", "email-alert mailers",
Simon Horman51a1cf62015-02-03 13:00:44 +09003816 "email-alert myhostname", section 3.6 about mailers.
3817
3818
Willy Tarreau4de91492010-01-22 19:10:05 +01003819force-persist { if | unless } <condition>
3820 Declare a condition to force persistence on down servers
3821 May be used in sections: defaults | frontend | listen | backend
Cyril Bonté4288c5a2018-03-12 22:02:59 +01003822 no | no | yes | yes
Willy Tarreau4de91492010-01-22 19:10:05 +01003823
3824 By default, requests are not dispatched to down servers. It is possible to
3825 force this using "option persist", but it is unconditional and redispatches
3826 to a valid server if "option redispatch" is set. That leaves with very little
3827 possibilities to force some requests to reach a server which is artificially
3828 marked down for maintenance operations.
3829
3830 The "force-persist" statement allows one to declare various ACL-based
3831 conditions which, when met, will cause a request to ignore the down status of
3832 a server and still try to connect to it. That makes it possible to start a
3833 server, still replying an error to the health checks, and run a specially
3834 configured browser to test the service. Among the handy methods, one could
3835 use a specific source IP address, or a specific cookie. The cookie also has
3836 the advantage that it can easily be added/removed on the browser from a test
3837 page. Once the service is validated, it is then possible to open the service
3838 to the world by returning a valid response to health checks.
3839
3840 The forced persistence is enabled when an "if" condition is met, or unless an
3841 "unless" condition is met. The final redispatch is always disabled when this
3842 is used.
3843
Cyril Bonté0d4bf012010-04-25 23:21:46 +02003844 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02003845 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01003846
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003847
3848filter <name> [param*]
3849 Add the filter <name> in the filter list attached to the proxy.
3850 May be used in sections : defaults | frontend | listen | backend
3851 no | yes | yes | yes
3852 Arguments :
3853 <name> is the name of the filter. Officially supported filters are
3854 referenced in section 9.
3855
Tim Düsterhus4896c442016-11-29 02:15:19 +01003856 <param*> is a list of parameters accepted by the filter <name>. The
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003857 parsing of these parameters are the responsibility of the
Tim Düsterhus4896c442016-11-29 02:15:19 +01003858 filter. Please refer to the documentation of the corresponding
3859 filter (section 9) for all details on the supported parameters.
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003860
3861 Multiple occurrences of the filter line can be used for the same proxy. The
3862 same filter can be referenced many times if needed.
3863
3864 Example:
3865 listen
3866 bind *:80
3867
3868 filter trace name BEFORE-HTTP-COMP
3869 filter compression
3870 filter trace name AFTER-HTTP-COMP
3871
3872 compression algo gzip
3873 compression offload
3874
3875 server srv1 192.168.0.1:80
3876
3877 See also : section 9.
3878
Willy Tarreau4de91492010-01-22 19:10:05 +01003879
Willy Tarreau2769aa02007-12-27 18:26:09 +01003880fullconn <conns>
3881 Specify at what backend load the servers will reach their maxconn
3882 May be used in sections : defaults | frontend | listen | backend
3883 yes | no | yes | yes
3884 Arguments :
3885 <conns> is the number of connections on the backend which will make the
3886 servers use the maximal number of connections.
3887
Willy Tarreau198a7442008-01-17 12:05:32 +01003888 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01003889 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01003890 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01003891 load. The server will then always accept at least <minconn> connections,
3892 never more than <maxconn>, and the limit will be on the ramp between both
3893 values when the backend has less than <conns> concurrent connections. This
3894 makes it possible to limit the load on the servers during normal loads, but
3895 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003896 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003897
Willy Tarreaufbb78422011-06-05 15:38:35 +02003898 Since it's hard to get this value right, haproxy automatically sets it to
3899 10% of the sum of the maxconns of all frontends that may branch to this
Bertrand Jacquin702d44f2013-11-19 11:43:06 +01003900 backend (based on "use_backend" and "default_backend" rules). That way it's
3901 safe to leave it unset. However, "use_backend" involving dynamic names are
3902 not counted since there is no way to know if they could match or not.
Willy Tarreaufbb78422011-06-05 15:38:35 +02003903
Willy Tarreau2769aa02007-12-27 18:26:09 +01003904 Example :
3905 # The servers will accept between 100 and 1000 concurrent connections each
3906 # and the maximum of 1000 will be reached when the backend reaches 10000
3907 # connections.
3908 backend dynamic
3909 fullconn 10000
3910 server srv1 dyn1:80 minconn 100 maxconn 1000
3911 server srv2 dyn2:80 minconn 100 maxconn 1000
3912
3913 See also : "maxconn", "server"
3914
3915
3916grace <time>
3917 Maintain a proxy operational for some time after a soft stop
3918 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01003919 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01003920 Arguments :
3921 <time> is the time (by default in milliseconds) for which the instance
3922 will remain operational with the frontend sockets still listening
3923 when a soft-stop is received via the SIGUSR1 signal.
3924
3925 This may be used to ensure that the services disappear in a certain order.
3926 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003927 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01003928 needed by the equipment to detect the failure.
3929
3930 Note that currently, there is very little benefit in using this parameter,
3931 and it may in fact complicate the soft-reconfiguration process more than
3932 simplify it.
3933
Willy Tarreau0ba27502007-12-24 16:55:16 +01003934
Andrew Rodland17be45e2016-10-25 17:04:12 -04003935hash-balance-factor <factor>
3936 Specify the balancing factor for bounded-load consistent hashing
3937 May be used in sections : defaults | frontend | listen | backend
3938 yes | no | no | yes
3939 Arguments :
3940 <factor> is the control for the maximum number of concurrent requests to
3941 send to a server, expressed as a percentage of the average number
Frédéric Lécaille93d33162019-03-06 09:35:59 +01003942 of concurrent requests across all of the active servers.
Andrew Rodland17be45e2016-10-25 17:04:12 -04003943
3944 Specifying a "hash-balance-factor" for a server with "hash-type consistent"
3945 enables an algorithm that prevents any one server from getting too many
3946 requests at once, even if some hash buckets receive many more requests than
3947 others. Setting <factor> to 0 (the default) disables the feature. Otherwise,
3948 <factor> is a percentage greater than 100. For example, if <factor> is 150,
3949 then no server will be allowed to have a load more than 1.5 times the average.
3950 If server weights are used, they will be respected.
3951
3952 If the first-choice server is disqualified, the algorithm will choose another
3953 server based on the request hash, until a server with additional capacity is
3954 found. A higher <factor> allows more imbalance between the servers, while a
3955 lower <factor> means that more servers will be checked on average, affecting
3956 performance. Reasonable values are from 125 to 200.
3957
Willy Tarreau760e81d2018-05-03 07:20:40 +02003958 This setting is also used by "balance random" which internally relies on the
3959 consistent hashing mechanism.
3960
Andrew Rodland17be45e2016-10-25 17:04:12 -04003961 See also : "balance" and "hash-type".
3962
3963
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003964hash-type <method> <function> <modifier>
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003965 Specify a method to use for mapping hashes to servers
3966 May be used in sections : defaults | frontend | listen | backend
3967 yes | no | yes | yes
3968 Arguments :
Bhaskar98634f02013-10-29 23:30:51 -04003969 <method> is the method used to select a server from the hash computed by
3970 the <function> :
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003971
Bhaskar98634f02013-10-29 23:30:51 -04003972 map-based the hash table is a static array containing all alive servers.
3973 The hashes will be very smooth, will consider weights, but
3974 will be static in that weight changes while a server is up
3975 will be ignored. This means that there will be no slow start.
3976 Also, since a server is selected by its position in the array,
3977 most mappings are changed when the server count changes. This
3978 means that when a server goes up or down, or when a server is
3979 added to a farm, most connections will be redistributed to
3980 different servers. This can be inconvenient with caches for
3981 instance.
Willy Tarreau798a39c2010-11-24 15:04:29 +01003982
Bhaskar98634f02013-10-29 23:30:51 -04003983 consistent the hash table is a tree filled with many occurrences of each
3984 server. The hash key is looked up in the tree and the closest
3985 server is chosen. This hash is dynamic, it supports changing
3986 weights while the servers are up, so it is compatible with the
3987 slow start feature. It has the advantage that when a server
3988 goes up or down, only its associations are moved. When a
3989 server is added to the farm, only a few part of the mappings
3990 are redistributed, making it an ideal method for caches.
3991 However, due to its principle, the distribution will never be
3992 very smooth and it may sometimes be necessary to adjust a
3993 server's weight or its ID to get a more balanced distribution.
3994 In order to get the same distribution on multiple load
3995 balancers, it is important that all servers have the exact
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003996 same IDs. Note: consistent hash uses sdbm and avalanche if no
3997 hash function is specified.
Bhaskar98634f02013-10-29 23:30:51 -04003998
3999 <function> is the hash function to be used :
4000
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03004001 sdbm this function was created initially for sdbm (a public-domain
Bhaskar98634f02013-10-29 23:30:51 -04004002 reimplementation of ndbm) database library. It was found to do
4003 well in scrambling bits, causing better distribution of the keys
4004 and fewer splits. It also happens to be a good general hashing
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004005 function with good distribution, unless the total server weight
4006 is a multiple of 64, in which case applying the avalanche
4007 modifier may help.
Bhaskar98634f02013-10-29 23:30:51 -04004008
4009 djb2 this function was first proposed by Dan Bernstein many years ago
4010 on comp.lang.c. Studies have shown that for certain workload this
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004011 function provides a better distribution than sdbm. It generally
4012 works well with text-based inputs though it can perform extremely
4013 poorly with numeric-only input or when the total server weight is
4014 a multiple of 33, unless the avalanche modifier is also used.
4015
Willy Tarreaua0f42712013-11-14 14:30:35 +01004016 wt6 this function was designed for haproxy while testing other
4017 functions in the past. It is not as smooth as the other ones, but
4018 is much less sensible to the input data set or to the number of
4019 servers. It can make sense as an alternative to sdbm+avalanche or
4020 djb2+avalanche for consistent hashing or when hashing on numeric
4021 data such as a source IP address or a visitor identifier in a URL
4022 parameter.
4023
Willy Tarreau324f07f2015-01-20 19:44:50 +01004024 crc32 this is the most common CRC32 implementation as used in Ethernet,
4025 gzip, PNG, etc. It is slower than the other ones but may provide
4026 a better distribution or less predictable results especially when
4027 used on strings.
4028
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004029 <modifier> indicates an optional method applied after hashing the key :
4030
4031 avalanche This directive indicates that the result from the hash
4032 function above should not be used in its raw form but that
4033 a 4-byte full avalanche hash must be applied first. The
4034 purpose of this step is to mix the resulting bits from the
4035 previous hash in order to avoid any undesired effect when
4036 the input contains some limited values or when the number of
4037 servers is a multiple of one of the hash's components (64
4038 for SDBM, 33 for DJB2). Enabling avalanche tends to make the
4039 result less predictable, but it's also not as smooth as when
4040 using the original function. Some testing might be needed
4041 with some workloads. This hash is one of the many proposed
4042 by Bob Jenkins.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004043
Bhaskar98634f02013-10-29 23:30:51 -04004044 The default hash type is "map-based" and is recommended for most usages. The
4045 default function is "sdbm", the selection of a function should be based on
4046 the range of the values being hashed.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004047
Andrew Rodland17be45e2016-10-25 17:04:12 -04004048 See also : "balance", "hash-balance-factor", "server"
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004049
4050
Willy Tarreau0ba27502007-12-24 16:55:16 +01004051http-check disable-on-404
4052 Enable a maintenance mode upon HTTP/404 response to health-checks
4053 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01004054 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01004055 Arguments : none
4056
4057 When this option is set, a server which returns an HTTP code 404 will be
4058 excluded from further load-balancing, but will still receive persistent
4059 connections. This provides a very convenient method for Web administrators
4060 to perform a graceful shutdown of their servers. It is also important to note
4061 that a server which is detected as failed while it was in this mode will not
4062 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
4063 will immediately be reinserted into the farm. The status on the stats page
4064 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01004065 option only works in conjunction with the "httpchk" option. If this option
4066 is used with "http-check expect", then it has precedence over it so that 404
4067 responses will still be considered as soft-stop.
4068
4069 See also : "option httpchk", "http-check expect"
4070
4071
4072http-check expect [!] <match> <pattern>
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004073 Make HTTP health checks consider response contents or specific status codes
Willy Tarreaubd741542010-03-16 18:46:54 +01004074 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau1ee51a62011-08-19 20:04:17 +02004075 yes | no | yes | yes
Willy Tarreaubd741542010-03-16 18:46:54 +01004076 Arguments :
4077 <match> is a keyword indicating how to look for a specific pattern in the
4078 response. The keyword may be one of "status", "rstatus",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004079 "string", or "rstring". The keyword may be preceded by an
Willy Tarreaubd741542010-03-16 18:46:54 +01004080 exclamation mark ("!") to negate the match. Spaces are allowed
4081 between the exclamation mark and the keyword. See below for more
4082 details on the supported keywords.
4083
4084 <pattern> is the pattern to look for. It may be a string or a regular
4085 expression. If the pattern contains spaces, they must be escaped
4086 with the usual backslash ('\').
4087
4088 By default, "option httpchk" considers that response statuses 2xx and 3xx
4089 are valid, and that others are invalid. When "http-check expect" is used,
4090 it defines what is considered valid or invalid. Only one "http-check"
4091 statement is supported in a backend. If a server fails to respond or times
4092 out, the check obviously fails. The available matches are :
4093
4094 status <string> : test the exact string match for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004095 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01004096 response's status code is exactly this string. If the
4097 "status" keyword is prefixed with "!", then the response
4098 will be considered invalid if the status code matches.
4099
4100 rstatus <regex> : test a regular expression for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004101 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01004102 response's status code matches the expression. If the
4103 "rstatus" keyword is prefixed with "!", then the response
4104 will be considered invalid if the status code matches.
4105 This is mostly used to check for multiple codes.
4106
4107 string <string> : test the exact string match in the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004108 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01004109 response's body contains this exact string. If the
4110 "string" keyword is prefixed with "!", then the response
4111 will be considered invalid if the body contains this
4112 string. This can be used to look for a mandatory word at
4113 the end of a dynamic page, or to detect a failure when a
Davor Ocelice9ed2812017-12-25 17:49:28 +01004114 specific error appears on the check page (e.g. a stack
Willy Tarreaubd741542010-03-16 18:46:54 +01004115 trace).
4116
4117 rstring <regex> : test a regular expression on the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004118 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01004119 response's body matches this expression. If the "rstring"
4120 keyword is prefixed with "!", then the response will be
4121 considered invalid if the body matches the expression.
4122 This can be used to look for a mandatory word at the end
4123 of a dynamic page, or to detect a failure when a specific
Davor Ocelice9ed2812017-12-25 17:49:28 +01004124 error appears on the check page (e.g. a stack trace).
Willy Tarreaubd741542010-03-16 18:46:54 +01004125
4126 It is important to note that the responses will be limited to a certain size
4127 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
4128 Thus, too large responses may not contain the mandatory pattern when using
4129 "string" or "rstring". If a large response is absolutely required, it is
4130 possible to change the default max size by setting the global variable.
4131 However, it is worth keeping in mind that parsing very large responses can
4132 waste some CPU cycles, especially when regular expressions are used, and that
4133 it is always better to focus the checks on smaller resources.
4134
Cyril Bonté32602d22015-01-30 00:07:07 +01004135 Also "http-check expect" doesn't support HTTP keep-alive. Keep in mind that it
4136 will automatically append a "Connection: close" header, meaning that this
4137 header should not be present in the request provided by "option httpchk".
4138
Willy Tarreaubd741542010-03-16 18:46:54 +01004139 Last, if "http-check expect" is combined with "http-check disable-on-404",
4140 then this last one has precedence when the server responds with 404.
4141
4142 Examples :
4143 # only accept status 200 as valid
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01004144 http-check expect status 200
Willy Tarreaubd741542010-03-16 18:46:54 +01004145
4146 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01004147 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01004148
4149 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01004150 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01004151
4152 # check that we have a correct hexadecimal tag before /html
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03004153 http-check expect rstring <!--tag:[0-9a-f]*--></html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01004154
Willy Tarreaubd741542010-03-16 18:46:54 +01004155 See also : "option httpchk", "http-check disable-on-404"
Willy Tarreau2769aa02007-12-27 18:26:09 +01004156
4157
Willy Tarreauef781042010-01-27 11:53:01 +01004158http-check send-state
4159 Enable emission of a state header with HTTP health checks
4160 May be used in sections : defaults | frontend | listen | backend
4161 yes | no | yes | yes
4162 Arguments : none
4163
4164 When this option is set, haproxy will systematically send a special header
4165 "X-Haproxy-Server-State" with a list of parameters indicating to each server
4166 how they are seen by haproxy. This can be used for instance when a server is
4167 manipulated without access to haproxy and the operator needs to know whether
4168 haproxy still sees it up or not, or if the server is the last one in a farm.
4169
4170 The header is composed of fields delimited by semi-colons, the first of which
4171 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
4172 checks on the total number before transition, just as appears in the stats
4173 interface. Next headers are in the form "<variable>=<value>", indicating in
4174 no specific order some values available in the stats interface :
Joseph Lynch514061c2015-01-15 17:52:59 -08004175 - a variable "address", containing the address of the backend server.
4176 This corresponds to the <address> field in the server declaration. For
4177 unix domain sockets, it will read "unix".
4178
4179 - a variable "port", containing the port of the backend server. This
4180 corresponds to the <port> field in the server declaration. For unix
4181 domain sockets, it will read "unix".
4182
Willy Tarreauef781042010-01-27 11:53:01 +01004183 - a variable "name", containing the name of the backend followed by a slash
4184 ("/") then the name of the server. This can be used when a server is
4185 checked in multiple backends.
4186
4187 - a variable "node" containing the name of the haproxy node, as set in the
4188 global "node" variable, otherwise the system's hostname if unspecified.
4189
4190 - a variable "weight" indicating the weight of the server, a slash ("/")
4191 and the total weight of the farm (just counting usable servers). This
4192 helps to know if other servers are available to handle the load when this
4193 one fails.
4194
4195 - a variable "scur" indicating the current number of concurrent connections
4196 on the server, followed by a slash ("/") then the total number of
4197 connections on all servers of the same backend.
4198
4199 - a variable "qcur" indicating the current number of requests in the
4200 server's queue.
4201
4202 Example of a header received by the application server :
4203 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
4204 scur=13/22; qcur=0
4205
4206 See also : "option httpchk", "http-check disable-on-404"
4207
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004208
4209http-request <action> [options...] [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004210 Access control for Layer 7 requests
4211
4212 May be used in sections: defaults | frontend | listen | backend
4213 no | yes | yes | yes
4214
Willy Tarreau20b0de52012-12-24 15:45:22 +01004215 The http-request statement defines a set of rules which apply to layer 7
4216 processing. The rules are evaluated in their declaration order when they are
4217 met in a frontend, listen or backend section. Any rule may optionally be
4218 followed by an ACL-based condition, in which case it will only be evaluated
4219 if the condition is true.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004220
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004221 The first keyword is the rule's action. The supported actions are described
4222 below.
Willy Tarreau20b0de52012-12-24 15:45:22 +01004223
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004224 There is no limit to the number of http-request statements per instance.
Willy Tarreau20b0de52012-12-24 15:45:22 +01004225
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004226 Example:
4227 acl nagios src 192.168.129.3
4228 acl local_net src 192.168.0.0/16
4229 acl auth_ok http_auth(L1)
Willy Tarreau20b0de52012-12-24 15:45:22 +01004230
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004231 http-request allow if nagios
4232 http-request allow if local_net auth_ok
4233 http-request auth realm Gimme if local_net auth_ok
4234 http-request deny
Willy Tarreau81499eb2012-12-27 12:19:02 +01004235
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004236 Example:
4237 acl key req.hdr(X-Add-Acl-Key) -m found
4238 acl add path /addacl
4239 acl del path /delacl
Willy Tarreau20b0de52012-12-24 15:45:22 +01004240
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004241 acl myhost hdr(Host) -f myhost.lst
Willy Tarreau20b0de52012-12-24 15:45:22 +01004242
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004243 http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add
4244 http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02004245
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004246 Example:
4247 acl value req.hdr(X-Value) -m found
4248 acl setmap path /setmap
4249 acl delmap path /delmap
Sasha Pachev218f0642014-06-16 12:05:59 -06004250
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004251 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
Sasha Pachev218f0642014-06-16 12:05:59 -06004252
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004253 http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value
4254 http-request del-map(map.lst) %[src] if delmap
Sasha Pachev218f0642014-06-16 12:05:59 -06004255
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004256 See also : "stats http-request", section 3.4 about userlists and section 7
4257 about ACL usage.
Sasha Pachev218f0642014-06-16 12:05:59 -06004258
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004259http-request add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004260
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004261 This is used to add a new entry into an ACL. The ACL must be loaded from a
4262 file (even a dummy empty file). The file name of the ACL to be updated is
4263 passed between parentheses. It takes one argument: <key fmt>, which follows
4264 log-format rules, to collect content of the new entry. It performs a lookup
4265 in the ACL before insertion, to avoid duplicated (or more) values. This
4266 lookup is done by a linear search and can be expensive with large lists!
4267 It is the equivalent of the "add acl" command from the stats socket, but can
4268 be triggered by an HTTP request.
Sasha Pachev218f0642014-06-16 12:05:59 -06004269
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004270http-request add-header <name> <fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004271
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004272 This appends an HTTP header field whose name is specified in <name> and
4273 whose value is defined by <fmt> which follows the log-format rules (see
4274 Custom Log Format in section 8.2.4). This is particularly useful to pass
4275 connection-specific information to the server (e.g. the client's SSL
4276 certificate), or to combine several headers into one. This rule is not
4277 final, so it is possible to add other similar rules. Note that header
4278 addition is performed immediately, so one rule might reuse the resulting
4279 header from a previous rule.
Sasha Pachev218f0642014-06-16 12:05:59 -06004280
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004281http-request allow [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004282
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004283 This stops the evaluation of the rules and lets the request pass the check.
4284 No further "http-request" rules are evaluated.
Sasha Pachev218f0642014-06-16 12:05:59 -06004285
Sasha Pachev218f0642014-06-16 12:05:59 -06004286
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004287http-request auth [realm <realm>] [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004288
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004289 This stops the evaluation of the rules and immediately responds with an
4290 HTTP 401 or 407 error code to invite the user to present a valid user name
4291 and password. No further "http-request" rules are evaluated. An optional
4292 "realm" parameter is supported, it sets the authentication realm that is
4293 returned with the response (typically the application's name).
Sasha Pachev218f0642014-06-16 12:05:59 -06004294
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004295 Example:
4296 acl auth_ok http_auth_group(L1) G1
4297 http-request auth unless auth_ok
Sasha Pachev218f0642014-06-16 12:05:59 -06004298
Jarno Huuskonen251a6b72019-01-04 14:05:02 +02004299http-request cache-use <name> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004300
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02004301 See section 6.2 about cache setup.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004302
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004303http-request capture <sample> [ len <length> | id <id> ]
4304 [ { if | unless } <condition> ]
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004305
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004306 This captures sample expression <sample> from the request buffer, and
4307 converts it to a string of at most <len> characters. The resulting string is
4308 stored into the next request "capture" slot, so it will possibly appear next
4309 to some captured HTTP headers. It will then automatically appear in the logs,
4310 and it will be possible to extract it using sample fetch rules to feed it
4311 into headers or anything. The length should be limited given that this size
4312 will be allocated for each capture during the whole session life.
4313 Please check section 7.3 (Fetching samples) and "capture request header" for
4314 more information.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004315
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004316 If the keyword "id" is used instead of "len", the action tries to store the
4317 captured string in a previously declared capture slot. This is useful to run
4318 captures in backends. The slot id can be declared by a previous directive
4319 "http-request capture" or with the "declare capture" keyword. If the slot
4320 <id> doesn't exist, then HAProxy fails parsing the configuration to prevent
4321 unexpected behavior at run time.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004322
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004323http-request del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004324
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004325 This is used to delete an entry from an ACL. The ACL must be loaded from a
4326 file (even a dummy empty file). The file name of the ACL to be updated is
4327 passed between parentheses. It takes one argument: <key fmt>, which follows
4328 log-format rules, to collect content of the entry to delete.
4329 It is the equivalent of the "del acl" command from the stats socket, but can
4330 be triggered by an HTTP request.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004331
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004332http-request del-header <name> [ { if | unless } <condition> ]
Willy Tarreauf4c43c12013-06-11 17:01:13 +02004333
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004334 This removes all HTTP header fields whose name is specified in <name>.
Willy Tarreau9a355ec2013-06-11 17:45:46 +02004335
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004336http-request del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreau42cf39e2013-06-11 18:51:32 +02004337
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004338 This is used to delete an entry from a MAP. The MAP must be loaded from a
4339 file (even a dummy empty file). The file name of the MAP to be updated is
4340 passed between parentheses. It takes one argument: <key fmt>, which follows
4341 log-format rules, to collect content of the entry to delete.
4342 It takes one argument: "file name" It is the equivalent of the "del map"
4343 command from the stats socket, but can be triggered by an HTTP request.
Willy Tarreau51347ed2013-06-11 19:34:13 +02004344
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004345http-request deny [deny_status <status>] [ { if | unless } <condition> ]
Patrick Hemmer268a7072018-05-11 12:52:31 -04004346
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004347 This stops the evaluation of the rules and immediately rejects the request
4348 and emits an HTTP 403 error, or optionally the status code specified as an
4349 argument to "deny_status". The list of permitted status codes is limited to
4350 those that can be overridden by the "errorfile" directive.
4351 No further "http-request" rules are evaluated.
Patrick Hemmer268a7072018-05-11 12:52:31 -04004352
Olivier Houchard602bf7d2019-05-10 13:59:15 +02004353http-request disable-l7-retry [ { if | unless } <condition> ]
4354 This disables any attempt to retry the request if it fails for any other
4355 reason than a connection failure. This can be useful for example to make
4356 sure POST requests aren't retried on failure.
4357
Baptiste Assmann333939c2019-01-21 08:34:50 +01004358http-request do-resolve(<var>,<resolvers>,[ipv4,ipv6]) <expr> :
4359
4360 This action performs a DNS resolution of the output of <expr> and stores
4361 the result in the variable <var>. It uses the DNS resolvers section
4362 pointed by <resolvers>.
4363 It is possible to choose a resolution preference using the optional
4364 arguments 'ipv4' or 'ipv6'.
4365 When performing the DNS resolution, the client side connection is on
4366 pause waiting till the end of the resolution.
4367 If an IP address can be found, it is stored into <var>. If any kind of
4368 error occurs, then <var> is not set.
4369 One can use this action to discover a server IP address at run time and
4370 based on information found in the request (IE a Host header).
4371 If this action is used to find the server's IP address (using the
4372 "set-dst" action), then the server IP address in the backend must be set
4373 to 0.0.0.0.
4374
4375 Example:
4376 resolvers mydns
4377 nameserver local 127.0.0.53:53
4378 nameserver google 8.8.8.8:53
4379 timeout retry 1s
4380 hold valid 10s
4381 hold nx 3s
4382 hold other 3s
4383 hold obsolete 0s
4384 accepted_payload_size 8192
4385
4386 frontend fe
4387 bind 10.42.0.1:80
4388 http-request do-resolve(txn.myip,mydns,ipv4) hdr(Host),lower
4389 http-request capture var(txn.myip) len 40
4390
4391 # return 503 when the variable is not set,
4392 # which mean DNS resolution error
4393 use_backend b_503 unless { var(txn.myip) -m found }
4394
4395 default_backend be
4396
4397 backend b_503
4398 # dummy backend used to return 503.
4399 # one can use the errorfile directive to send a nice
4400 # 503 error page to end users
4401
4402 backend be
4403 # rule to prevent HAProxy from reconnecting to services
4404 # on the local network (forged DNS name used to scan the network)
4405 http-request deny if { var(txn.myip) -m ip 127.0.0.0/8 10.0.0.0/8 }
4406 http-request set-dst var(txn.myip)
4407 server clear 0.0.0.0:0
4408
4409 NOTE: Don't forget to set the "protection" rules to ensure HAProxy won't
4410 be used to scan the network or worst won't loop over itself...
4411
Frédéric Lécaille06f5b642018-11-12 11:01:10 +01004412http-request early-hint <name> <fmt> [ { if | unless } <condition> ]
4413
4414 This is used to build an HTTP 103 Early Hints response prior to any other one.
4415 This appends an HTTP header field to this response whose name is specified in
4416 <name> and whose value is defined by <fmt> which follows the log-format rules
4417 (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 +01004418 to the client some Link headers to preload resources required to render the
4419 HTML documents.
Frédéric Lécaille06f5b642018-11-12 11:01:10 +01004420
4421 See RFC 8297 for more information.
4422
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004423http-request redirect <rule> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004424
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004425 This performs an HTTP redirection based on a redirect rule. This is exactly
4426 the same as the "redirect" statement except that it inserts a redirect rule
4427 which can be processed in the middle of other "http-request" rules and that
4428 these rules use the "log-format" strings. See the "redirect" keyword for the
4429 rule's syntax.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004430
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004431http-request reject [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004432
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004433 This stops the evaluation of the rules and immediately closes the connection
4434 without sending any response. It acts similarly to the
4435 "tcp-request content reject" rules. It can be useful to force an immediate
4436 connection closure on HTTP/2 connections.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004437
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004438http-request replace-header <name> <match-regex> <replace-fmt>
4439 [ { if | unless } <condition> ]
Willy Tarreaua9083d02015-05-08 15:27:59 +02004440
Tim Duesterhus2252beb2019-10-29 00:05:13 +01004441 This matches the value of all occurences of header field <name> against
4442 <match-regex>. Matching is performed case-sensitively. Matching values are
4443 completely replaced by <replace-fmt>. Format characters are allowed in
4444 <replace-fmt> and work like <fmt> arguments in "http-request add-header".
4445 Standard back-references using the backslash ('\') followed by a number are
4446 supported.
Thierry FOURNIER82bf70d2015-05-26 17:58:29 +02004447
Tim Duesterhus2252beb2019-10-29 00:05:13 +01004448 This action acts on whole header lines, regardless of the number of values
4449 they may contain. Thus it is well-suited to process headers naturally
4450 containing commas in their value, such as If-Modified-Since. Headers that
4451 contain a comma-separated list of values, such as Accept, should be processed
4452 using "http-request replace-value".
William Lallemand86d0df02017-11-24 21:36:45 +01004453
Tim Duesterhus2252beb2019-10-29 00:05:13 +01004454 Example:
4455 http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2
4456
4457 # applied to:
4458 Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT;
4459
4460 # outputs:
4461 Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT;
4462
4463 # assuming the backend IP is 192.168.1.20
Willy Tarreau09448f72014-06-25 18:12:15 +02004464
Tim Duesterhus2252beb2019-10-29 00:05:13 +01004465 http-request replace-header User-Agent curl foo
4466
4467 # applied to:
4468 User-Agent: curl/7.47.0
Willy Tarreau09448f72014-06-25 18:12:15 +02004469
Tim Duesterhus2252beb2019-10-29 00:05:13 +01004470 # outputs:
4471 User-Agent: foo
Willy Tarreau09448f72014-06-25 18:12:15 +02004472
Willy Tarreau262c3f12019-12-17 06:52:51 +01004473http-request replace-path <match-regex> <replace-fmt>
4474 [ { if | unless } <condition> ]
4475
4476 This works like "replace-header" except that it works on the request's path
4477 component instead of a header. The path component starts at the first '/'
4478 after an optional scheme+authority. It does contain the query string if any
4479 is present. The replacement does not modify the scheme nor authority.
4480
4481 It is worth noting that regular expressions may be more expensive to evaluate
4482 than certain ACLs, so rare replacements may benefit from a condition to avoid
4483 performing the evaluation at all if it does not match.
4484
4485 Example:
4486 # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 :
4487 http-request replace-path (.*) /foo\1
4488
4489 # suffix /foo : turn /bar?q=1 into /bar/foo?q=1 :
4490 http-request replace-path ([^?]*)(\?(.*))? \1/foo\2
4491
4492 # strip /foo : turn /foo/bar?q=1 into /bar?q=1
4493 http-request replace-path /foo/(.*) /\1
4494 # or more efficient if only some requests match :
4495 http-request replace-path /foo/(.*) /\1 if { url_beg /foo/ }
4496
Willy Tarreau33810222019-06-12 17:44:02 +02004497http-request replace-uri <match-regex> <replace-fmt>
4498 [ { if | unless } <condition> ]
4499
Tim Duesterhus2252beb2019-10-29 00:05:13 +01004500 This works like "replace-header" except that it works on the request's URI part
4501 instead of a header. The URI part may contain an optional scheme, authority or
4502 query string. These are considered to be part of the value that is matched
4503 against.
4504
4505 It is worth noting that regular expressions may be more expensive to evaluate
4506 than certain ACLs, so rare replacements may benefit from a condition to avoid
4507 performing the evaluation at all if it does not match.
Willy Tarreau33810222019-06-12 17:44:02 +02004508
Willy Tarreau62b59132019-12-17 06:51:20 +01004509 IMPORTANT NOTE: historically in HTTP/1.x, the vast majority of requests sent
4510 by browsers use the "origin form", which differs from the "absolute form" in
4511 that they do not contain a scheme nor authority in the URI portion. Mostly
4512 only requests sent to proxies, those forged by hand and some emitted by
4513 certain applications use the absolute form. As such, "replace-uri" usually
4514 works fine most of the time in HTTP/1.x with rules starting with a "/". But
4515 with HTTP/2, clients are encouraged to send absolute URIs only, which look
4516 like the ones HTTP/1 clients use to talk to proxies. Such partial replace-uri
4517 rules may then fail in HTTP/2 when they work in HTTP/1. Either the rules need
Willy Tarreau262c3f12019-12-17 06:52:51 +01004518 to be adapted to optionally match a scheme and authority, or replace-path
4519 should be used.
Willy Tarreau33810222019-06-12 17:44:02 +02004520
Willy Tarreau62b59132019-12-17 06:51:20 +01004521 Example:
4522 # rewrite all "http" absolute requests to "https":
4523 http-request replace-uri ^http://(.*) https://\1
Willy Tarreau33810222019-06-12 17:44:02 +02004524
Willy Tarreau62b59132019-12-17 06:51:20 +01004525 # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 :
4526 http-request replace-uri ([^/:]*://[^/]*)?(.*) \1/foo\2
Willy Tarreau33810222019-06-12 17:44:02 +02004527
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004528http-request replace-value <name> <match-regex> <replace-fmt>
4529 [ { if | unless } <condition> ]
Willy Tarreau09448f72014-06-25 18:12:15 +02004530
Tim Duesterhus2252beb2019-10-29 00:05:13 +01004531 This works like "replace-header" except that it matches the regex against
4532 every comma-delimited value of the header field <name> instead of the
4533 entire header. This is suited for all headers which are allowed to carry
4534 more than one value. An example could be the Accept header.
Willy Tarreau09448f72014-06-25 18:12:15 +02004535
Tim Duesterhus2252beb2019-10-29 00:05:13 +01004536 Example:
4537 http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1
Thierry FOURNIER236657b2015-08-19 08:25:14 +02004538
Tim Duesterhus2252beb2019-10-29 00:05:13 +01004539 # applied to:
4540 X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02004541
Tim Duesterhus2252beb2019-10-29 00:05:13 +01004542 # outputs:
4543 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 +01004544
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004545http-request sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
4546http-request sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004547
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004548 This actions increments the GPC0 or GPC1 counter according with the sticky
4549 counter designated by <sc-id>. If an error occurs, this action silently fails
4550 and the actions evaluation continues.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004551
Cédric Dufour0d7712d2019-11-06 18:38:53 +01004552http-request sc-set-gpt0(<sc-id>) { <int> | <expr> }
4553 [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004554
Cédric Dufour0d7712d2019-11-06 18:38:53 +01004555 This action sets the 32-bit unsigned GPT0 tag according to the sticky counter
4556 designated by <sc-id> and the value of <int>/<expr>. The expected result is a
4557 boolean. If an error occurs, this action silently fails and the actions
4558 evaluation continues.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004559
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004560http-request set-dst <expr> [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004561
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004562 This is used to set the destination IP address to the value of specified
4563 expression. Useful when a proxy in front of HAProxy rewrites destination IP,
4564 but provides the correct IP in a HTTP header; or you want to mask the IP for
4565 privacy. If you want to connect to the new address/port, use '0.0.0.0:0' as a
4566 server address in the backend.
Christopher Faulet85d79c92016-11-09 16:54:56 +01004567
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004568 Arguments:
4569 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
4570 by some converters.
Christopher Faulet85d79c92016-11-09 16:54:56 +01004571
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004572 Example:
4573 http-request set-dst hdr(x-dst)
4574 http-request set-dst dst,ipmask(24)
Christopher Faulet85d79c92016-11-09 16:54:56 +01004575
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004576 When possible, set-dst preserves the original destination port as long as the
4577 address family allows it, otherwise the destination port is set to 0.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004578
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004579http-request set-dst-port <expr> [ { if | unless } <condition> ]
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004580
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004581 This is used to set the destination port address to the value of specified
4582 expression. If you want to connect to the new address/port, use '0.0.0.0:0'
4583 as a server address in the backend.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004584
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004585 Arguments:
4586 <expr> Is a standard HAProxy expression formed by a sample-fetch
4587 followed by some converters.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004588
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004589 Example:
4590 http-request set-dst-port hdr(x-port)
4591 http-request set-dst-port int(4000)
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004592
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004593 When possible, set-dst-port preserves the original destination address as
4594 long as the address family supports a port, otherwise it forces the
4595 destination address to IPv4 "0.0.0.0" before rewriting the port.
William Lallemand44be6402016-05-25 01:51:35 +02004596
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004597http-request set-header <name> <fmt> [ { if | unless } <condition> ]
William Lallemand44be6402016-05-25 01:51:35 +02004598
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004599 This does the same as "http-request add-header" except that the header name
4600 is first removed if it existed. This is useful when passing security
4601 information to the server, where the header must not be manipulated by
4602 external users. Note that the new value is computed before the removal so it
4603 is possible to concatenate a value to an existing header.
William Lallemand44be6402016-05-25 01:51:35 +02004604
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004605 Example:
4606 http-request set-header X-Haproxy-Current-Date %T
4607 http-request set-header X-SSL %[ssl_fc]
4608 http-request set-header X-SSL-Session_ID %[ssl_fc_session_id,hex]
4609 http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
4610 http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
4611 http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
4612 http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
4613 http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
4614 http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
William Lallemand44be6402016-05-25 01:51:35 +02004615
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004616http-request set-log-level <level> [ { if | unless } <condition> ]
William Lallemand44be6402016-05-25 01:51:35 +02004617
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004618 This is used to change the log level of the current request when a certain
4619 condition is met. Valid levels are the 8 syslog levels (see the "log"
4620 keyword) plus the special level "silent" which disables logging for this
4621 request. This rule is not final so the last matching rule wins. This rule
4622 can be useful to disable health checks coming from another equipment.
William Lallemand13e9b0c2016-05-25 02:34:07 +02004623
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004624http-request set-map(<file-name>) <key fmt> <value fmt>
4625 [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02004626
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004627 This is used to add a new entry into a MAP. The MAP must be loaded from a
4628 file (even a dummy empty file). The file name of the MAP to be updated is
4629 passed between parentheses. It takes 2 arguments: <key fmt>, which follows
4630 log-format rules, used to collect MAP key, and <value fmt>, which follows
4631 log-format rules, used to collect content for the new entry.
4632 It performs a lookup in the MAP before insertion, to avoid duplicated (or
4633 more) values. This lookup is done by a linear search and can be expensive
4634 with large lists! It is the equivalent of the "set map" command from the
4635 stats socket, but can be triggered by an HTTP request.
William Lallemand13e9b0c2016-05-25 02:34:07 +02004636
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004637http-request set-mark <mark> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02004638
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004639 This is used to set the Netfilter MARK on all packets sent to the client to
4640 the value passed in <mark> on platforms which support it. This value is an
4641 unsigned 32 bit value which can be matched by netfilter and by the routing
4642 table. It can be expressed both in decimal or hexadecimal format (prefixed by
4643 "0x"). This can be useful to force certain packets to take a different route
4644 (for example a cheaper network path for bulk downloads). This works on Linux
4645 kernels 2.6.32 and above and requires admin privileges.
Willy Tarreau00005ce2016-10-21 15:07:45 +02004646
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004647http-request set-method <fmt> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02004648
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004649 This rewrites the request method with the result of the evaluation of format
4650 string <fmt>. There should be very few valid reasons for having to do so as
4651 this is more likely to break something than to fix it.
William Lallemand13e9b0c2016-05-25 02:34:07 +02004652
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004653http-request set-nice <nice> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02004654
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004655 This sets the "nice" factor of the current request being processed. It only
4656 has effect against the other requests being processed at the same time.
4657 The default value is 0, unless altered by the "nice" setting on the "bind"
4658 line. The accepted range is -1024..1024. The higher the value, the nicest
4659 the request will be. Lower values will make the request more important than
4660 other ones. This can be useful to improve the speed of some requests, or
4661 lower the priority of non-important requests. Using this setting without
4662 prior experimentation can cause some major slowdown.
William Lallemand13e9b0c2016-05-25 02:34:07 +02004663
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004664http-request set-path <fmt> [ { if | unless } <condition> ]
Willy Tarreau00005ce2016-10-21 15:07:45 +02004665
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004666 This rewrites the request path with the result of the evaluation of format
4667 string <fmt>. The query string, if any, is left intact. If a scheme and
4668 authority is found before the path, they are left intact as well. If the
4669 request doesn't have a path ("*"), this one is replaced with the format.
4670 This can be used to prepend a directory component in front of a path for
4671 example. See also "http-request set-query" and "http-request set-uri".
Willy Tarreau2d392c22015-08-24 01:43:45 +02004672
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004673 Example :
4674 # prepend the host name before the path
4675 http-request set-path /%[hdr(host)]%[path]
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004676
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004677http-request set-priority-class <expr> [ { if | unless } <condition> ]
Olivier Houchardccaa7de2017-10-02 11:51:03 +02004678
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004679 This is used to set the queue priority class of the current request.
4680 The value must be a sample expression which converts to an integer in the
4681 range -2047..2047. Results outside this range will be truncated.
4682 The priority class determines the order in which queued requests are
4683 processed. Lower values have higher priority.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004684
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004685http-request set-priority-offset <expr> [ { if | unless } <condition> ]
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004686
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004687 This is used to set the queue priority timestamp offset of the current
4688 request. The value must be a sample expression which converts to an integer
4689 in the range -524287..524287. Results outside this range will be truncated.
4690 When a request is queued, it is ordered first by the priority class, then by
4691 the current timestamp adjusted by the given offset in milliseconds. Lower
4692 values have higher priority.
4693 Note that the resulting timestamp is is only tracked with enough precision
4694 for 524,287ms (8m44s287ms). If the request is queued long enough to where the
4695 adjusted timestamp exceeds this value, it will be misidentified as highest
4696 priority. Thus it is important to set "timeout queue" to a value, where when
4697 combined with the offset, does not exceed this limit.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004698
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004699http-request set-query <fmt> [ { if | unless } <condition> ]
Willy Tarreau20b0de52012-12-24 15:45:22 +01004700
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004701 This rewrites the request's query string which appears after the first
4702 question mark ("?") with the result of the evaluation of format string <fmt>.
4703 The part prior to the question mark is left intact. If the request doesn't
4704 contain a question mark and the new value is not empty, then one is added at
4705 the end of the URI, followed by the new value. If a question mark was
4706 present, it will never be removed even if the value is empty. This can be
4707 used to add or remove parameters from the query string.
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08004708
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004709 See also "http-request set-query" and "http-request set-uri".
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004710
4711 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004712 # replace "%3D" with "=" in the query string
4713 http-request set-query %[query,regsub(%3D,=,g)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004714
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004715http-request set-src <expr> [ { if | unless } <condition> ]
4716 This is used to set the source IP address to the value of specified
4717 expression. Useful when a proxy in front of HAProxy rewrites source IP, but
4718 provides the correct IP in a HTTP header; or you want to mask source IP for
4719 privacy.
4720
4721 Arguments :
4722 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
4723 by some converters.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004724
Cyril Bonté78caf842010-03-10 22:41:43 +01004725 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004726 http-request set-src hdr(x-forwarded-for)
4727 http-request set-src src,ipmask(24)
4728
4729 When possible, set-src preserves the original source port as long as the
4730 address family allows it, otherwise the source port is set to 0.
4731
4732http-request set-src-port <expr> [ { if | unless } <condition> ]
4733
4734 This is used to set the source port address to the value of specified
4735 expression.
4736
4737 Arguments:
4738 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
4739 by some converters.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004740
Willy Tarreau20b0de52012-12-24 15:45:22 +01004741 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004742 http-request set-src-port hdr(x-port)
4743 http-request set-src-port int(4000)
4744
4745 When possible, set-src-port preserves the original source address as long as
4746 the address family supports a port, otherwise it forces the source address to
4747 IPv4 "0.0.0.0" before rewriting the port.
4748
4749http-request set-tos <tos> [ { if | unless } <condition> ]
4750
4751 This is used to set the TOS or DSCP field value of packets sent to the client
4752 to the value passed in <tos> on platforms which support this. This value
4753 represents the whole 8 bits of the IP TOS field, and can be expressed both in
4754 decimal or hexadecimal format (prefixed by "0x"). Note that only the 6 higher
4755 bits are used in DSCP or TOS, and the two lower bits are always 0. This can
4756 be used to adjust some routing behavior on border routers based on some
4757 information from the request.
4758
4759 See RFC 2474, 2597, 3260 and 4594 for more information.
4760
4761http-request set-uri <fmt> [ { if | unless } <condition> ]
4762
4763 This rewrites the request URI with the result of the evaluation of format
4764 string <fmt>. The scheme, authority, path and query string are all replaced
4765 at once. This can be used to rewrite hosts in front of proxies, or to
4766 perform complex modifications to the URI such as moving parts between the
4767 path and the query string.
4768 See also "http-request set-path" and "http-request set-query".
4769
4770http-request set-var(<var-name>) <expr> [ { if | unless } <condition> ]
4771
4772 This is used to set the contents of a variable. The variable is declared
4773 inline.
4774
4775 Arguments:
4776 <var-name> The name of the variable starts with an indication about its
4777 scope. The scopes allowed are:
4778 "proc" : the variable is shared with the whole process
4779 "sess" : the variable is shared with the whole session
4780 "txn" : the variable is shared with the transaction
4781 (request and response)
4782 "req" : the variable is shared only during request
4783 processing
4784 "res" : the variable is shared only during response
4785 processing
4786 This prefix is followed by a name. The separator is a '.'.
4787 The name may only contain characters 'a-z', 'A-Z', '0-9'
4788 and '_'.
4789
4790 <expr> Is a standard HAProxy expression formed by a sample-fetch
4791 followed by some converters.
Willy Tarreau20b0de52012-12-24 15:45:22 +01004792
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004793 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004794 http-request set-var(req.my_var) req.fhdr(user-agent),lower
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004795
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004796http-request send-spoe-group <engine-name> <group-name>
4797 [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004798
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004799 This action is used to trigger sending of a group of SPOE messages. To do so,
4800 the SPOE engine used to send messages must be defined, as well as the SPOE
4801 group to send. Of course, the SPOE engine must refer to an existing SPOE
4802 filter. If not engine name is provided on the SPOE filter line, the SPOE
4803 agent name must be used.
4804
4805 Arguments:
4806 <engine-name> The SPOE engine name.
4807
4808 <group-name> The SPOE group name as specified in the engine
4809 configuration.
4810
4811http-request silent-drop [ { if | unless } <condition> ]
4812
4813 This stops the evaluation of the rules and makes the client-facing connection
4814 suddenly disappear using a system-dependent way that tries to prevent the
4815 client from being notified. The effect it then that the client still sees an
4816 established connection while there's none on HAProxy. The purpose is to
4817 achieve a comparable effect to "tarpit" except that it doesn't use any local
4818 resource at all on the machine running HAProxy. It can resist much higher
4819 loads than "tarpit", and slow down stronger attackers. It is important to
4820 understand the impact of using this mechanism. All stateful equipment placed
4821 between the client and HAProxy (firewalls, proxies, load balancers) will also
4822 keep the established connection for a long time and may suffer from this
4823 action.
4824 On modern Linux systems running with enough privileges, the TCP_REPAIR socket
4825 option is used to block the emission of a TCP reset. On other systems, the
4826 socket's TTL is reduced to 1 so that the TCP reset doesn't pass the first
4827 router, though it's still delivered to local networks. Do not use it unless
4828 you fully understand how it works.
4829
4830http-request tarpit [deny_status <status>] [ { if | unless } <condition> ]
4831
4832 This stops the evaluation of the rules and immediately blocks the request
4833 without responding for a delay specified by "timeout tarpit" or
4834 "timeout connect" if the former is not set. After that delay, if the client
4835 is still connected, an HTTP error 500 (or optionally the status code
4836 specified as an argument to "deny_status") is returned so that the client
4837 does not suspect it has been tarpitted. Logs will report the flags "PT".
4838 The goal of the tarpit rule is to slow down robots during an attack when
4839 they're limited on the number of concurrent requests. It can be very
4840 efficient against very dumb robots, and will significantly reduce the load
4841 on firewalls compared to a "deny" rule. But when facing "correctly"
4842 developed robots, it can make things worse by forcing haproxy and the front
4843 firewall to support insane number of concurrent connections.
4844 See also the "silent-drop" action.
4845
4846http-request track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
4847http-request track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
4848http-request track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
4849
4850 This enables tracking of sticky counters from current request. These rules do
4851 not stop evaluation and do not change default action. The number of counters
4852 that may be simultaneously tracked by the same connection is set in
4853 MAX_SESS_STKCTR at build time (reported in haproxy -vv) which defaults to 3,
4854 so the track-sc number is between 0 and (MAX_SESS_STCKTR-1). The first
4855 "track-sc0" rule executed enables tracking of the counters of the specified
4856 table as the first set. The first "track-sc1" rule executed enables tracking
4857 of the counters of the specified table as the second set. The first
4858 "track-sc2" rule executed enables tracking of the counters of the specified
4859 table as the third set. It is a recommended practice to use the first set of
4860 counters for the per-frontend counters and the second set for the per-backend
4861 ones. But this is just a guideline, all may be used everywhere.
4862
4863 Arguments :
4864 <key> is mandatory, and is a sample expression rule as described in
4865 section 7.3. It describes what elements of the incoming request or
4866 connection will be analyzed, extracted, combined, and used to
4867 select which table entry to update the counters.
4868
4869 <table> is an optional table to be used instead of the default one, which
4870 is the stick-table declared in the current proxy. All the counters
4871 for the matches and updates for the key will then be performed in
4872 that table until the session ends.
4873
4874 Once a "track-sc*" rule is executed, the key is looked up in the table and if
4875 it is not found, an entry is allocated for it. Then a pointer to that entry
4876 is kept during all the session's life, and this entry's counters are updated
4877 as often as possible, every time the session's counters are updated, and also
4878 systematically when the session ends. Counters are only updated for events
4879 that happen after the tracking has been started. As an exception, connection
4880 counters and request counters are systematically updated so that they reflect
4881 useful information.
4882
4883 If the entry tracks concurrent connection counters, one connection is counted
4884 for as long as the entry is tracked, and the entry will not expire during
4885 that time. Tracking counters also provides a performance advantage over just
4886 checking the keys, because only one table lookup is performed for all ACL
4887 checks that make use of it.
4888
4889http-request unset-var(<var-name>) [ { if | unless } <condition> ]
4890
4891 This is used to unset a variable. See above for details about <var-name>.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004892
4893 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004894 http-request unset-var(req.my_var)
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004895
Christopher Faulet579d83b2019-11-22 15:34:17 +01004896http-request use-service <service-name> [ { if | unless } <condition> ]
4897
4898 This directive executes the configured HTTP service to reply to the request
4899 and stops the evaluation of the rules. An HTTP service may choose to reply by
4900 sending any valid HTTP response or it may immediately close the connection
4901 without sending any response. Outside natives services, for instance the
4902 Prometheus exporter, it is possible to write your own services in Lua. No
4903 further "http-request" rules are evaluated.
4904
4905 Arguments :
4906 <service-name> is mandatory. It is the service to call
4907
4908 Example:
4909 http-request use-service prometheus-exporter if { path /metrics }
4910
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004911http-request wait-for-handshake [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004912
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004913 This will delay the processing of the request until the SSL handshake
4914 happened. This is mostly useful to delay processing early data until we're
4915 sure they are valid.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004916
Willy Tarreauef781042010-01-27 11:53:01 +01004917
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004918http-response <action> <options...> [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004919 Access control for Layer 7 responses
4920
4921 May be used in sections: defaults | frontend | listen | backend
4922 no | yes | yes | yes
4923
4924 The http-response statement defines a set of rules which apply to layer 7
4925 processing. The rules are evaluated in their declaration order when they are
4926 met in a frontend, listen or backend section. Any rule may optionally be
4927 followed by an ACL-based condition, in which case it will only be evaluated
4928 if the condition is true. Since these rules apply on responses, the backend
4929 rules are applied first, followed by the frontend's rules.
4930
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004931 The first keyword is the rule's action. The supported actions are described
4932 below.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004933
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004934 There is no limit to the number of http-response statements per instance.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004935
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004936 Example:
4937 acl key_acl res.hdr(X-Acl-Key) -m found
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02004938
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004939 acl myhost hdr(Host) -f myhost.lst
Sasha Pachev218f0642014-06-16 12:05:59 -06004940
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004941 http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
4942 http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
Sasha Pachev218f0642014-06-16 12:05:59 -06004943
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004944 Example:
4945 acl value res.hdr(X-Value) -m found
Sasha Pachev218f0642014-06-16 12:05:59 -06004946
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004947 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
Sasha Pachev218f0642014-06-16 12:05:59 -06004948
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004949 http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value
4950 http-response del-map(map.lst) %[src] if ! value
Sasha Pachev218f0642014-06-16 12:05:59 -06004951
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004952 See also : "http-request", section 3.4 about userlists and section 7 about
4953 ACL usage.
Sasha Pachev218f0642014-06-16 12:05:59 -06004954
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004955http-response add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004956
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004957 This is used to add a new entry into an ACL. The ACL must be loaded from a
4958 file (even a dummy empty file). The file name of the ACL to be updated is
4959 passed between parentheses. It takes one argument: <key fmt>, which follows
4960 log-format rules, to collect content of the new entry. It performs a lookup
4961 in the ACL before insertion, to avoid duplicated (or more) values.
4962 This lookup is done by a linear search and can be expensive with large lists!
4963 It is the equivalent of the "add acl" command from the stats socket, but can
4964 be triggered by an HTTP response.
Sasha Pachev218f0642014-06-16 12:05:59 -06004965
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004966http-response add-header <name> <fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004967
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004968 This appends an HTTP header field whose name is specified in <name> and whose
4969 value is defined by <fmt> which follows the log-format rules (see Custom Log
4970 Format in section 8.2.4). This may be used to send a cookie to a client for
4971 example, or to pass some internal information.
4972 This rule is not final, so it is possible to add other similar rules.
4973 Note that header addition is performed immediately, so one rule might reuse
4974 the resulting header from a previous rule.
Sasha Pachev218f0642014-06-16 12:05:59 -06004975
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004976http-response allow [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004977
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004978 This stops the evaluation of the rules and lets the response pass the check.
4979 No further "http-response" rules are evaluated for the current section.
Sasha Pachev218f0642014-06-16 12:05:59 -06004980
Jarno Huuskonen251a6b72019-01-04 14:05:02 +02004981http-response cache-store <name> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004982
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02004983 See section 6.2 about cache setup.
Sasha Pachev218f0642014-06-16 12:05:59 -06004984
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004985http-response capture <sample> id <id> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004986
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004987 This captures sample expression <sample> from the response buffer, and
4988 converts it to a string. The resulting string is stored into the next request
4989 "capture" slot, so it will possibly appear next to some captured HTTP
4990 headers. It will then automatically appear in the logs, and it will be
4991 possible to extract it using sample fetch rules to feed it into headers or
4992 anything. Please check section 7.3 (Fetching samples) and
4993 "capture response header" for more information.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02004994
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02004995 The keyword "id" is the id of the capture slot which is used for storing the
4996 string. The capture slot must be defined in an associated frontend.
4997 This is useful to run captures in backends. The slot id can be declared by a
4998 previous directive "http-response capture" or with the "declare capture"
4999 keyword.
5000 If the slot <id> doesn't exist, then HAProxy fails parsing the configuration
5001 to prevent unexpected behavior at run time.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02005002
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005003http-response del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02005004
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005005 This is used to delete an entry from an ACL. The ACL must be loaded from a
5006 file (even a dummy empty file). The file name of the ACL to be updated is
5007 passed between parentheses. It takes one argument: <key fmt>, which follows
5008 log-format rules, to collect content of the entry to delete.
5009 It is the equivalent of the "del acl" command from the stats socket, but can
5010 be triggered by an HTTP response.
Willy Tarreauf4c43c12013-06-11 17:01:13 +02005011
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005012http-response del-header <name> [ { if | unless } <condition> ]
Willy Tarreau9a355ec2013-06-11 17:45:46 +02005013
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005014 This removes all HTTP header fields whose name is specified in <name>.
Willy Tarreau42cf39e2013-06-11 18:51:32 +02005015
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005016http-response del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreau51347ed2013-06-11 19:34:13 +02005017
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005018 This is used to delete an entry from a MAP. The MAP must be loaded from a
5019 file (even a dummy empty file). The file name of the MAP to be updated is
5020 passed between parentheses. It takes one argument: <key fmt>, which follows
5021 log-format rules, to collect content of the entry to delete.
5022 It takes one argument: "file name" It is the equivalent of the "del map"
5023 command from the stats socket, but can be triggered by an HTTP response.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005024
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005025http-response deny [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005026
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005027 This stops the evaluation of the rules and immediately rejects the response
5028 and emits an HTTP 502 error. No further "http-response" rules are evaluated.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005029
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005030http-response redirect <rule> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005031
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005032 This performs an HTTP redirection based on a redirect rule.
5033 This supports a format string similarly to "http-request redirect" rules,
5034 with the exception that only the "location" type of redirect is possible on
5035 the response. See the "redirect" keyword for the rule's syntax. When a
5036 redirect rule is applied during a response, connections to the server are
5037 closed so that no data can be forwarded from the server to the client.
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02005038
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005039http-response replace-header <name> <regex-match> <replace-fmt>
5040 [ { if | unless } <condition> ]
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02005041
Tim Duesterhus2252beb2019-10-29 00:05:13 +01005042 This works like "http-request replace-header" except that it works on the
5043 server's response instead of the client's request.
William Lallemand86d0df02017-11-24 21:36:45 +01005044
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005045 Example:
5046 http-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2
Willy Tarreau51d861a2015-05-22 17:30:48 +02005047
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005048 # applied to:
5049 Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005050
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005051 # outputs:
5052 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 +02005053
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005054 # assuming the backend IP is 192.168.1.20.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005055
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005056http-response replace-value <name> <regex-match> <replace-fmt>
5057 [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005058
Tim Duesterhus2252beb2019-10-29 00:05:13 +01005059 This works like "http-response replace-value" except that it works on the
5060 server's response instead of the client's request.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005061
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005062 Example:
5063 http-response replace-value Cache-control ^public$ private
Christopher Faulet85d79c92016-11-09 16:54:56 +01005064
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005065 # applied to:
5066 Cache-Control: max-age=3600, public
Christopher Faulet85d79c92016-11-09 16:54:56 +01005067
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005068 # outputs:
5069 Cache-Control: max-age=3600, private
Christopher Faulet85d79c92016-11-09 16:54:56 +01005070
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005071http-response sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
5072http-response sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
Ruoshan Huange4edc6b2016-07-14 15:07:45 +08005073
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005074 This action increments the GPC0 or GPC1 counter according with the sticky
5075 counter designated by <sc-id>. If an error occurs, this action silently fails
5076 and the actions evaluation continues.
Thierry FOURNIER236657b2015-08-19 08:25:14 +02005077
Cédric Dufour0d7712d2019-11-06 18:38:53 +01005078http-response sc-set-gpt0(<sc-id>) { <int> | <expr> }
5079 [ { if | unless } <condition> ]
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02005080
Cédric Dufour0d7712d2019-11-06 18:38:53 +01005081 This action sets the 32-bit unsigned GPT0 tag according to the sticky counter
5082 designated by <sc-id> and the value of <int>/<expr>. The expected result is a
5083 boolean. If an error occurs, this action silently fails and the actions
5084 evaluation continues.
Frédéric Lécaille6778b272018-01-29 15:22:53 +01005085
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005086http-response send-spoe-group [ { if | unless } <condition> ]
Willy Tarreau2d392c22015-08-24 01:43:45 +02005087
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005088 This action is used to trigger sending of a group of SPOE messages. To do so,
5089 the SPOE engine used to send messages must be defined, as well as the SPOE
5090 group to send. Of course, the SPOE engine must refer to an existing SPOE
5091 filter. If not engine name is provided on the SPOE filter line, the SPOE
5092 agent name must be used.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02005093
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005094 Arguments:
5095 <engine-name> The SPOE engine name.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02005096
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005097 <group-name> The SPOE group name as specified in the engine
5098 configuration.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02005099
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005100http-response set-header <name> <fmt> [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02005101
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005102 This does the same as "add-header" except that the header name is first
5103 removed if it existed. This is useful when passing security information to
5104 the server, where the header must not be manipulated by external users.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02005105
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005106http-response set-log-level <level> [ { if | unless } <condition> ]
5107
5108 This is used to change the log level of the current request when a certain
5109 condition is met. Valid levels are the 8 syslog levels (see the "log"
5110 keyword) plus the special level "silent" which disables logging for this
5111 request. This rule is not final so the last matching rule wins. This rule can
5112 be useful to disable health checks coming from another equipment.
5113
5114http-response set-map(<file-name>) <key fmt> <value fmt>
5115
5116 This is used to add a new entry into a MAP. The MAP must be loaded from a
5117 file (even a dummy empty file). The file name of the MAP to be updated is
5118 passed between parentheses. It takes 2 arguments: <key fmt>, which follows
5119 log-format rules, used to collect MAP key, and <value fmt>, which follows
5120 log-format rules, used to collect content for the new entry. It performs a
5121 lookup in the MAP before insertion, to avoid duplicated (or more) values.
5122 This lookup is done by a linear search and can be expensive with large lists!
5123 It is the equivalent of the "set map" command from the stats socket, but can
5124 be triggered by an HTTP response.
5125
5126http-response set-mark <mark> [ { if | unless } <condition> ]
5127
5128 This is used to set the Netfilter MARK on all packets sent to the client to
5129 the value passed in <mark> on platforms which support it. This value is an
5130 unsigned 32 bit value which can be matched by netfilter and by the routing
5131 table. It can be expressed both in decimal or hexadecimal format (prefixed
5132 by "0x"). This can be useful to force certain packets to take a different
5133 route (for example a cheaper network path for bulk downloads). This works on
5134 Linux kernels 2.6.32 and above and requires admin privileges.
5135
5136http-response set-nice <nice> [ { if | unless } <condition> ]
5137
5138 This sets the "nice" factor of the current request being processed.
5139 It only has effect against the other requests being processed at the same
5140 time. The default value is 0, unless altered by the "nice" setting on the
5141 "bind" line. The accepted range is -1024..1024. The higher the value, the
5142 nicest the request will be. Lower values will make the request more important
5143 than other ones. This can be useful to improve the speed of some requests, or
5144 lower the priority of non-important requests. Using this setting without
5145 prior experimentation can cause some major slowdown.
5146
5147http-response set-status <status> [reason <str>]
5148 [ { if | unless } <condition> ]
5149
5150 This replaces the response status code with <status> which must be an integer
5151 between 100 and 999. Optionally, a custom reason text can be provided defined
5152 by <str>, or the default reason for the specified code will be used as a
5153 fallback.
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08005154
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005155 Example:
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005156 # return "431 Request Header Fields Too Large"
5157 http-response set-status 431
5158 # return "503 Slow Down", custom reason
5159 http-response set-status 503 reason "Slow Down".
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005160
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005161http-response set-tos <tos> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005162
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005163 This is used to set the TOS or DSCP field value of packets sent to the client
5164 to the value passed in <tos> on platforms which support this.
5165 This value represents the whole 8 bits of the IP TOS field, and can be
5166 expressed both in decimal or hexadecimal format (prefixed by "0x"). Note that
5167 only the 6 higher bits are used in DSCP or TOS, and the two lower bits are
5168 always 0. This can be used to adjust some routing behavior on border routers
5169 based on some information from the request.
5170
5171 See RFC 2474, 2597, 3260 and 4594 for more information.
5172
5173http-response set-var(<var-name>) <expr> [ { if | unless } <condition> ]
5174
5175 This is used to set the contents of a variable. The variable is declared
5176 inline.
5177
5178 Arguments:
5179 <var-name> The name of the variable starts with an indication about its
5180 scope. The scopes allowed are:
5181 "proc" : the variable is shared with the whole process
5182 "sess" : the variable is shared with the whole session
5183 "txn" : the variable is shared with the transaction
5184 (request and response)
5185 "req" : the variable is shared only during request
5186 processing
5187 "res" : the variable is shared only during response
5188 processing
5189 This prefix is followed by a name. The separator is a '.'.
5190 The name may only contain characters 'a-z', 'A-Z', '0-9', '.'
5191 and '_'.
5192
5193 <expr> Is a standard HAProxy expression formed by a sample-fetch
5194 followed by some converters.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005195
5196 Example:
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005197 http-response set-var(sess.last_redir) res.hdr(location)
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005198
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005199http-response silent-drop [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005200
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005201 This stops the evaluation of the rules and makes the client-facing connection
5202 suddenly disappear using a system-dependent way that tries to prevent the
5203 client from being notified. The effect it then that the client still sees an
5204 established connection while there's none on HAProxy. The purpose is to
5205 achieve a comparable effect to "tarpit" except that it doesn't use any local
5206 resource at all on the machine running HAProxy. It can resist much higher
5207 loads than "tarpit", and slow down stronger attackers. It is important to
5208 understand the impact of using this mechanism. All stateful equipment placed
5209 between the client and HAProxy (firewalls, proxies, load balancers) will also
5210 keep the established connection for a long time and may suffer from this
5211 action.
5212 On modern Linux systems running with enough privileges, the TCP_REPAIR socket
5213 option is used to block the emission of a TCP reset. On other systems, the
5214 socket's TTL is reduced to 1 so that the TCP reset doesn't pass the first
5215 router, though it's still delivered to local networks. Do not use it unless
5216 you fully understand how it works.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005217
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005218http-response track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
5219http-response track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
5220http-response track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02005221
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005222 This enables tracking of sticky counters from current response. Please refer
5223 to "http-request track-sc" for a complete description. The only difference
5224 from "http-request track-sc" is the <key> sample expression can only make use
5225 of samples in response (e.g. res.*, status etc.) and samples below Layer 6
5226 (e.g. SSL-related samples, see section 7.3.4). If the sample is not
5227 supported, haproxy will fail and warn while parsing the config.
5228
5229http-response unset-var(<var-name>) [ { if | unless } <condition> ]
5230
5231 This is used to unset a variable. See "http-response set-var" for details
5232 about <var-name>.
5233
5234 Example:
5235 http-response unset-var(sess.last_redir)
5236
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02005237
Willy Tarreau30631952015-08-06 15:05:24 +02005238http-reuse { never | safe | aggressive | always }
5239 Declare how idle HTTP connections may be shared between requests
5240
5241 May be used in sections: defaults | frontend | listen | backend
5242 yes | no | yes | yes
5243
5244 By default, a connection established between haproxy and the backend server
Olivier Houchard86006a52018-12-14 19:37:49 +01005245 which is considered safe for reuse is moved back to the server's idle
5246 connections pool so that any other request can make use of it. This is the
5247 "safe" strategy below.
Willy Tarreau30631952015-08-06 15:05:24 +02005248
5249 The argument indicates the desired connection reuse strategy :
5250
Olivier Houchard86006a52018-12-14 19:37:49 +01005251 - "never" : idle connections are never shared between sessions. This mode
5252 may be enforced to cancel a different strategy inherited from
5253 a defaults section or for troubleshooting. For example, if an
5254 old bogus application considers that multiple requests over
5255 the same connection come from the same client and it is not
5256 possible to fix the application, it may be desirable to
5257 disable connection sharing in a single backend. An example of
5258 such an application could be an old haproxy using cookie
5259 insertion in tunnel mode and not checking any request past the
5260 first one.
Willy Tarreau30631952015-08-06 15:05:24 +02005261
Olivier Houchard86006a52018-12-14 19:37:49 +01005262 - "safe" : this is the default and the recommended strategy. The first
5263 request of a session is always sent over its own connection,
5264 and only subsequent requests may be dispatched over other
5265 existing connections. This ensures that in case the server
5266 closes the connection when the request is being sent, the
5267 browser can decide to silently retry it. Since it is exactly
5268 equivalent to regular keep-alive, there should be no side
5269 effects.
Willy Tarreau30631952015-08-06 15:05:24 +02005270
5271 - "aggressive" : this mode may be useful in webservices environments where
5272 all servers are not necessarily known and where it would be
5273 appreciable to deliver most first requests over existing
5274 connections. In this case, first requests are only delivered
5275 over existing connections that have been reused at least once,
5276 proving that the server correctly supports connection reuse.
5277 It should only be used when it's sure that the client can
5278 retry a failed request once in a while and where the benefit
Michael Prokop4438c602019-05-24 10:25:45 +02005279 of aggressive connection reuse significantly outweighs the
Willy Tarreau30631952015-08-06 15:05:24 +02005280 downsides of rare connection failures.
5281
5282 - "always" : this mode is only recommended when the path to the server is
5283 known for never breaking existing connections quickly after
5284 releasing them. It allows the first request of a session to be
5285 sent to an existing connection. This can provide a significant
5286 performance increase over the "safe" strategy when the backend
5287 is a cache farm, since such components tend to show a
Davor Ocelice9ed2812017-12-25 17:49:28 +01005288 consistent behavior and will benefit from the connection
Willy Tarreau30631952015-08-06 15:05:24 +02005289 sharing. It is recommended that the "http-keep-alive" timeout
5290 remains low in this mode so that no dead connections remain
5291 usable. In most cases, this will lead to the same performance
5292 gains as "aggressive" but with more risks. It should only be
5293 used when it improves the situation over "aggressive".
5294
5295 When http connection sharing is enabled, a great care is taken to respect the
Davor Ocelice9ed2812017-12-25 17:49:28 +01005296 connection properties and compatibility. Specifically :
5297 - connections made with "usesrc" followed by a client-dependent value
5298 ("client", "clientip", "hdr_ip") are marked private and never shared;
Willy Tarreau30631952015-08-06 15:05:24 +02005299
5300 - connections sent to a server with a TLS SNI extension are marked private
Davor Ocelice9ed2812017-12-25 17:49:28 +01005301 and are never shared;
Willy Tarreau30631952015-08-06 15:05:24 +02005302
Lukas Tribusfd9b68c2018-10-27 20:06:59 +02005303 - connections with certain bogus authentication schemes (relying on the
5304 connection) like NTLM are detected, marked private and are never shared;
Willy Tarreau30631952015-08-06 15:05:24 +02005305
Lukas Tribuse8adfeb2019-11-06 11:50:25 +01005306 A connection pool is involved and configurable with "pool-max-conn".
Willy Tarreau30631952015-08-06 15:05:24 +02005307
5308 Note: connection reuse improves the accuracy of the "server maxconn" setting,
5309 because almost no new connection will be established while idle connections
5310 remain available. This is particularly true with the "always" strategy.
5311
5312 See also : "option http-keep-alive", "server maxconn"
5313
5314
Mark Lamourinec2247f02012-01-04 13:02:01 -05005315http-send-name-header [<header>]
5316 Add the server name to a request. Use the header string given by <header>
Mark Lamourinec2247f02012-01-04 13:02:01 -05005317 May be used in sections: defaults | frontend | listen | backend
5318 yes | no | yes | yes
Mark Lamourinec2247f02012-01-04 13:02:01 -05005319 Arguments :
Mark Lamourinec2247f02012-01-04 13:02:01 -05005320 <header> The header string to use to send the server name
5321
Willy Tarreau81bef7e2019-10-07 14:58:02 +02005322 The "http-send-name-header" statement causes the header field named <header>
5323 to be set to the name of the target server at the moment the request is about
5324 to be sent on the wire. Any existing occurrences of this header are removed.
5325 Upon retries and redispatches, the header field is updated to always reflect
5326 the server being attempted to connect to. Given that this header is modified
5327 very late in the connection setup, it may have unexpected effects on already
5328 modified headers. For example using it with transport-level header such as
5329 connection, content-length, transfer-encoding and so on will likely result in
5330 invalid requests being sent to the server. Additionally it has been reported
5331 that this directive is currently being used as a way to overwrite the Host
5332 header field in outgoing requests; while this trick has been known to work
5333 as a side effect of the feature for some time, it is not officially supported
5334 and might possibly not work anymore in a future version depending on the
5335 technical difficulties this feature induces. A long-term solution instead
5336 consists in fixing the application which required this trick so that it binds
5337 to the correct host name.
Mark Lamourinec2247f02012-01-04 13:02:01 -05005338
5339 See also : "server"
5340
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01005341id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02005342 Set a persistent ID to a proxy.
5343 May be used in sections : defaults | frontend | listen | backend
5344 no | yes | yes | yes
5345 Arguments : none
5346
5347 Set a persistent ID for the proxy. This ID must be unique and positive.
5348 An unused ID will automatically be assigned if unset. The first assigned
5349 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01005350
5351
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005352ignore-persist { if | unless } <condition>
5353 Declare a condition to ignore persistence
5354 May be used in sections: defaults | frontend | listen | backend
Cyril Bonté4288c5a2018-03-12 22:02:59 +01005355 no | no | yes | yes
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005356
5357 By default, when cookie persistence is enabled, every requests containing
5358 the cookie are unconditionally persistent (assuming the target server is up
5359 and running).
5360
5361 The "ignore-persist" statement allows one to declare various ACL-based
5362 conditions which, when met, will cause a request to ignore persistence.
5363 This is sometimes useful to load balance requests for static files, which
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03005364 often don't require persistence. This can also be used to fully disable
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005365 persistence for a specific User-Agent (for example, some web crawler bots).
5366
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005367 The persistence is ignored when an "if" condition is met, or unless an
5368 "unless" condition is met.
5369
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03005370 Example:
5371 acl url_static path_beg /static /images /img /css
5372 acl url_static path_end .gif .png .jpg .css .js
5373 ignore-persist if url_static
5374
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005375 See also : "force-persist", "cookie", and section 7 about ACL usage.
5376
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005377load-server-state-from-file { global | local | none }
5378 Allow seamless reload of HAProxy
5379 May be used in sections: defaults | frontend | listen | backend
5380 yes | no | yes | yes
5381
5382 This directive points HAProxy to a file where server state from previous
5383 running process has been saved. That way, when starting up, before handling
5384 traffic, the new process can apply old states to servers exactly has if no
Davor Ocelice9ed2812017-12-25 17:49:28 +01005385 reload occurred. The purpose of the "load-server-state-from-file" directive is
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005386 to tell haproxy which file to use. For now, only 2 arguments to either prevent
5387 loading state or load states from a file containing all backends and servers.
5388 The state file can be generated by running the command "show servers state"
5389 over the stats socket and redirect output.
5390
Davor Ocelice9ed2812017-12-25 17:49:28 +01005391 The format of the file is versioned and is very specific. To understand it,
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005392 please read the documentation of the "show servers state" command (chapter
Willy Tarreau1af20c72017-06-23 16:01:14 +02005393 9.3 of Management Guide).
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005394
5395 Arguments:
5396 global load the content of the file pointed by the global directive
5397 named "server-state-file".
5398
5399 local load the content of the file pointed by the directive
5400 "server-state-file-name" if set. If not set, then the backend
5401 name is used as a file name.
5402
5403 none don't load any stat for this backend
5404
5405 Notes:
Willy Tarreaue5a60682016-11-09 14:54:53 +01005406 - server's IP address is preserved across reloads by default, but the
5407 order can be changed thanks to the server's "init-addr" setting. This
5408 means that an IP address change performed on the CLI at run time will
Davor Ocelice9ed2812017-12-25 17:49:28 +01005409 be preserved, and that any change to the local resolver (e.g. /etc/hosts)
Willy Tarreaue5a60682016-11-09 14:54:53 +01005410 will possibly not have any effect if the state file is in use.
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005411
5412 - server's weight is applied from previous running process unless it has
5413 has changed between previous and new configuration files.
5414
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005415 Example: Minimal configuration
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005416
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005417 global
5418 stats socket /tmp/socket
5419 server-state-file /tmp/server_state
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005420
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005421 defaults
5422 load-server-state-from-file global
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005423
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005424 backend bk
5425 server s1 127.0.0.1:22 check weight 11
5426 server s2 127.0.0.1:22 check weight 12
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005427
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005428
5429 Then one can run :
5430
5431 socat /tmp/socket - <<< "show servers state" > /tmp/server_state
5432
5433 Content of the file /tmp/server_state would be like this:
5434
5435 1
5436 # <field names skipped for the doc example>
5437 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
5438 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
5439
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005440 Example: Minimal configuration
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005441
5442 global
5443 stats socket /tmp/socket
5444 server-state-base /etc/haproxy/states
5445
5446 defaults
5447 load-server-state-from-file local
5448
5449 backend bk
5450 server s1 127.0.0.1:22 check weight 11
5451 server s2 127.0.0.1:22 check weight 12
5452
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005453
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005454 Then one can run :
5455
5456 socat /tmp/socket - <<< "show servers state bk" > /etc/haproxy/states/bk
5457
5458 Content of the file /etc/haproxy/states/bk would be like this:
5459
5460 1
5461 # <field names skipped for the doc example>
5462 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
5463 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
5464
5465 See also: "server-state-file", "server-state-file-name", and
5466 "show servers state"
5467
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005468
Willy Tarreau2769aa02007-12-27 18:26:09 +01005469log global
Frédéric Lécailled690dfa2019-04-25 10:52:17 +02005470log <address> [len <length>] [format <format>] [sample <ranges>:<smp_size>]
5471 <facility> [<level> [<minlevel>]]
William Lallemand0f99e342011-10-12 17:50:54 +02005472no log
Willy Tarreau2769aa02007-12-27 18:26:09 +01005473 Enable per-instance logging of events and traffic.
5474 May be used in sections : defaults | frontend | listen | backend
5475 yes | yes | yes | yes
William Lallemand0f99e342011-10-12 17:50:54 +02005476
5477 Prefix :
5478 no should be used when the logger list must be flushed. For example,
5479 if you don't want to inherit from the default logger list. This
5480 prefix does not allow arguments.
5481
Willy Tarreau2769aa02007-12-27 18:26:09 +01005482 Arguments :
5483 global should be used when the instance's logging parameters are the
5484 same as the global ones. This is the most common usage. "global"
5485 replaces <address>, <facility> and <level> with those of the log
5486 entries found in the "global" section. Only one "log global"
5487 statement may be used per instance, and this form takes no other
5488 parameter.
5489
5490 <address> indicates where to send the logs. It takes the same format as
5491 for the "global" section's logs, and can be one of :
5492
5493 - An IPv4 address optionally followed by a colon (':') and a UDP
5494 port. If no port is specified, 514 is used by default (the
5495 standard syslog port).
5496
David du Colombier24bb5f52011-03-17 10:40:23 +01005497 - An IPv6 address followed by a colon (':') and optionally a UDP
5498 port. If no port is specified, 514 is used by default (the
5499 standard syslog port).
5500
Willy Tarreau2769aa02007-12-27 18:26:09 +01005501 - A filesystem path to a UNIX domain socket, keeping in mind
5502 considerations for chroot (be sure the path is accessible
5503 inside the chroot) and uid/gid (be sure the path is
Davor Ocelice9ed2812017-12-25 17:49:28 +01005504 appropriately writable).
Willy Tarreau2769aa02007-12-27 18:26:09 +01005505
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01005506 - A file descriptor number in the form "fd@<number>", which may
5507 point to a pipe, terminal, or socket. In this case unbuffered
5508 logs are used and one writev() call per log is performed. This
5509 is a bit expensive but acceptable for most workloads. Messages
5510 sent this way will not be truncated but may be dropped, in
5511 which case the DroppedLogs counter will be incremented. The
5512 writev() call is atomic even on pipes for messages up to
5513 PIPE_BUF size, which POSIX recommends to be at least 512 and
5514 which is 4096 bytes on most modern operating systems. Any
5515 larger message may be interleaved with messages from other
5516 processes. Exceptionally for debugging purposes the file
5517 descriptor may also be directed to a file, but doing so will
5518 significantly slow haproxy down as non-blocking calls will be
5519 ignored. Also there will be no way to purge nor rotate this
5520 file without restarting the process. Note that the configured
5521 syslog format is preserved, so the output is suitable for use
Willy Tarreauc1b06452018-11-12 11:57:56 +01005522 with a TCP syslog server. See also the "short" and "raw"
5523 formats below.
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01005524
5525 - "stdout" / "stderr", which are respectively aliases for "fd@1"
5526 and "fd@2", see above.
5527
Willy Tarreauc046d162019-08-30 15:24:59 +02005528 - A ring buffer in the form "ring@<name>", which will correspond
5529 to an in-memory ring buffer accessible over the CLI using the
5530 "show events" command, which will also list existing rings and
5531 their sizes. Such buffers are lost on reload or restart but
5532 when used as a complement this can help troubleshooting by
5533 having the logs instantly available.
5534
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01005535 You may want to reference some environment variables in the
5536 address parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01005537
Willy Tarreau18324f52014-06-27 18:10:07 +02005538 <length> is an optional maximum line length. Log lines larger than this
5539 value will be truncated before being sent. The reason is that
5540 syslog servers act differently on log line length. All servers
5541 support the default value of 1024, but some servers simply drop
5542 larger lines while others do log them. If a server supports long
5543 lines, it may make sense to set this value here in order to avoid
5544 truncating long lines. Similarly, if a server drops long lines,
5545 it is preferable to truncate them before sending them. Accepted
5546 values are 80 to 65535 inclusive. The default value of 1024 is
5547 generally fine for all standard usages. Some specific cases of
Davor Ocelice9ed2812017-12-25 17:49:28 +01005548 long captures or JSON-formatted logs may require larger values.
Willy Tarreau18324f52014-06-27 18:10:07 +02005549
Frédéric Lécailled690dfa2019-04-25 10:52:17 +02005550 <ranges> A list of comma-separated ranges to identify the logs to sample.
5551 This is used to balance the load of the logs to send to the log
5552 server. The limits of the ranges cannot be null. They are numbered
5553 from 1. The size or period (in number of logs) of the sample must
5554 be set with <sample_size> parameter.
5555
5556 <sample_size>
5557 The size of the sample in number of logs to consider when balancing
5558 their logging loads. It is used to balance the load of the logs to
5559 send to the syslog server. This size must be greater or equal to the
5560 maximum of the high limits of the ranges.
5561 (see also <ranges> parameter).
5562
Willy Tarreauadb345d2018-11-12 07:56:13 +01005563 <format> is the log format used when generating syslog messages. It may be
5564 one of the following :
5565
5566 rfc3164 The RFC3164 syslog message format. This is the default.
5567 (https://tools.ietf.org/html/rfc3164)
5568
5569 rfc5424 The RFC5424 syslog message format.
5570 (https://tools.ietf.org/html/rfc5424)
5571
Willy Tarreaue8746a02018-11-12 08:45:00 +01005572 short A message containing only a level between angle brackets such as
5573 '<3>', followed by the text. The PID, date, time, process name
5574 and system name are omitted. This is designed to be used with a
5575 local log server. This format is compatible with what the
5576 systemd logger consumes.
5577
Willy Tarreauc1b06452018-11-12 11:57:56 +01005578 raw A message containing only the text. The level, PID, date, time,
5579 process name and system name are omitted. This is designed to
5580 be used in containers or during development, where the severity
5581 only depends on the file descriptor used (stdout/stderr).
5582
Willy Tarreau2769aa02007-12-27 18:26:09 +01005583 <facility> must be one of the 24 standard syslog facilities :
5584
Willy Tarreaue8746a02018-11-12 08:45:00 +01005585 kern user mail daemon auth syslog lpr news
5586 uucp cron auth2 ftp ntp audit alert cron2
5587 local0 local1 local2 local3 local4 local5 local6 local7
5588
Willy Tarreauc1b06452018-11-12 11:57:56 +01005589 Note that the facility is ignored for the "short" and "raw"
5590 formats, but still required as a positional field. It is
5591 recommended to use "daemon" in this case to make it clear that
5592 it's only supposed to be used locally.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005593
5594 <level> is optional and can be specified to filter outgoing messages. By
5595 default, all messages are sent. If a level is specified, only
5596 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02005597 will be sent. An optional minimum level can be specified. If it
5598 is set, logs emitted with a more severe level than this one will
5599 be capped to this level. This is used to avoid sending "emerg"
5600 messages on all terminals on some default syslog configurations.
5601 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01005602
5603 emerg alert crit err warning notice info debug
5604
William Lallemand0f99e342011-10-12 17:50:54 +02005605 It is important to keep in mind that it is the frontend which decides what to
5606 log from a connection, and that in case of content switching, the log entries
5607 from the backend will be ignored. Connections are logged at level "info".
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005608
5609 However, backend log declaration define how and where servers status changes
5610 will be logged. Level "notice" will be used to indicate a server going up,
5611 "warning" will be used for termination signals and definitive service
5612 termination, and "alert" will be used for when a server goes down.
5613
5614 Note : According to RFC3164, messages are truncated to 1024 bytes before
5615 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005616
5617 Example :
5618 log global
Willy Tarreauc1b06452018-11-12 11:57:56 +01005619 log stdout format short daemon # send log to systemd
5620 log stdout format raw daemon # send everything to stdout
5621 log stderr format raw daemon notice # send important events to stderr
Willy Tarreauf7edefa2009-05-10 17:20:05 +02005622 log 127.0.0.1:514 local0 notice # only send important events
5623 log 127.0.0.1:514 local0 notice notice # same but limit output level
William Lallemandb2f07452015-05-12 14:27:13 +02005624 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
Willy Tarreaudad36a32013-03-11 01:20:04 +01005625
Willy Tarreau2769aa02007-12-27 18:26:09 +01005626
William Lallemand48940402012-01-30 16:47:22 +01005627log-format <string>
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01005628 Specifies the log format string to use for traffic logs
5629 May be used in sections: defaults | frontend | listen | backend
5630 yes | yes | yes | no
William Lallemand48940402012-01-30 16:47:22 +01005631
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01005632 This directive specifies the log format string that will be used for all logs
5633 resulting from traffic passing through the frontend using this line. If the
5634 directive is used in a defaults section, all subsequent frontends will use
5635 the same log format. Please see section 8.2.4 which covers the log format
5636 string in depth.
William Lallemand48940402012-01-30 16:47:22 +01005637
Guillaume de Lafond29f45602017-03-31 19:52:15 +02005638 "log-format" directive overrides previous "option tcplog", "log-format" and
5639 "option httplog" directives.
5640
Dragan Dosen7ad31542015-09-28 17:16:47 +02005641log-format-sd <string>
5642 Specifies the RFC5424 structured-data log format string
5643 May be used in sections: defaults | frontend | listen | backend
5644 yes | yes | yes | no
5645
5646 This directive specifies the RFC5424 structured-data log format string that
5647 will be used for all logs resulting from traffic passing through the frontend
5648 using this line. If the directive is used in a defaults section, all
5649 subsequent frontends will use the same log format. Please see section 8.2.4
5650 which covers the log format string in depth.
5651
5652 See https://tools.ietf.org/html/rfc5424#section-6.3 for more information
5653 about the RFC5424 structured-data part.
5654
5655 Note : This log format string will be used only for loggers that have set
5656 log format to "rfc5424".
5657
5658 Example :
5659 log-format-sd [exampleSDID@1234\ bytes=\"%B\"\ status=\"%ST\"]
5660
5661
Willy Tarreau094af4e2015-01-07 15:03:42 +01005662log-tag <string>
5663 Specifies the log tag to use for all outgoing logs
5664 May be used in sections: defaults | frontend | listen | backend
5665 yes | yes | yes | yes
5666
5667 Sets the tag field in the syslog header to this string. It defaults to the
5668 log-tag set in the global section, otherwise the program name as launched
5669 from the command line, which usually is "haproxy". Sometimes it can be useful
5670 to differentiate between multiple processes running on the same host, or to
5671 differentiate customer instances running in the same process. In the backend,
5672 logs about servers up/down will use this tag. As a hint, it can be convenient
5673 to set a log-tag related to a hosted customer in a defaults section then put
5674 all the frontends and backends for that customer, then start another customer
5675 in a new defaults section. See also the global "log-tag" directive.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005676
Willy Tarreauc35362a2014-04-25 13:58:37 +02005677max-keep-alive-queue <value>
5678 Set the maximum server queue size for maintaining keep-alive connections
5679 May be used in sections: defaults | frontend | listen | backend
5680 yes | no | yes | yes
5681
5682 HTTP keep-alive tries to reuse the same server connection whenever possible,
5683 but sometimes it can be counter-productive, for example if a server has a lot
5684 of connections while other ones are idle. This is especially true for static
5685 servers.
5686
5687 The purpose of this setting is to set a threshold on the number of queued
5688 connections at which haproxy stops trying to reuse the same server and prefers
5689 to find another one. The default value, -1, means there is no limit. A value
5690 of zero means that keep-alive requests will never be queued. For very close
5691 servers which can be reached with a low latency and which are not sensible to
Davor Ocelice9ed2812017-12-25 17:49:28 +01005692 breaking keep-alive, a low value is recommended (e.g. local static server can
Willy Tarreauc35362a2014-04-25 13:58:37 +02005693 use a value of 10 or less). For remote servers suffering from a high latency,
5694 higher values might be needed to cover for the latency and/or the cost of
5695 picking a different server.
5696
5697 Note that this has no impact on responses which are maintained to the same
5698 server consecutively to a 401 response. They will still go to the same server
5699 even if they have to be queued.
5700
5701 See also : "option http-server-close", "option prefer-last-server", server
5702 "maxconn" and cookie persistence.
5703
Olivier Houcharda4d4fdf2018-12-14 19:27:06 +01005704max-session-srv-conns <nb>
5705 Set the maximum number of outgoing connections we can keep idling for a given
5706 client session. The default is 5 (it precisely equals MAX_SRV_LIST which is
5707 defined at build time).
Willy Tarreauc35362a2014-04-25 13:58:37 +02005708
Willy Tarreau2769aa02007-12-27 18:26:09 +01005709maxconn <conns>
5710 Fix the maximum number of concurrent connections on a frontend
5711 May be used in sections : defaults | frontend | listen | backend
5712 yes | yes | yes | no
5713 Arguments :
5714 <conns> is the maximum number of concurrent connections the frontend will
5715 accept to serve. Excess connections will be queued by the system
5716 in the socket's listen queue and will be served once a connection
5717 closes.
5718
5719 If the system supports it, it can be useful on big sites to raise this limit
5720 very high so that haproxy manages connection queues, instead of leaving the
5721 clients with unanswered connection attempts. This value should not exceed the
5722 global maxconn. Also, keep in mind that a connection contains two buffers
Baptiste Assmann79fb45d2016-03-06 23:34:31 +01005723 of tune.bufsize (16kB by default) each, as well as some other data resulting
5724 in about 33 kB of RAM being consumed per established connection. That means
5725 that a medium system equipped with 1GB of RAM can withstand around
5726 20000-25000 concurrent connections if properly tuned.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005727
5728 Also, when <conns> is set to large values, it is possible that the servers
5729 are not sized to accept such loads, and for this reason it is generally wise
5730 to assign them some reasonable connection limits.
5731
Willy Tarreauc8d5b952019-02-27 17:25:52 +01005732 When this value is set to zero, which is the default, the global "maxconn"
5733 value is used.
Vincent Bernat6341be52012-06-27 17:18:30 +02005734
Willy Tarreau2769aa02007-12-27 18:26:09 +01005735 See also : "server", global section's "maxconn", "fullconn"
5736
5737
5738mode { tcp|http|health }
5739 Set the running mode or protocol of the instance
5740 May be used in sections : defaults | frontend | listen | backend
5741 yes | yes | yes | yes
5742 Arguments :
5743 tcp The instance will work in pure TCP mode. A full-duplex connection
5744 will be established between clients and servers, and no layer 7
5745 examination will be performed. This is the default mode. It
5746 should be used for SSL, SSH, SMTP, ...
5747
5748 http The instance will work in HTTP mode. The client request will be
5749 analyzed in depth before connecting to any server. Any request
5750 which is not RFC-compliant will be rejected. Layer 7 filtering,
5751 processing and switching will be possible. This is the mode which
5752 brings HAProxy most of its value.
5753
5754 health The instance will work in "health" mode. It will just reply "OK"
Willy Tarreau82569f92012-09-27 23:48:56 +02005755 to incoming connections and close the connection. Alternatively,
5756 If the "httpchk" option is set, "HTTP/1.0 200 OK" will be sent
5757 instead. Nothing will be logged in either case. This mode is used
5758 to reply to external components health checks. This mode is
5759 deprecated and should not be used anymore as it is possible to do
5760 the same and even better by combining TCP or HTTP modes with the
5761 "monitor" keyword.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005762
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005763 When doing content switching, it is mandatory that the frontend and the
5764 backend are in the same mode (generally HTTP), otherwise the configuration
5765 will be refused.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005766
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005767 Example :
Willy Tarreau2769aa02007-12-27 18:26:09 +01005768 defaults http_instances
5769 mode http
5770
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005771 See also : "monitor", "monitor-net"
Willy Tarreau2769aa02007-12-27 18:26:09 +01005772
Willy Tarreau0ba27502007-12-24 16:55:16 +01005773
Cyril Bontéf0c60612010-02-06 14:44:47 +01005774monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01005775 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01005776 May be used in sections : defaults | frontend | listen | backend
5777 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01005778 Arguments :
5779 if <cond> the monitor request will fail if the condition is satisfied,
5780 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005781 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01005782 are met, for instance a low number of servers both in a
5783 backend and its backup.
5784
5785 unless <cond> the monitor request will succeed only if the condition is
5786 satisfied, and will fail otherwise. Such a condition may be
5787 based on a test on the presence of a minimum number of active
5788 servers in a list of backends.
5789
5790 This statement adds a condition which can force the response to a monitor
5791 request to report a failure. By default, when an external component queries
5792 the URI dedicated to monitoring, a 200 response is returned. When one of the
5793 conditions above is met, haproxy will return 503 instead of 200. This is
5794 very useful to report a site failure to an external component which may base
5795 routing advertisements between multiple sites on the availability reported by
5796 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02005797 criterion. Note that "monitor fail" only works in HTTP mode. Both status
5798 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01005799
5800 Example:
5801 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01005802 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01005803 acl site_dead nbsrv(dynamic) lt 2
5804 acl site_dead nbsrv(static) lt 2
5805 monitor-uri /site_alive
5806 monitor fail if site_dead
5807
Willy Tarreauae94d4d2011-05-11 16:28:49 +02005808 See also : "monitor-net", "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01005809
5810
5811monitor-net <source>
5812 Declare a source network which is limited to monitor requests
5813 May be used in sections : defaults | frontend | listen | backend
5814 yes | yes | yes | no
5815 Arguments :
5816 <source> is the source IPv4 address or network which will only be able to
5817 get monitor responses to any request. It can be either an IPv4
5818 address, a host name, or an address followed by a slash ('/')
5819 followed by a mask.
5820
5821 In TCP mode, any connection coming from a source matching <source> will cause
5822 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005823 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01005824 forwarding the connection to a remote server.
5825
5826 In HTTP mode, a connection coming from a source matching <source> will be
5827 accepted, the following response will be sent without waiting for a request,
5828 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
5829 enough for any front-end HTTP probe to detect that the service is UP and
Willy Tarreau82569f92012-09-27 23:48:56 +02005830 running without forwarding the request to a backend server. Note that this
5831 response is sent in raw format, without any transformation. This is important
5832 as it means that it will not be SSL-encrypted on SSL listeners.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005833
Willy Tarreau82569f92012-09-27 23:48:56 +02005834 Monitor requests are processed very early, just after tcp-request connection
5835 ACLs which are the only ones able to block them. These connections are short
5836 lived and never wait for any data from the client. They cannot be logged, and
5837 it is the intended purpose. They are only used to report HAProxy's health to
5838 an upper component, nothing more. Please note that "monitor fail" rules do
5839 not apply to connections intercepted by "monitor-net".
Willy Tarreau2769aa02007-12-27 18:26:09 +01005840
Willy Tarreau95cd2832010-03-04 23:36:33 +01005841 Last, please note that only one "monitor-net" statement can be specified in
5842 a frontend. If more than one is found, only the last one will be considered.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005843
Willy Tarreau2769aa02007-12-27 18:26:09 +01005844 Example :
5845 # addresses .252 and .253 are just probing us.
5846 frontend www
5847 monitor-net 192.168.0.252/31
5848
5849 See also : "monitor fail", "monitor-uri"
5850
5851
5852monitor-uri <uri>
5853 Intercept a URI used by external components' monitor requests
5854 May be used in sections : defaults | frontend | listen | backend
5855 yes | yes | yes | no
5856 Arguments :
5857 <uri> is the exact URI which we want to intercept to return HAProxy's
5858 health status instead of forwarding the request.
5859
5860 When an HTTP request referencing <uri> will be received on a frontend,
5861 HAProxy will not forward it nor log it, but instead will return either
5862 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
5863 conditions defined with "monitor fail". This is normally enough for any
5864 front-end HTTP probe to detect that the service is UP and running without
5865 forwarding the request to a backend server. Note that the HTTP method, the
5866 version and all headers are ignored, but the request must at least be valid
5867 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
5868
Willy Tarreau721d8e02017-12-01 18:25:08 +01005869 Monitor requests are processed very early, just after the request is parsed
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02005870 and even before any "http-request". The only rulesets applied before are the
5871 tcp-request ones. They cannot be logged either, and it is the intended
5872 purpose. They are only used to report HAProxy's health to an upper component,
5873 nothing more. However, it is possible to add any number of conditions using
5874 "monitor fail" and ACLs so that the result can be adjusted to whatever check
5875 can be imagined (most often the number of available servers in a backend).
Willy Tarreau2769aa02007-12-27 18:26:09 +01005876
5877 Example :
5878 # Use /haproxy_test to report haproxy's status
5879 frontend www
5880 mode http
5881 monitor-uri /haproxy_test
5882
5883 See also : "monitor fail", "monitor-net"
5884
Willy Tarreau0ba27502007-12-24 16:55:16 +01005885
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005886option abortonclose
5887no option abortonclose
5888 Enable or disable early dropping of aborted requests pending in queues.
5889 May be used in sections : defaults | frontend | listen | backend
5890 yes | no | yes | yes
5891 Arguments : none
5892
5893 In presence of very high loads, the servers will take some time to respond.
5894 The per-instance connection queue will inflate, and the response time will
5895 increase respective to the size of the queue times the average per-session
5896 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01005897 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005898 the queue, and slowing down other users, and the servers as well, because the
5899 request will eventually be served, then aborted at the first error
5900 encountered while delivering the response.
5901
5902 As there is no way to distinguish between a full STOP and a simple output
5903 close on the client side, HTTP agents should be conservative and consider
5904 that the client might only have closed its output channel while waiting for
5905 the response. However, this introduces risks of congestion when lots of users
5906 do the same, and is completely useless nowadays because probably no client at
5907 all will close the session while waiting for the response. Some HTTP agents
Davor Ocelice9ed2812017-12-25 17:49:28 +01005908 support this behavior (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005909 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01005910 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005911 of being the single component to break rare but valid traffic is extremely
5912 low, which adds to the temptation to be able to abort a session early while
5913 still not served and not pollute the servers.
5914
Davor Ocelice9ed2812017-12-25 17:49:28 +01005915 In HAProxy, the user can choose the desired behavior using the option
5916 "abortonclose". By default (without the option) the behavior is HTTP
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005917 compliant and aborted requests will be served. But when the option is
5918 specified, a session with an incoming channel closed will be aborted while
5919 it is still possible, either pending in the queue for a connection slot, or
5920 during the connection establishment if the server has not yet acknowledged
5921 the connection request. This considerably reduces the queue size and the load
5922 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01005923 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005924
5925 If this option has been enabled in a "defaults" section, it can be disabled
5926 in a specific instance by prepending the "no" keyword before it.
5927
5928 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
5929
5930
Willy Tarreau4076a152009-04-02 15:18:36 +02005931option accept-invalid-http-request
5932no option accept-invalid-http-request
5933 Enable or disable relaxing of HTTP request parsing
5934 May be used in sections : defaults | frontend | listen | backend
5935 yes | yes | yes | no
5936 Arguments : none
5937
Willy Tarreau91852eb2015-05-01 13:26:00 +02005938 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02005939 means that invalid characters in header names are not permitted and cause an
Davor Ocelice9ed2812017-12-25 17:49:28 +01005940 error to be returned to the client. This is the desired behavior as such
Willy Tarreau4076a152009-04-02 15:18:36 +02005941 forbidden characters are essentially used to build attacks exploiting server
5942 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
5943 server will emit invalid header names for whatever reason (configuration,
5944 implementation) and the issue will not be immediately fixed. In such a case,
5945 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau422246e2012-01-07 23:54:13 +01005946 even if that does not make sense, by specifying this option. Similarly, the
5947 list of characters allowed to appear in a URI is well defined by RFC3986, and
5948 chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
5949 ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
Davor Ocelice9ed2812017-12-25 17:49:28 +01005950 not allowed at all. HAProxy always blocks a number of them (0..32, 127). The
Willy Tarreau91852eb2015-05-01 13:26:00 +02005951 remaining ones are blocked by default unless this option is enabled. This
Willy Tarreau13317662015-05-01 13:47:08 +02005952 option also relaxes the test on the HTTP version, it allows HTTP/0.9 requests
5953 to pass through (no version specified) and multiple digits for both the major
5954 and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02005955
5956 This option should never be enabled by default as it hides application bugs
5957 and open security breaches. It should only be deployed after a problem has
5958 been confirmed.
5959
5960 When this option is enabled, erroneous header names will still be accepted in
5961 requests, but the complete request will be captured in order to permit later
Willy Tarreau422246e2012-01-07 23:54:13 +01005962 analysis using the "show errors" request on the UNIX stats socket. Similarly,
5963 requests containing invalid chars in the URI part will be logged. Doing this
Willy Tarreau4076a152009-04-02 15:18:36 +02005964 also helps confirming that the issue has been solved.
5965
5966 If this option has been enabled in a "defaults" section, it can be disabled
5967 in a specific instance by prepending the "no" keyword before it.
5968
5969 See also : "option accept-invalid-http-response" and "show errors" on the
5970 stats socket.
5971
5972
5973option accept-invalid-http-response
5974no option accept-invalid-http-response
5975 Enable or disable relaxing of HTTP response parsing
5976 May be used in sections : defaults | frontend | listen | backend
5977 yes | no | yes | yes
5978 Arguments : none
5979
Willy Tarreau91852eb2015-05-01 13:26:00 +02005980 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02005981 means that invalid characters in header names are not permitted and cause an
Davor Ocelice9ed2812017-12-25 17:49:28 +01005982 error to be returned to the client. This is the desired behavior as such
Willy Tarreau4076a152009-04-02 15:18:36 +02005983 forbidden characters are essentially used to build attacks exploiting server
5984 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
5985 server will emit invalid header names for whatever reason (configuration,
5986 implementation) and the issue will not be immediately fixed. In such a case,
5987 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau91852eb2015-05-01 13:26:00 +02005988 even if that does not make sense, by specifying this option. This option also
5989 relaxes the test on the HTTP version format, it allows multiple digits for
5990 both the major and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02005991
5992 This option should never be enabled by default as it hides application bugs
5993 and open security breaches. It should only be deployed after a problem has
5994 been confirmed.
5995
5996 When this option is enabled, erroneous header names will still be accepted in
5997 responses, but the complete response will be captured in order to permit
5998 later analysis using the "show errors" request on the UNIX stats socket.
5999 Doing this also helps confirming that the issue has been solved.
6000
6001 If this option has been enabled in a "defaults" section, it can be disabled
6002 in a specific instance by prepending the "no" keyword before it.
6003
6004 See also : "option accept-invalid-http-request" and "show errors" on the
6005 stats socket.
6006
6007
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006008option allbackups
6009no option allbackups
6010 Use either all backup servers at a time or only the first one
6011 May be used in sections : defaults | frontend | listen | backend
6012 yes | no | yes | yes
6013 Arguments : none
6014
6015 By default, the first operational backup server gets all traffic when normal
6016 servers are all down. Sometimes, it may be preferred to use multiple backups
6017 at once, because one will not be enough. When "option allbackups" is enabled,
6018 the load balancing will be performed among all backup servers when all normal
6019 ones are unavailable. The same load balancing algorithm will be used and the
6020 servers' weights will be respected. Thus, there will not be any priority
6021 order between the backup servers anymore.
6022
6023 This option is mostly used with static server farms dedicated to return a
6024 "sorry" page when an application is completely offline.
6025
6026 If this option has been enabled in a "defaults" section, it can be disabled
6027 in a specific instance by prepending the "no" keyword before it.
6028
6029
6030option checkcache
6031no option checkcache
Godbach7056a352013-12-11 20:01:07 +08006032 Analyze all server responses and block responses with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006033 May be used in sections : defaults | frontend | listen | backend
6034 yes | no | yes | yes
6035 Arguments : none
6036
6037 Some high-level frameworks set application cookies everywhere and do not
6038 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006039 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006040 high risk of session crossing or stealing between users traversing the same
6041 caches. In some situations, it is better to block the response than to let
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02006042 some sensitive session information go in the wild.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006043
6044 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006045 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01006046 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006047 response to check if there's a risk of caching a cookie on a client-side
6048 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01006049 to the client are :
Davor Ocelice9ed2812017-12-25 17:49:28 +01006050 - all those without "Set-Cookie" header;
Willy Tarreauc55ddce2017-12-21 11:41:38 +01006051 - all those with a return code other than 200, 203, 204, 206, 300, 301,
6052 404, 405, 410, 414, 501, provided that the server has not set a
Davor Ocelice9ed2812017-12-25 17:49:28 +01006053 "Cache-control: public" header field;
Willy Tarreau24ea0bc2017-12-21 11:32:55 +01006054 - all those that result from a request using a method other than GET, HEAD,
6055 OPTIONS, TRACE, provided that the server has not set a 'Cache-Control:
Davor Ocelice9ed2812017-12-25 17:49:28 +01006056 public' header field;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006057 - those with a 'Pragma: no-cache' header
6058 - those with a 'Cache-control: private' header
6059 - those with a 'Cache-control: no-store' header
6060 - those with a 'Cache-control: max-age=0' header
6061 - those with a 'Cache-control: s-maxage=0' header
6062 - those with a 'Cache-control: no-cache' header
6063 - those with a 'Cache-control: no-cache="set-cookie"' header
6064 - those with a 'Cache-control: no-cache="set-cookie,' header
6065 (allowing other fields after set-cookie)
6066
6067 If a response doesn't respect these requirements, then it will be blocked
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02006068 just as if it was from an "http-response deny" rule, with an "HTTP 502 bad
6069 gateway". The session state shows "PH--" meaning that the proxy blocked the
6070 response during headers processing. Additionally, an alert will be sent in
6071 the logs so that admins are informed that there's something to be fixed.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006072
6073 Due to the high impact on the application, the application should be tested
6074 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006075 good practice to always activate it during tests, even if it is not used in
Davor Ocelice9ed2812017-12-25 17:49:28 +01006076 production, as it will report potentially dangerous application behaviors.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006077
6078 If this option has been enabled in a "defaults" section, it can be disabled
6079 in a specific instance by prepending the "no" keyword before it.
6080
6081
6082option clitcpka
6083no option clitcpka
6084 Enable or disable the sending of TCP keepalive packets on the client side
6085 May be used in sections : defaults | frontend | listen | backend
6086 yes | yes | yes | no
6087 Arguments : none
6088
6089 When there is a firewall or any session-aware component between a client and
6090 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01006091 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006092 components decides to expire a session which has remained idle for too long.
6093
6094 Enabling socket-level TCP keep-alives makes the system regularly send packets
6095 to the other end of the connection, leaving it active. The delay between
6096 keep-alive probes is controlled by the system only and depends both on the
6097 operating system and its tuning parameters.
6098
6099 It is important to understand that keep-alive packets are neither emitted nor
6100 received at the application level. It is only the network stacks which sees
6101 them. For this reason, even if one side of the proxy already uses keep-alives
6102 to maintain its connection alive, those keep-alive packets will not be
6103 forwarded to the other side of the proxy.
6104
6105 Please note that this has nothing to do with HTTP keep-alive.
6106
6107 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
6108 client side of a connection, which should help when session expirations are
6109 noticed between HAProxy and a client.
6110
6111 If this option has been enabled in a "defaults" section, it can be disabled
6112 in a specific instance by prepending the "no" keyword before it.
6113
6114 See also : "option srvtcpka", "option tcpka"
6115
6116
Willy Tarreau0ba27502007-12-24 16:55:16 +01006117option contstats
6118 Enable continuous traffic statistics updates
6119 May be used in sections : defaults | frontend | listen | backend
6120 yes | yes | yes | no
6121 Arguments : none
6122
6123 By default, counters used for statistics calculation are incremented
6124 only when a session finishes. It works quite well when serving small
6125 objects, but with big ones (for example large images or archives) or
6126 with A/V streaming, a graph generated from haproxy counters looks like
Willy Tarreaudef0d222016-11-08 22:03:00 +01006127 a hedgehog. With this option enabled counters get incremented frequently
6128 along the session, typically every 5 seconds, which is often enough to
6129 produce clean graphs. Recounting touches a hotpath directly so it is not
6130 not enabled by default, as it can cause a lot of wakeups for very large
6131 session counts and cause a small performance drop.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006132
6133
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02006134option dontlog-normal
6135no option dontlog-normal
6136 Enable or disable logging of normal, successful connections
6137 May be used in sections : defaults | frontend | listen | backend
6138 yes | yes | yes | no
6139 Arguments : none
6140
6141 There are large sites dealing with several thousand connections per second
6142 and for which logging is a major pain. Some of them are even forced to turn
6143 logs off and cannot debug production issues. Setting this option ensures that
6144 normal connections, those which experience no error, no timeout, no retry nor
6145 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
6146 mode, the response status code is checked and return codes 5xx will still be
6147 logged.
6148
6149 It is strongly discouraged to use this option as most of the time, the key to
6150 complex issues is in the normal logs which will not be logged here. If you
6151 need to separate logs, see the "log-separate-errors" option instead.
6152
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006153 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02006154 logging.
6155
6156
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006157option dontlognull
6158no option dontlognull
6159 Enable or disable logging of null connections
6160 May be used in sections : defaults | frontend | listen | backend
6161 yes | yes | yes | no
6162 Arguments : none
6163
6164 In certain environments, there are components which will regularly connect to
6165 various systems to ensure that they are still alive. It can be the case from
6166 another load balancer as well as from monitoring systems. By default, even a
6167 simple port probe or scan will produce a log. If those connections pollute
6168 the logs too much, it is possible to enable option "dontlognull" to indicate
6169 that a connection on which no data has been transferred will not be logged,
Willy Tarreau0f228a02015-05-01 15:37:53 +02006170 which typically corresponds to those probes. Note that errors will still be
6171 returned to the client and accounted for in the stats. If this is not what is
6172 desired, option http-ignore-probes can be used instead.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006173
6174 It is generally recommended not to use this option in uncontrolled
Davor Ocelice9ed2812017-12-25 17:49:28 +01006175 environments (e.g. internet), otherwise scans and other malicious activities
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006176 would not be logged.
6177
6178 If this option has been enabled in a "defaults" section, it can be disabled
6179 in a specific instance by prepending the "no" keyword before it.
6180
Willy Tarreau0f228a02015-05-01 15:37:53 +02006181 See also : "log", "http-ignore-probes", "monitor-net", "monitor-uri", and
6182 section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006183
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006184
Willy Tarreau87cf5142011-08-19 22:57:24 +02006185option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01006186 Enable insertion of the X-Forwarded-For header to requests sent to servers
6187 May be used in sections : defaults | frontend | listen | backend
6188 yes | yes | yes | yes
6189 Arguments :
6190 <network> is an optional argument used to disable this option for sources
6191 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02006192 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01006193 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006194
6195 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
6196 their client address. This is sometimes annoying when the client's IP address
6197 is expected in server logs. To solve this problem, the well-known HTTP header
6198 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
6199 This header contains a value representing the client's IP address. Since this
6200 header is always appended at the end of the existing header list, the server
6201 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02006202 the server's manual to find how to enable use of this standard header. Note
6203 that only the last occurrence of the header must be used, since it is really
6204 possible that the client has already brought one.
6205
Willy Tarreaud72758d2010-01-12 10:42:19 +01006206 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02006207 the default "X-Forwarded-For". This can be useful where you might already
Davor Ocelice9ed2812017-12-25 17:49:28 +01006208 have a "X-Forwarded-For" header from a different application (e.g. stunnel),
Willy Tarreaud72758d2010-01-12 10:42:19 +01006209 and you need preserve it. Also if your backend server doesn't use the
Davor Ocelice9ed2812017-12-25 17:49:28 +01006210 "X-Forwarded-For" header and requires different one (e.g. Zeus Web Servers
Ross Westaf72a1d2008-08-03 10:51:45 +02006211 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01006212
6213 Sometimes, a same HAProxy instance may be shared between a direct client
6214 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
6215 used to decrypt HTTPS traffic). It is possible to disable the addition of the
6216 header for a known source address or network by adding the "except" keyword
6217 followed by the network address. In this case, any source IP matching the
6218 network will not cause an addition of this header. Most common uses are with
6219 private networks or 127.0.0.1.
6220
Willy Tarreau87cf5142011-08-19 22:57:24 +02006221 Alternatively, the keyword "if-none" states that the header will only be
6222 added if it is not present. This should only be used in perfectly trusted
6223 environment, as this might cause a security issue if headers reaching haproxy
6224 are under the control of the end-user.
6225
Willy Tarreauc27debf2008-01-06 08:57:02 +01006226 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02006227 least one of them uses it, the header will be added. Note that the backend's
6228 setting of the header subargument takes precedence over the frontend's if
Willy Tarreau87cf5142011-08-19 22:57:24 +02006229 both are defined. In the case of the "if-none" argument, if at least one of
6230 the frontend or the backend does not specify it, it wants the addition to be
6231 mandatory, so it wins.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006232
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02006233 Example :
Willy Tarreauc27debf2008-01-06 08:57:02 +01006234 # Public HTTP address also used by stunnel on the same machine
6235 frontend www
6236 mode http
6237 option forwardfor except 127.0.0.1 # stunnel already adds the header
6238
Ross Westaf72a1d2008-08-03 10:51:45 +02006239 # Those servers want the IP Address in X-Client
6240 backend www
6241 mode http
6242 option forwardfor header X-Client
6243
Willy Tarreau87cf5142011-08-19 22:57:24 +02006244 See also : "option httpclose", "option http-server-close",
Christopher Faulet315b39c2018-09-21 16:26:19 +02006245 "option http-keep-alive"
Willy Tarreauc27debf2008-01-06 08:57:02 +01006246
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006247
Christopher Faulet98fbe952019-07-22 16:18:24 +02006248option h1-case-adjust-bogus-client
6249no option h1-case-adjust-bogus-client
6250 Enable or disable the case adjustment of HTTP/1 headers sent to bogus clients
6251 May be used in sections : defaults | frontend | listen | backend
6252 yes | yes | yes | no
6253 Arguments : none
6254
6255 There is no standard case for header names because, as stated in RFC7230,
6256 they are case-insensitive. So applications must handle them in a case-
6257 insensitive manner. But some bogus applications violate the standards and
6258 erroneously rely on the cases most commonly used by browsers. This problem
6259 becomes critical with HTTP/2 because all header names must be exchanged in
6260 lower case, and HAProxy follows the same convention. All header names are
6261 sent in lower case to clients and servers, regardless of the HTTP version.
6262
6263 When HAProxy receives an HTTP/1 response, its header names are converted to
6264 lower case and manipulated and sent this way to the clients. If a client is
6265 known to violate the HTTP standards and to fail to process a response coming
6266 from HAProxy, it is possible to transform the lower case header names to a
6267 different format when the response is formatted and sent to the client, by
6268 enabling this option and specifying the list of headers to be reformatted
6269 using the global directives "h1-case-adjust" or "h1-case-adjust-file". This
6270 must only be a temporary workaround for the time it takes the client to be
6271 fixed, because clients which require such workarounds might be vulnerable to
6272 content smuggling attacks and must absolutely be fixed.
6273
6274 Please note that this option will not affect standards-compliant clients.
6275
6276 If this option has been enabled in a "defaults" section, it can be disabled
6277 in a specific instance by prepending the "no" keyword before it.
6278
6279 See also: "option h1-case-adjust-bogus-server", "h1-case-adjust",
6280 "h1-case-adjust-file".
6281
6282
6283option h1-case-adjust-bogus-server
6284no option h1-case-adjust-bogus-server
6285 Enable or disable the case adjustment of HTTP/1 headers sent to bogus servers
6286 May be used in sections : defaults | frontend | listen | backend
6287 yes | no | yes | yes
6288 Arguments : none
6289
6290 There is no standard case for header names because, as stated in RFC7230,
6291 they are case-insensitive. So applications must handle them in a case-
6292 insensitive manner. But some bogus applications violate the standards and
6293 erroneously rely on the cases most commonly used by browsers. This problem
6294 becomes critical with HTTP/2 because all header names must be exchanged in
6295 lower case, and HAProxy follows the same convention. All header names are
6296 sent in lower case to clients and servers, regardless of the HTTP version.
6297
6298 When HAProxy receives an HTTP/1 request, its header names are converted to
6299 lower case and manipulated and sent this way to the servers. If a server is
6300 known to violate the HTTP standards and to fail to process a request coming
6301 from HAProxy, it is possible to transform the lower case header names to a
6302 different format when the request is formatted and sent to the server, by
6303 enabling this option and specifying the list of headers to be reformatted
6304 using the global directives "h1-case-adjust" or "h1-case-adjust-file". This
6305 must only be a temporary workaround for the time it takes the server to be
6306 fixed, because servers which require such workarounds might be vulnerable to
6307 content smuggling attacks and must absolutely be fixed.
6308
6309 Please note that this option will not affect standards-compliant servers.
6310
6311 If this option has been enabled in a "defaults" section, it can be disabled
6312 in a specific instance by prepending the "no" keyword before it.
6313
6314 See also: "option h1-case-adjust-bogus-client", "h1-case-adjust",
6315 "h1-case-adjust-file".
6316
6317
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02006318option http-buffer-request
6319no option http-buffer-request
6320 Enable or disable waiting for whole HTTP request body before proceeding
6321 May be used in sections : defaults | frontend | listen | backend
6322 yes | yes | yes | yes
6323 Arguments : none
6324
6325 It is sometimes desirable to wait for the body of an HTTP request before
6326 taking a decision. This is what is being done by "balance url_param" for
6327 example. The first use case is to buffer requests from slow clients before
6328 connecting to the server. Another use case consists in taking the routing
6329 decision based on the request body's contents. This option placed in a
6330 frontend or backend forces the HTTP processing to wait until either the whole
Christopher Faulet6db8a2e2019-11-19 16:27:25 +01006331 body is received or the request buffer is full. It can have undesired side
6332 effects with some applications abusing HTTP by expecting unbuffered
6333 transmissions between the frontend and the backend, so this should definitely
6334 not be used by default.
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02006335
Baptiste Assmanneccdf432015-10-28 13:49:01 +01006336 See also : "option http-no-delay", "timeout http-request"
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02006337
6338
Willy Tarreau0f228a02015-05-01 15:37:53 +02006339option http-ignore-probes
6340no option http-ignore-probes
6341 Enable or disable logging of null connections and request timeouts
6342 May be used in sections : defaults | frontend | listen | backend
6343 yes | yes | yes | no
6344 Arguments : none
6345
6346 Recently some browsers started to implement a "pre-connect" feature
6347 consisting in speculatively connecting to some recently visited web sites
6348 just in case the user would like to visit them. This results in many
6349 connections being established to web sites, which end up in 408 Request
6350 Timeout if the timeout strikes first, or 400 Bad Request when the browser
6351 decides to close them first. These ones pollute the log and feed the error
6352 counters. There was already "option dontlognull" but it's insufficient in
6353 this case. Instead, this option does the following things :
6354 - prevent any 400/408 message from being sent to the client if nothing
Davor Ocelice9ed2812017-12-25 17:49:28 +01006355 was received over a connection before it was closed;
6356 - prevent any log from being emitted in this situation;
Willy Tarreau0f228a02015-05-01 15:37:53 +02006357 - prevent any error counter from being incremented
6358
6359 That way the empty connection is silently ignored. Note that it is better
6360 not to use this unless it is clear that it is needed, because it will hide
6361 real problems. The most common reason for not receiving a request and seeing
6362 a 408 is due to an MTU inconsistency between the client and an intermediary
6363 element such as a VPN, which blocks too large packets. These issues are
6364 generally seen with POST requests as well as GET with large cookies. The logs
6365 are often the only way to detect them.
6366
6367 If this option has been enabled in a "defaults" section, it can be disabled
6368 in a specific instance by prepending the "no" keyword before it.
6369
6370 See also : "log", "dontlognull", "errorfile", and section 8 about logging.
6371
6372
Willy Tarreau16bfb022010-01-16 19:48:41 +01006373option http-keep-alive
6374no option http-keep-alive
6375 Enable or disable HTTP keep-alive from client to server
6376 May be used in sections : defaults | frontend | listen | backend
6377 yes | yes | yes | yes
6378 Arguments : none
6379
Willy Tarreau70dffda2014-01-30 03:07:23 +01006380 By default HAProxy operates in keep-alive mode with regards to persistent
6381 connections: for each connection it processes each request and response, and
Christopher Faulet315b39c2018-09-21 16:26:19 +02006382 leaves the connection idle on both sides between the end of a response and
6383 the start of a new request. This mode may be changed by several options such
Christopher Faulet159e6672019-07-16 15:09:52 +02006384 as "option http-server-close" or "option httpclose". This option allows to
6385 set back the keep-alive mode, which can be useful when another mode was used
6386 in a defaults section.
Willy Tarreau70dffda2014-01-30 03:07:23 +01006387
6388 Setting "option http-keep-alive" enables HTTP keep-alive mode on the client-
6389 and server- sides. This provides the lowest latency on the client side (slow
Willy Tarreau16bfb022010-01-16 19:48:41 +01006390 network) and the fastest session reuse on the server side at the expense
6391 of maintaining idle connections to the servers. In general, it is possible
6392 with this option to achieve approximately twice the request rate that the
6393 "http-server-close" option achieves on small objects. There are mainly two
6394 situations where this option may be useful :
6395
6396 - when the server is non-HTTP compliant and authenticates the connection
Davor Ocelice9ed2812017-12-25 17:49:28 +01006397 instead of requests (e.g. NTLM authentication)
Willy Tarreau16bfb022010-01-16 19:48:41 +01006398
6399 - when the cost of establishing the connection to the server is significant
6400 compared to the cost of retrieving the associated object from the server.
6401
6402 This last case can happen when the server is a fast static server of cache.
6403 In this case, the server will need to be properly tuned to support high enough
6404 connection counts because connections will last until the client sends another
6405 request.
6406
6407 If the client request has to go to another backend or another server due to
6408 content switching or the load balancing algorithm, the idle connection will
Willy Tarreau9420b122013-12-15 18:58:25 +01006409 immediately be closed and a new one re-opened. Option "prefer-last-server" is
6410 available to try optimize server selection so that if the server currently
6411 attached to an idle connection is usable, it will be used.
Willy Tarreau16bfb022010-01-16 19:48:41 +01006412
Willy Tarreau16bfb022010-01-16 19:48:41 +01006413 At the moment, logs will not indicate whether requests came from the same
6414 session or not. The accept date reported in the logs corresponds to the end
6415 of the previous request, and the request time corresponds to the time spent
6416 waiting for a new request. The keep-alive request time is still bound to the
6417 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
6418 not set.
6419
Christopher Faulet159e6672019-07-16 15:09:52 +02006420 This option disables and replaces any previous "option httpclose" or "option
6421 http-server-close". When backend and frontend options differ, all of these 4
6422 options have precedence over "option http-keep-alive".
Willy Tarreau16bfb022010-01-16 19:48:41 +01006423
Christopher Faulet315b39c2018-09-21 16:26:19 +02006424 See also : "option httpclose",, "option http-server-close",
Willy Tarreau9420b122013-12-15 18:58:25 +01006425 "option prefer-last-server", "option http-pretend-keepalive",
Frédéric Lécaille93d33162019-03-06 09:35:59 +01006426 and "1.1. The HTTP transaction model".
Willy Tarreau16bfb022010-01-16 19:48:41 +01006427
6428
Willy Tarreau96e31212011-05-30 18:10:30 +02006429option http-no-delay
6430no option http-no-delay
6431 Instruct the system to favor low interactive delays over performance in HTTP
6432 May be used in sections : defaults | frontend | listen | backend
6433 yes | yes | yes | yes
6434 Arguments : none
6435
6436 In HTTP, each payload is unidirectional and has no notion of interactivity.
6437 Any agent is expected to queue data somewhat for a reasonably low delay.
6438 There are some very rare server-to-server applications that abuse the HTTP
6439 protocol and expect the payload phase to be highly interactive, with many
6440 interleaved data chunks in both directions within a single request. This is
6441 absolutely not supported by the HTTP specification and will not work across
6442 most proxies or servers. When such applications attempt to do this through
6443 haproxy, it works but they will experience high delays due to the network
6444 optimizations which favor performance by instructing the system to wait for
6445 enough data to be available in order to only send full packets. Typical
6446 delays are around 200 ms per round trip. Note that this only happens with
6447 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
6448 affected.
6449
6450 When "option http-no-delay" is present in either the frontend or the backend
6451 used by a connection, all such optimizations will be disabled in order to
6452 make the exchanges as fast as possible. Of course this offers no guarantee on
6453 the functionality, as it may break at any other place. But if it works via
6454 HAProxy, it will work as fast as possible. This option should never be used
6455 by default, and should never be used at all unless such a buggy application
6456 is discovered. The impact of using this option is an increase of bandwidth
6457 usage and CPU usage, which may significantly lower performance in high
6458 latency environments.
6459
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02006460 See also : "option http-buffer-request"
6461
Willy Tarreau96e31212011-05-30 18:10:30 +02006462
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006463option http-pretend-keepalive
6464no option http-pretend-keepalive
6465 Define whether haproxy will announce keepalive to the server or not
6466 May be used in sections : defaults | frontend | listen | backend
Christopher Faulet98db9762018-09-21 10:25:19 +02006467 yes | no | yes | yes
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006468 Arguments : none
6469
Christopher Faulet315b39c2018-09-21 16:26:19 +02006470 When running with "option http-server-close" or "option httpclose", haproxy
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006471 adds a "Connection: close" header to the request forwarded to the server.
6472 Unfortunately, when some servers see this header, they automatically refrain
6473 from using the chunked encoding for responses of unknown length, while this
6474 is totally unrelated. The immediate effect is that this prevents haproxy from
6475 maintaining the client connection alive. A second effect is that a client or
6476 a cache could receive an incomplete response without being aware of it, and
6477 consider the response complete.
6478
6479 By setting "option http-pretend-keepalive", haproxy will make the server
6480 believe it will keep the connection alive. The server will then not fall back
6481 to the abnormal undesired above. When haproxy gets the whole response, it
6482 will close the connection with the server just as it would do with the
Christopher Faulet315b39c2018-09-21 16:26:19 +02006483 "option httpclose". That way the client gets a normal response and the
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006484 connection is correctly closed on the server side.
6485
6486 It is recommended not to enable this option by default, because most servers
6487 will more efficiently close the connection themselves after the last packet,
6488 and release its buffers slightly earlier. Also, the added packet on the
6489 network could slightly reduce the overall peak performance. However it is
6490 worth noting that when this option is enabled, haproxy will have slightly
6491 less work to do. So if haproxy is the bottleneck on the whole architecture,
6492 enabling this option might save a few CPU cycles.
6493
Christopher Faulet98db9762018-09-21 10:25:19 +02006494 This option may be set in backend and listen sections. Using it in a frontend
6495 section will be ignored and a warning will be reported during startup. It is
6496 a backend related option, so there is no real reason to set it on a
6497 frontend. This option may be combined with "option httpclose", which will
6498 cause keepalive to be announced to the server and close to be announced to
6499 the client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006500
6501 If this option has been enabled in a "defaults" section, it can be disabled
6502 in a specific instance by prepending the "no" keyword before it.
6503
Christopher Faulet315b39c2018-09-21 16:26:19 +02006504 See also : "option httpclose", "option http-server-close", and
Willy Tarreau16bfb022010-01-16 19:48:41 +01006505 "option http-keep-alive"
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006506
Willy Tarreauc27debf2008-01-06 08:57:02 +01006507
Willy Tarreaub608feb2010-01-02 22:47:18 +01006508option http-server-close
6509no option http-server-close
6510 Enable or disable HTTP connection closing on the server side
6511 May be used in sections : defaults | frontend | listen | backend
6512 yes | yes | yes | yes
6513 Arguments : none
6514
Willy Tarreau70dffda2014-01-30 03:07:23 +01006515 By default HAProxy operates in keep-alive mode with regards to persistent
6516 connections: for each connection it processes each request and response, and
6517 leaves the connection idle on both sides between the end of a response and
6518 the start of a new request. This mode may be changed by several options such
Christopher Faulet159e6672019-07-16 15:09:52 +02006519 as "option http-server-close" or "option httpclose". Setting "option
6520 http-server-close" enables HTTP connection-close mode on the server side
6521 while keeping the ability to support HTTP keep-alive and pipelining on the
6522 client side. This provides the lowest latency on the client side (slow
6523 network) and the fastest session reuse on the server side to save server
6524 resources, similarly to "option httpclose". It also permits non-keepalive
6525 capable servers to be served in keep-alive mode to the clients if they
6526 conform to the requirements of RFC7230. Please note that some servers do not
6527 always conform to those requirements when they see "Connection: close" in the
6528 request. The effect will be that keep-alive will never be used. A workaround
6529 consists in enabling "option http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01006530
6531 At the moment, logs will not indicate whether requests came from the same
6532 session or not. The accept date reported in the logs corresponds to the end
6533 of the previous request, and the request time corresponds to the time spent
6534 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01006535 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
6536 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01006537
6538 This option may be set both in a frontend and in a backend. It is enabled if
6539 at least one of the frontend or backend holding a connection has it enabled.
Christopher Faulet159e6672019-07-16 15:09:52 +02006540 It disables and replaces any previous "option httpclose" or "option
6541 http-keep-alive". Please check section 4 ("Proxies") to see how this option
6542 combines with others when frontend and backend options differ.
Willy Tarreaub608feb2010-01-02 22:47:18 +01006543
6544 If this option has been enabled in a "defaults" section, it can be disabled
6545 in a specific instance by prepending the "no" keyword before it.
6546
Christopher Faulet315b39c2018-09-21 16:26:19 +02006547 See also : "option httpclose", "option http-pretend-keepalive",
6548 "option http-keep-alive", and "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01006549
Willy Tarreau88d349d2010-01-25 12:15:43 +01006550option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01006551no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01006552 Make use of non-standard Proxy-Connection header instead of Connection
6553 May be used in sections : defaults | frontend | listen | backend
6554 yes | yes | yes | no
6555 Arguments : none
6556
Lukas Tribus23953682017-04-28 13:24:30 +00006557 While RFC7230 explicitly states that HTTP/1.1 agents must use the
Willy Tarreau88d349d2010-01-25 12:15:43 +01006558 Connection header to indicate their wish of persistent or non-persistent
6559 connections, both browsers and proxies ignore this header for proxied
6560 connections and make use of the undocumented, non-standard Proxy-Connection
6561 header instead. The issue begins when trying to put a load balancer between
6562 browsers and such proxies, because there will be a difference between what
6563 haproxy understands and what the client and the proxy agree on.
6564
6565 By setting this option in a frontend, haproxy can automatically switch to use
6566 that non-standard header if it sees proxied requests. A proxied request is
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01006567 defined here as one where the URI begins with neither a '/' nor a '*'. This
6568 is incompatible with the HTTP tunnel mode. Note that this option can only be
6569 specified in a frontend and will affect the request along its whole life.
Willy Tarreau88d349d2010-01-25 12:15:43 +01006570
Willy Tarreau844a7e72010-01-31 21:46:18 +01006571 Also, when this option is set, a request which requires authentication will
6572 automatically switch to use proxy authentication headers if it is itself a
6573 proxied request. That makes it possible to check or enforce authentication in
6574 front of an existing proxy.
6575
Willy Tarreau88d349d2010-01-25 12:15:43 +01006576 This option should normally never be used, except in front of a proxy.
6577
Christopher Faulet315b39c2018-09-21 16:26:19 +02006578 See also : "option httpclose", and "option http-server-close".
Willy Tarreau88d349d2010-01-25 12:15:43 +01006579
Willy Tarreaud63335a2010-02-26 12:56:52 +01006580option httpchk
6581option httpchk <uri>
6582option httpchk <method> <uri>
6583option httpchk <method> <uri> <version>
6584 Enable HTTP protocol to check on the servers health
6585 May be used in sections : defaults | frontend | listen | backend
6586 yes | no | yes | yes
6587 Arguments :
6588 <method> is the optional HTTP method used with the requests. When not set,
6589 the "OPTIONS" method is used, as it generally requires low server
6590 processing and is easy to filter out from the logs. Any method
6591 may be used, though it is not recommended to invent non-standard
6592 ones.
6593
6594 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
6595 which is accessible by default on almost any server, but may be
6596 changed to any other URI. Query strings are permitted.
6597
6598 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
6599 but some servers might behave incorrectly in HTTP 1.0, so turning
6600 it to HTTP/1.1 may sometimes help. Note that the Host field is
6601 mandatory in HTTP/1.1, and as a trick, it is possible to pass it
6602 after "\r\n" following the version string.
6603
6604 By default, server health checks only consist in trying to establish a TCP
6605 connection. When "option httpchk" is specified, a complete HTTP request is
6606 sent once the TCP connection is established, and responses 2xx and 3xx are
6607 considered valid, while all other ones indicate a server failure, including
6608 the lack of any response.
6609
6610 The port and interval are specified in the server configuration.
6611
6612 This option does not necessarily require an HTTP backend, it also works with
6613 plain TCP backends. This is particularly useful to check simple scripts bound
6614 to some dedicated ports using the inetd daemon.
6615
6616 Examples :
6617 # Relay HTTPS traffic to Apache instance and check service availability
6618 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
6619 backend https_relay
6620 mode tcp
6621 option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www
6622 server apache1 192.168.1.1:443 check port 80
6623
Simon Hormanafc47ee2013-11-25 10:46:35 +09006624 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
6625 "option pgsql-check", "http-check" and the "check", "port" and
6626 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01006627
6628
Willy Tarreauc27debf2008-01-06 08:57:02 +01006629option httpclose
6630no option httpclose
Christopher Faulet315b39c2018-09-21 16:26:19 +02006631 Enable or disable HTTP connection closing
Willy Tarreauc27debf2008-01-06 08:57:02 +01006632 May be used in sections : defaults | frontend | listen | backend
6633 yes | yes | yes | yes
6634 Arguments : none
6635
Willy Tarreau70dffda2014-01-30 03:07:23 +01006636 By default HAProxy operates in keep-alive mode with regards to persistent
6637 connections: for each connection it processes each request and response, and
6638 leaves the connection idle on both sides between the end of a response and
6639 the start of a new request. This mode may be changed by several options such
Christopher Faulet159e6672019-07-16 15:09:52 +02006640 as "option http-server-close" or "option httpclose".
Willy Tarreau70dffda2014-01-30 03:07:23 +01006641
Christopher Faulet315b39c2018-09-21 16:26:19 +02006642 If "option httpclose" is set, HAProxy will close connections with the server
6643 and the client as soon as the request and the response are received. It will
John Roeslerfb2fce12019-07-10 15:45:51 -05006644 also check if a "Connection: close" header is already set in each direction,
Christopher Faulet315b39c2018-09-21 16:26:19 +02006645 and will add one if missing. Any "Connection" header different from "close"
6646 will also be removed.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006647
Christopher Faulet315b39c2018-09-21 16:26:19 +02006648 This option may also be combined with "option http-pretend-keepalive", which
6649 will disable sending of the "Connection: close" header, but will still cause
6650 the connection to be closed once the whole response is received.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006651
6652 This option may be set both in a frontend and in a backend. It is enabled if
6653 at least one of the frontend or backend holding a connection has it enabled.
Christopher Faulet159e6672019-07-16 15:09:52 +02006654 It disables and replaces any previous "option http-server-close" or "option
6655 http-keep-alive". Please check section 4 ("Proxies") to see how this option
6656 combines with others when frontend and backend options differ.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006657
6658 If this option has been enabled in a "defaults" section, it can be disabled
6659 in a specific instance by prepending the "no" keyword before it.
6660
Christopher Faulet315b39c2018-09-21 16:26:19 +02006661 See also : "option http-server-close" and "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01006662
6663
Emeric Brun3a058f32009-06-30 18:26:00 +02006664option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01006665 Enable logging of HTTP request, session state and timers
6666 May be used in sections : defaults | frontend | listen | backend
Tim Duesterhus9ad9f352018-02-05 20:52:27 +01006667 yes | yes | yes | no
Emeric Brun3a058f32009-06-30 18:26:00 +02006668 Arguments :
6669 clf if the "clf" argument is added, then the output format will be
6670 the CLF format instead of HAProxy's default HTTP format. You can
6671 use this when you need to feed HAProxy's logs through a specific
Davor Ocelice9ed2812017-12-25 17:49:28 +01006672 log analyzer which only support the CLF format and which is not
Emeric Brun3a058f32009-06-30 18:26:00 +02006673 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006674
6675 By default, the log output format is very poor, as it only contains the
6676 source and destination addresses, and the instance name. By specifying
6677 "option httplog", each log line turns into a much richer format including,
6678 but not limited to, the HTTP request, the connection timers, the session
6679 status, the connections numbers, the captured headers and cookies, the
6680 frontend, backend and server name, and of course the source address and
6681 ports.
6682
PiBa-NLbd556bf2014-12-11 21:31:54 +01006683 Specifying only "option httplog" will automatically clear the 'clf' mode
6684 if it was set by default.
Emeric Brun3a058f32009-06-30 18:26:00 +02006685
Guillaume de Lafond29f45602017-03-31 19:52:15 +02006686 "option httplog" overrides any previous "log-format" directive.
6687
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006688 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006689
Willy Tarreau55165fe2009-05-10 12:02:55 +02006690
6691option http_proxy
6692no option http_proxy
6693 Enable or disable plain HTTP proxy mode
6694 May be used in sections : defaults | frontend | listen | backend
6695 yes | yes | yes | yes
6696 Arguments : none
6697
6698 It sometimes happens that people need a pure HTTP proxy which understands
6699 basic proxy requests without caching nor any fancy feature. In this case,
6700 it may be worth setting up an HAProxy instance with the "option http_proxy"
6701 set. In this mode, no server is declared, and the connection is forwarded to
6702 the IP address and port found in the URL after the "http://" scheme.
6703
6704 No host address resolution is performed, so this only works when pure IP
6705 addresses are passed. Since this option's usage perimeter is rather limited,
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01006706 it will probably be used only by experts who know they need exactly it. This
6707 is incompatible with the HTTP tunnel mode.
Willy Tarreau55165fe2009-05-10 12:02:55 +02006708
6709 If this option has been enabled in a "defaults" section, it can be disabled
6710 in a specific instance by prepending the "no" keyword before it.
6711
6712 Example :
6713 # this backend understands HTTP proxy requests and forwards them directly.
6714 backend direct_forward
6715 option httpclose
6716 option http_proxy
6717
6718 See also : "option httpclose"
6719
Willy Tarreau211ad242009-10-03 21:45:07 +02006720
Jamie Gloudon801a0a32012-08-25 00:18:33 -04006721option independent-streams
6722no option independent-streams
6723 Enable or disable independent timeout processing for both directions
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02006724 May be used in sections : defaults | frontend | listen | backend
6725 yes | yes | yes | yes
6726 Arguments : none
6727
6728 By default, when data is sent over a socket, both the write timeout and the
6729 read timeout for that socket are refreshed, because we consider that there is
6730 activity on that socket, and we have no other means of guessing if we should
6731 receive data or not.
6732
Davor Ocelice9ed2812017-12-25 17:49:28 +01006733 While this default behavior is desirable for almost all applications, there
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02006734 exists a situation where it is desirable to disable it, and only refresh the
6735 read timeout if there are incoming data. This happens on sessions with large
6736 timeouts and low amounts of exchanged data such as telnet session. If the
6737 server suddenly disappears, the output data accumulates in the system's
6738 socket buffers, both timeouts are correctly refreshed, and there is no way
6739 to know the server does not receive them, so we don't timeout. However, when
6740 the underlying protocol always echoes sent data, it would be enough by itself
6741 to detect the issue using the read timeout. Note that this problem does not
6742 happen with more verbose protocols because data won't accumulate long in the
6743 socket buffers.
6744
6745 When this option is set on the frontend, it will disable read timeout updates
6746 on data sent to the client. There probably is little use of this case. When
6747 the option is set on the backend, it will disable read timeout updates on
6748 data sent to the server. Doing so will typically break large HTTP posts from
6749 slow lines, so use it with caution.
6750
Willy Tarreauce887fd2012-05-12 12:50:00 +02006751 See also : "timeout client", "timeout server" and "timeout tunnel"
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02006752
6753
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02006754option ldap-check
6755 Use LDAPv3 health checks for server testing
6756 May be used in sections : defaults | frontend | listen | backend
6757 yes | no | yes | yes
6758 Arguments : none
6759
6760 It is possible to test that the server correctly talks LDAPv3 instead of just
6761 testing that it accepts the TCP connection. When this option is set, an
6762 LDAPv3 anonymous simple bind message is sent to the server, and the response
6763 is analyzed to find an LDAPv3 bind response message.
6764
6765 The server is considered valid only when the LDAP response contains success
6766 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
6767
6768 Logging of bind requests is server dependent see your documentation how to
6769 configure it.
6770
6771 Example :
6772 option ldap-check
6773
6774 See also : "option httpchk"
6775
6776
Simon Horman98637e52014-06-20 12:30:16 +09006777option external-check
6778 Use external processes for server health checks
6779 May be used in sections : defaults | frontend | listen | backend
6780 yes | no | yes | yes
6781
6782 It is possible to test the health of a server using an external command.
6783 This is achieved by running the executable set using "external-check
6784 command".
6785
6786 Requires the "external-check" global to be set.
6787
6788 See also : "external-check", "external-check command", "external-check path"
6789
6790
Willy Tarreau211ad242009-10-03 21:45:07 +02006791option log-health-checks
6792no option log-health-checks
Willy Tarreaubef1b322014-05-13 21:01:39 +02006793 Enable or disable logging of health checks status updates
Willy Tarreau211ad242009-10-03 21:45:07 +02006794 May be used in sections : defaults | frontend | listen | backend
6795 yes | no | yes | yes
6796 Arguments : none
6797
Willy Tarreaubef1b322014-05-13 21:01:39 +02006798 By default, failed health check are logged if server is UP and successful
6799 health checks are logged if server is DOWN, so the amount of additional
6800 information is limited.
Willy Tarreau211ad242009-10-03 21:45:07 +02006801
Willy Tarreaubef1b322014-05-13 21:01:39 +02006802 When this option is enabled, any change of the health check status or to
6803 the server's health will be logged, so that it becomes possible to know
6804 that a server was failing occasional checks before crashing, or exactly when
6805 it failed to respond a valid HTTP status, then when the port started to
6806 reject connections, then when the server stopped responding at all.
6807
Davor Ocelice9ed2812017-12-25 17:49:28 +01006808 Note that status changes not caused by health checks (e.g. enable/disable on
Willy Tarreaubef1b322014-05-13 21:01:39 +02006809 the CLI) are intentionally not logged by this option.
Willy Tarreau211ad242009-10-03 21:45:07 +02006810
Willy Tarreaubef1b322014-05-13 21:01:39 +02006811 See also: "option httpchk", "option ldap-check", "option mysql-check",
6812 "option pgsql-check", "option redis-check", "option smtpchk",
6813 "option tcp-check", "log" and section 8 about logging.
Willy Tarreau211ad242009-10-03 21:45:07 +02006814
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02006815
6816option log-separate-errors
6817no option log-separate-errors
6818 Change log level for non-completely successful connections
6819 May be used in sections : defaults | frontend | listen | backend
6820 yes | yes | yes | no
6821 Arguments : none
6822
6823 Sometimes looking for errors in logs is not easy. This option makes haproxy
6824 raise the level of logs containing potentially interesting information such
6825 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
6826 level changes from "info" to "err". This makes it possible to log them
6827 separately to a different file with most syslog daemons. Be careful not to
6828 remove them from the original file, otherwise you would lose ordering which
6829 provides very important information.
6830
6831 Using this option, large sites dealing with several thousand connections per
6832 second may log normal traffic to a rotating buffer and only archive smaller
6833 error logs.
6834
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006835 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02006836 logging.
6837
Willy Tarreauc27debf2008-01-06 08:57:02 +01006838
6839option logasap
6840no option logasap
6841 Enable or disable early logging of HTTP requests
6842 May be used in sections : defaults | frontend | listen | backend
6843 yes | yes | yes | no
6844 Arguments : none
6845
6846 By default, HTTP requests are logged upon termination so that the total
6847 transfer time and the number of bytes appear in the logs. When large objects
6848 are being transferred, it may take a while before the request appears in the
6849 logs. Using "option logasap", the request gets logged as soon as the server
6850 sends the complete headers. The only missing information in the logs will be
6851 the total number of bytes which will indicate everything except the amount
6852 of data transferred, and the total time which will not take the transfer
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006853 time into account. In such a situation, it's a good practice to capture the
Willy Tarreauc27debf2008-01-06 08:57:02 +01006854 "Content-Length" response header so that the logs at least indicate how many
6855 bytes are expected to be transferred.
6856
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006857 Examples :
6858 listen http_proxy 0.0.0.0:80
6859 mode http
6860 option httplog
6861 option logasap
6862 log 192.168.2.200 local3
6863
6864 >>> Feb 6 12:14:14 localhost \
6865 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
6866 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
6867 "GET /image.iso HTTP/1.0"
6868
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006869 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01006870 logging.
6871
6872
Nenad Merdanovic6639a7c2014-05-30 14:26:32 +02006873option mysql-check [ user <username> [ post-41 ] ]
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006874 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01006875 May be used in sections : defaults | frontend | listen | backend
6876 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006877 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006878 <username> This is the username which will be used when connecting to MySQL
6879 server.
Nenad Merdanovic6639a7c2014-05-30 14:26:32 +02006880 post-41 Send post v4.1 client compatible checks
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006881
6882 If you specify a username, the check consists of sending two MySQL packet,
6883 one Client Authentication packet, and one QUIT packet, to correctly close
Davor Ocelice9ed2812017-12-25 17:49:28 +01006884 MySQL session. We then parse the MySQL Handshake Initialization packet and/or
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006885 Error packet. It is a basic but useful test which does not produce error nor
6886 aborted connect on the server. However, it requires adding an authorization
6887 in the MySQL table, like this :
6888
6889 USE mysql;
6890 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
6891 FLUSH PRIVILEGES;
6892
6893 If you don't specify a username (it is deprecated and not recommended), the
Davor Ocelice9ed2812017-12-25 17:49:28 +01006894 check only consists in parsing the Mysql Handshake Initialization packet or
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006895 Error packet, we don't send anything in this mode. It was reported that it
6896 can generate lockout if check is too frequent and/or if there is not enough
6897 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
6898 value as if a connection is established successfully within fewer than MySQL
6899 "max_connect_errors" attempts after a previous connection was interrupted,
6900 the error count for the host is cleared to zero. If HAProxy's server get
6901 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
6902
6903 Remember that this does not check database presence nor database consistency.
6904 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01006905
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02006906 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01006907
6908 Most often, an incoming MySQL server needs to see the client's IP address for
6909 various purposes, including IP privilege matching and connection logging.
6910 When possible, it is often wise to masquerade the client's IP address when
6911 connecting to the server using the "usesrc" argument of the "source" keyword,
Willy Tarreau29fbe512015-08-20 19:35:14 +02006912 which requires the transparent proxy feature to be compiled in, and the MySQL
6913 server to route the client via the machine hosting haproxy.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01006914
6915 See also: "option httpchk"
6916
6917
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006918option nolinger
6919no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006920 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006921 May be used in sections: defaults | frontend | listen | backend
6922 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006923 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006924
Davor Ocelice9ed2812017-12-25 17:49:28 +01006925 When clients or servers abort connections in a dirty way (e.g. they are
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006926 physically disconnected), the session timeouts triggers and the session is
6927 closed. But it will remain in FIN_WAIT1 state for some time in the system,
6928 using some resources and possibly limiting the ability to establish newer
6929 connections.
6930
6931 When this happens, it is possible to activate "option nolinger" which forces
6932 the system to immediately remove any socket's pending data on close. Thus,
6933 the session is instantly purged from the system's tables. This usually has
6934 side effects such as increased number of TCP resets due to old retransmits
6935 getting immediately rejected. Some firewalls may sometimes complain about
6936 this too.
6937
6938 For this reason, it is not recommended to use this option when not absolutely
6939 needed. You know that you need it when you have thousands of FIN_WAIT1
6940 sessions on your system (TIME_WAIT ones do not count).
6941
6942 This option may be used both on frontends and backends, depending on the side
6943 where it is required. Use it on the frontend for clients, and on the backend
6944 for servers.
6945
6946 If this option has been enabled in a "defaults" section, it can be disabled
6947 in a specific instance by prepending the "no" keyword before it.
6948
6949
Willy Tarreau55165fe2009-05-10 12:02:55 +02006950option originalto [ except <network> ] [ header <name> ]
6951 Enable insertion of the X-Original-To header to requests sent to servers
6952 May be used in sections : defaults | frontend | listen | backend
6953 yes | yes | yes | yes
6954 Arguments :
6955 <network> is an optional argument used to disable this option for sources
6956 matching <network>
6957 <name> an optional argument to specify a different "X-Original-To"
6958 header name.
6959
6960 Since HAProxy can work in transparent mode, every request from a client can
6961 be redirected to the proxy and HAProxy itself can proxy every request to a
6962 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
6963 be lost. This is annoying when you want access rules based on destination ip
6964 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
6965 added by HAProxy to all requests sent to the server. This header contains a
6966 value representing the original destination IP address. Since this must be
6967 configured to always use the last occurrence of this header only. Note that
6968 only the last occurrence of the header must be used, since it is really
6969 possible that the client has already brought one.
6970
6971 The keyword "header" may be used to supply a different header name to replace
6972 the default "X-Original-To". This can be useful where you might already
6973 have a "X-Original-To" header from a different application, and you need
6974 preserve it. Also if your backend server doesn't use the "X-Original-To"
6975 header and requires different one.
6976
6977 Sometimes, a same HAProxy instance may be shared between a direct client
6978 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
6979 used to decrypt HTTPS traffic). It is possible to disable the addition of the
6980 header for a known source address or network by adding the "except" keyword
6981 followed by the network address. In this case, any source IP matching the
6982 network will not cause an addition of this header. Most common uses are with
6983 private networks or 127.0.0.1.
6984
6985 This option may be specified either in the frontend or in the backend. If at
6986 least one of them uses it, the header will be added. Note that the backend's
6987 setting of the header subargument takes precedence over the frontend's if
6988 both are defined.
6989
Willy Tarreau55165fe2009-05-10 12:02:55 +02006990 Examples :
6991 # Original Destination address
6992 frontend www
6993 mode http
6994 option originalto except 127.0.0.1
6995
6996 # Those servers want the IP Address in X-Client-Dst
6997 backend www
6998 mode http
6999 option originalto header X-Client-Dst
7000
Christopher Faulet315b39c2018-09-21 16:26:19 +02007001 See also : "option httpclose", "option http-server-close".
Willy Tarreau55165fe2009-05-10 12:02:55 +02007002
7003
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007004option persist
7005no option persist
7006 Enable or disable forced persistence on down servers
7007 May be used in sections: defaults | frontend | listen | backend
7008 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007009 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007010
7011 When an HTTP request reaches a backend with a cookie which references a dead
7012 server, by default it is redispatched to another server. It is possible to
7013 force the request to be sent to the dead server first using "option persist"
7014 if absolutely needed. A common use case is when servers are under extreme
7015 load and spend their time flapping. In this case, the users would still be
7016 directed to the server they opened the session on, in the hope they would be
7017 correctly served. It is recommended to use "option redispatch" in conjunction
7018 with this option so that in the event it would not be possible to connect to
7019 the server at all (server definitely dead), the client would finally be
7020 redirected to another valid server.
7021
7022 If this option has been enabled in a "defaults" section, it can be disabled
7023 in a specific instance by prepending the "no" keyword before it.
7024
Willy Tarreau4de91492010-01-22 19:10:05 +01007025 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007026
7027
Willy Tarreau0c122822013-12-15 18:49:01 +01007028option pgsql-check [ user <username> ]
7029 Use PostgreSQL health checks for server testing
7030 May be used in sections : defaults | frontend | listen | backend
7031 yes | no | yes | yes
7032 Arguments :
7033 <username> This is the username which will be used when connecting to
7034 PostgreSQL server.
7035
7036 The check sends a PostgreSQL StartupMessage and waits for either
7037 Authentication request or ErrorResponse message. It is a basic but useful
7038 test which does not produce error nor aborted connect on the server.
7039 This check is identical with the "mysql-check".
7040
7041 See also: "option httpchk"
7042
7043
Willy Tarreau9420b122013-12-15 18:58:25 +01007044option prefer-last-server
7045no option prefer-last-server
7046 Allow multiple load balanced requests to remain on the same server
7047 May be used in sections: defaults | frontend | listen | backend
7048 yes | no | yes | yes
7049 Arguments : none
7050
7051 When the load balancing algorithm in use is not deterministic, and a previous
7052 request was sent to a server to which haproxy still holds a connection, it is
7053 sometimes desirable that subsequent requests on a same session go to the same
7054 server as much as possible. Note that this is different from persistence, as
7055 we only indicate a preference which haproxy tries to apply without any form
7056 of warranty. The real use is for keep-alive connections sent to servers. When
7057 this option is used, haproxy will try to reuse the same connection that is
7058 attached to the server instead of rebalancing to another server, causing a
7059 close of the connection. This can make sense for static file servers. It does
Willy Tarreau068621e2013-12-23 15:11:25 +01007060 not make much sense to use this in combination with hashing algorithms. Note,
7061 haproxy already automatically tries to stick to a server which sends a 401 or
Lukas Tribus80512b12018-10-27 20:07:40 +02007062 to a proxy which sends a 407 (authentication required), when the load
7063 balancing algorithm is not deterministic. This is mandatory for use with the
7064 broken NTLM authentication challenge, and significantly helps in
Willy Tarreau068621e2013-12-23 15:11:25 +01007065 troubleshooting some faulty applications. Option prefer-last-server might be
7066 desirable in these environments as well, to avoid redistributing the traffic
7067 after every other response.
Willy Tarreau9420b122013-12-15 18:58:25 +01007068
7069 If this option has been enabled in a "defaults" section, it can be disabled
7070 in a specific instance by prepending the "no" keyword before it.
7071
7072 See also: "option http-keep-alive"
7073
7074
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007075option redispatch
Joseph Lynch726ab712015-05-11 23:25:34 -07007076option redispatch <interval>
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007077no option redispatch
7078 Enable or disable session redistribution in case of connection failure
7079 May be used in sections: defaults | frontend | listen | backend
7080 yes | no | yes | yes
Joseph Lynch726ab712015-05-11 23:25:34 -07007081 Arguments :
7082 <interval> The optional integer value that controls how often redispatches
7083 occur when retrying connections. Positive value P indicates a
7084 redispatch is desired on every Pth retry, and negative value
Davor Ocelice9ed2812017-12-25 17:49:28 +01007085 N indicate a redispatch is desired on the Nth retry prior to the
Joseph Lynch726ab712015-05-11 23:25:34 -07007086 last retry. For example, the default of -1 preserves the
Davor Ocelice9ed2812017-12-25 17:49:28 +01007087 historical behavior of redispatching on the last retry, a
Joseph Lynch726ab712015-05-11 23:25:34 -07007088 positive value of 1 would indicate a redispatch on every retry,
7089 and a positive value of 3 would indicate a redispatch on every
7090 third retry. You can disable redispatches with a value of 0.
7091
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007092
7093 In HTTP mode, if a server designated by a cookie is down, clients may
7094 definitely stick to it because they cannot flush the cookie, so they will not
7095 be able to access the service anymore.
7096
Willy Tarreau59884a62019-01-02 14:48:31 +01007097 Specifying "option redispatch" will allow the proxy to break cookie or
7098 consistent hash based persistence and redistribute them to a working server.
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007099
Joseph Lynch726ab712015-05-11 23:25:34 -07007100 It also allows to retry connections to another server in case of multiple
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007101 connection failures. Of course, it requires having "retries" set to a nonzero
7102 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01007103
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007104 If this option has been enabled in a "defaults" section, it can be disabled
7105 in a specific instance by prepending the "no" keyword before it.
7106
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02007107 See also : "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007108
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007109
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02007110option redis-check
7111 Use redis health checks for server testing
7112 May be used in sections : defaults | frontend | listen | backend
7113 yes | no | yes | yes
7114 Arguments : none
7115
7116 It is possible to test that the server correctly talks REDIS protocol instead
7117 of just testing that it accepts the TCP connection. When this option is set,
7118 a PING redis command is sent to the server, and the response is analyzed to
7119 find the "+PONG" response message.
7120
7121 Example :
7122 option redis-check
7123
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03007124 See also : "option httpchk", "option tcp-check", "tcp-check expect"
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02007125
7126
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007127option smtpchk
7128option smtpchk <hello> <domain>
7129 Use SMTP health checks for server testing
7130 May be used in sections : defaults | frontend | listen | backend
7131 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01007132 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007133 <hello> is an optional argument. It is the "hello" command to use. It can
Lukas Tribus27935782018-10-01 02:00:16 +02007134 be either "HELO" (for SMTP) or "EHLO" (for ESMTP). All other
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007135 values will be turned into the default command ("HELO").
7136
7137 <domain> is the domain name to present to the server. It may only be
7138 specified (and is mandatory) if the hello command has been
7139 specified. By default, "localhost" is used.
7140
7141 When "option smtpchk" is set, the health checks will consist in TCP
7142 connections followed by an SMTP command. By default, this command is
7143 "HELO localhost". The server's return code is analyzed and only return codes
7144 starting with a "2" will be considered as valid. All other responses,
7145 including a lack of response will constitute an error and will indicate a
7146 dead server.
7147
7148 This test is meant to be used with SMTP servers or relays. Depending on the
7149 request, it is possible that some servers do not log each connection attempt,
Davor Ocelice9ed2812017-12-25 17:49:28 +01007150 so you may want to experiment to improve the behavior. Using telnet on port
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007151 25 is often easier than adjusting the configuration.
7152
7153 Most often, an incoming SMTP server needs to see the client's IP address for
7154 various purposes, including spam filtering, anti-spoofing and logging. When
7155 possible, it is often wise to masquerade the client's IP address when
7156 connecting to the server using the "usesrc" argument of the "source" keyword,
Willy Tarreau29fbe512015-08-20 19:35:14 +02007157 which requires the transparent proxy feature to be compiled in.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007158
7159 Example :
7160 option smtpchk HELO mydomain.org
7161
7162 See also : "option httpchk", "source"
7163
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007164
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02007165option socket-stats
7166no option socket-stats
7167
7168 Enable or disable collecting & providing separate statistics for each socket.
7169 May be used in sections : defaults | frontend | listen | backend
7170 yes | yes | yes | no
7171
7172 Arguments : none
7173
7174
Willy Tarreauff4f82d2009-02-06 11:28:13 +01007175option splice-auto
7176no option splice-auto
7177 Enable or disable automatic kernel acceleration on sockets in both directions
7178 May be used in sections : defaults | frontend | listen | backend
7179 yes | yes | yes | yes
7180 Arguments : none
7181
7182 When this option is enabled either on a frontend or on a backend, haproxy
7183 will automatically evaluate the opportunity to use kernel tcp splicing to
Davor Ocelice9ed2812017-12-25 17:49:28 +01007184 forward data between the client and the server, in either direction. HAProxy
Willy Tarreauff4f82d2009-02-06 11:28:13 +01007185 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007186 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01007187 are not much aggressive in order to limit excessive use of splicing. This
7188 option requires splicing to be enabled at compile time, and may be globally
7189 disabled with the global option "nosplice". Since splice uses pipes, using it
7190 requires that there are enough spare pipes.
7191
7192 Important note: kernel-based TCP splicing is a Linux-specific feature which
7193 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
7194 transfer data between sockets without copying these data to user-space, thus
7195 providing noticeable performance gains and CPU cycles savings. Since many
7196 early implementations are buggy, corrupt data and/or are inefficient, this
7197 feature is not enabled by default, and it should be used with extreme care.
7198 While it is not possible to detect the correctness of an implementation,
7199 2.6.29 is the first version offering a properly working implementation. In
7200 case of doubt, splicing may be globally disabled using the global "nosplice"
7201 keyword.
7202
7203 Example :
7204 option splice-auto
7205
7206 If this option has been enabled in a "defaults" section, it can be disabled
7207 in a specific instance by prepending the "no" keyword before it.
7208
7209 See also : "option splice-request", "option splice-response", and global
7210 options "nosplice" and "maxpipes"
7211
7212
7213option splice-request
7214no option splice-request
7215 Enable or disable automatic kernel acceleration on sockets for requests
7216 May be used in sections : defaults | frontend | listen | backend
7217 yes | yes | yes | yes
7218 Arguments : none
7219
7220 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04007221 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01007222 the client to the server. It might still use the recv/send scheme if there
7223 are no spare pipes left. This option requires splicing to be enabled at
7224 compile time, and may be globally disabled with the global option "nosplice".
7225 Since splice uses pipes, using it requires that there are enough spare pipes.
7226
7227 Important note: see "option splice-auto" for usage limitations.
7228
7229 Example :
7230 option splice-request
7231
7232 If this option has been enabled in a "defaults" section, it can be disabled
7233 in a specific instance by prepending the "no" keyword before it.
7234
7235 See also : "option splice-auto", "option splice-response", and global options
7236 "nosplice" and "maxpipes"
7237
7238
7239option splice-response
7240no option splice-response
7241 Enable or disable automatic kernel acceleration on sockets for responses
7242 May be used in sections : defaults | frontend | listen | backend
7243 yes | yes | yes | yes
7244 Arguments : none
7245
7246 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04007247 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01007248 the server to the client. It might still use the recv/send scheme if there
7249 are no spare pipes left. This option requires splicing to be enabled at
7250 compile time, and may be globally disabled with the global option "nosplice".
7251 Since splice uses pipes, using it requires that there are enough spare pipes.
7252
7253 Important note: see "option splice-auto" for usage limitations.
7254
7255 Example :
7256 option splice-response
7257
7258 If this option has been enabled in a "defaults" section, it can be disabled
7259 in a specific instance by prepending the "no" keyword before it.
7260
7261 See also : "option splice-auto", "option splice-request", and global options
7262 "nosplice" and "maxpipes"
7263
7264
Christopher Fauletba7bc162016-11-07 21:07:38 +01007265option spop-check
7266 Use SPOP health checks for server testing
7267 May be used in sections : defaults | frontend | listen | backend
7268 no | no | no | yes
7269 Arguments : none
7270
7271 It is possible to test that the server correctly talks SPOP protocol instead
7272 of just testing that it accepts the TCP connection. When this option is set,
7273 a HELLO handshake is performed between HAProxy and the server, and the
7274 response is analyzed to check no error is reported.
7275
7276 Example :
7277 option spop-check
7278
7279 See also : "option httpchk"
7280
7281
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007282option srvtcpka
7283no option srvtcpka
7284 Enable or disable the sending of TCP keepalive packets on the server side
7285 May be used in sections : defaults | frontend | listen | backend
7286 yes | no | yes | yes
7287 Arguments : none
7288
7289 When there is a firewall or any session-aware component between a client and
7290 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01007291 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007292 components decides to expire a session which has remained idle for too long.
7293
7294 Enabling socket-level TCP keep-alives makes the system regularly send packets
7295 to the other end of the connection, leaving it active. The delay between
7296 keep-alive probes is controlled by the system only and depends both on the
7297 operating system and its tuning parameters.
7298
7299 It is important to understand that keep-alive packets are neither emitted nor
7300 received at the application level. It is only the network stacks which sees
7301 them. For this reason, even if one side of the proxy already uses keep-alives
7302 to maintain its connection alive, those keep-alive packets will not be
7303 forwarded to the other side of the proxy.
7304
7305 Please note that this has nothing to do with HTTP keep-alive.
7306
7307 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
7308 server side of a connection, which should help when session expirations are
7309 noticed between HAProxy and a server.
7310
7311 If this option has been enabled in a "defaults" section, it can be disabled
7312 in a specific instance by prepending the "no" keyword before it.
7313
7314 See also : "option clitcpka", "option tcpka"
7315
7316
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007317option ssl-hello-chk
7318 Use SSLv3 client hello health checks for server testing
7319 May be used in sections : defaults | frontend | listen | backend
7320 yes | no | yes | yes
7321 Arguments : none
7322
7323 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
7324 possible to test that the server correctly talks SSL instead of just testing
7325 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
7326 SSLv3 client hello messages are sent once the connection is established to
7327 the server, and the response is analyzed to find an SSL server hello message.
7328 The server is considered valid only when the response contains this server
7329 hello message.
7330
7331 All servers tested till there correctly reply to SSLv3 client hello messages,
7332 and most servers tested do not even log the requests containing only hello
7333 messages, which is appreciable.
7334
Willy Tarreau763a95b2012-10-04 23:15:39 +02007335 Note that this check works even when SSL support was not built into haproxy
7336 because it forges the SSL message. When SSL support is available, it is best
7337 to use native SSL health checks instead of this one.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007338
Willy Tarreau763a95b2012-10-04 23:15:39 +02007339 See also: "option httpchk", "check-ssl"
7340
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007341
Willy Tarreaued179852013-12-16 01:07:00 +01007342option tcp-check
7343 Perform health checks using tcp-check send/expect sequences
7344 May be used in sections: defaults | frontend | listen | backend
7345 yes | no | yes | yes
7346
7347 This health check method is intended to be combined with "tcp-check" command
7348 lists in order to support send/expect types of health check sequences.
7349
7350 TCP checks currently support 4 modes of operations :
7351 - no "tcp-check" directive : the health check only consists in a connection
7352 attempt, which remains the default mode.
7353
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007354 - "tcp-check send" or "tcp-check send-binary" only is mentioned : this is
Willy Tarreaued179852013-12-16 01:07:00 +01007355 used to send a string along with a connection opening. With some
7356 protocols, it helps sending a "QUIT" message for example that prevents
7357 the server from logging a connection error for each health check. The
7358 check result will still be based on the ability to open the connection
7359 only.
7360
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007361 - "tcp-check expect" only is mentioned : this is used to test a banner.
Willy Tarreaued179852013-12-16 01:07:00 +01007362 The connection is opened and haproxy waits for the server to present some
7363 contents which must validate some rules. The check result will be based
7364 on the matching between the contents and the rules. This is suited for
7365 POP, IMAP, SMTP, FTP, SSH, TELNET.
7366
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007367 - both "tcp-check send" and "tcp-check expect" are mentioned : this is
Davor Ocelice9ed2812017-12-25 17:49:28 +01007368 used to test a hello-type protocol. HAProxy sends a message, the server
7369 responds and its response is analyzed. the check result will be based on
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007370 the matching between the response contents and the rules. This is often
Willy Tarreaued179852013-12-16 01:07:00 +01007371 suited for protocols which require a binding or a request/response model.
7372 LDAP, MySQL, Redis and SSL are example of such protocols, though they
7373 already all have their dedicated checks with a deeper understanding of
7374 the respective protocols.
7375 In this mode, many questions may be sent and many answers may be
Davor Ocelice9ed2812017-12-25 17:49:28 +01007376 analyzed.
Willy Tarreaued179852013-12-16 01:07:00 +01007377
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007378 A fifth mode can be used to insert comments in different steps of the
7379 script.
7380
7381 For each tcp-check rule you create, you can add a "comment" directive,
7382 followed by a string. This string will be reported in the log and stderr
7383 in debug mode. It is useful to make user-friendly error reporting.
7384 The "comment" is of course optional.
7385
7386
Willy Tarreaued179852013-12-16 01:07:00 +01007387 Examples :
Davor Ocelice9ed2812017-12-25 17:49:28 +01007388 # perform a POP check (analyze only server's banner)
Willy Tarreaued179852013-12-16 01:07:00 +01007389 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007390 tcp-check expect string +OK\ POP3\ ready comment POP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01007391
Davor Ocelice9ed2812017-12-25 17:49:28 +01007392 # perform an IMAP check (analyze only server's banner)
Willy Tarreaued179852013-12-16 01:07:00 +01007393 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007394 tcp-check expect string *\ OK\ IMAP4\ ready comment IMAP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01007395
7396 # look for the redis master server after ensuring it speaks well
7397 # redis protocol, then it exits properly.
Davor Ocelice9ed2812017-12-25 17:49:28 +01007398 # (send a command then analyze the response 3 times)
Willy Tarreaued179852013-12-16 01:07:00 +01007399 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007400 tcp-check comment PING\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01007401 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +02007402 tcp-check expect string +PONG
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007403 tcp-check comment role\ check
Willy Tarreaued179852013-12-16 01:07:00 +01007404 tcp-check send info\ replication\r\n
7405 tcp-check expect string role:master
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007406 tcp-check comment QUIT\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01007407 tcp-check send QUIT\r\n
7408 tcp-check expect string +OK
7409
Davor Ocelice9ed2812017-12-25 17:49:28 +01007410 forge a HTTP request, then analyze the response
Willy Tarreaued179852013-12-16 01:07:00 +01007411 (send many headers before analyzing)
7412 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007413 tcp-check comment forge\ and\ send\ HTTP\ request
Willy Tarreaued179852013-12-16 01:07:00 +01007414 tcp-check send HEAD\ /\ HTTP/1.1\r\n
7415 tcp-check send Host:\ www.mydomain.com\r\n
7416 tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n
7417 tcp-check send \r\n
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007418 tcp-check expect rstring HTTP/1\..\ (2..|3..) comment check\ HTTP\ response
Willy Tarreaued179852013-12-16 01:07:00 +01007419
7420
7421 See also : "tcp-check expect", "tcp-check send"
7422
7423
Willy Tarreau9ea05a72009-06-14 12:07:01 +02007424option tcp-smart-accept
7425no option tcp-smart-accept
7426 Enable or disable the saving of one ACK packet during the accept sequence
7427 May be used in sections : defaults | frontend | listen | backend
7428 yes | yes | yes | no
7429 Arguments : none
7430
7431 When an HTTP connection request comes in, the system acknowledges it on
7432 behalf of HAProxy, then the client immediately sends its request, and the
7433 system acknowledges it too while it is notifying HAProxy about the new
7434 connection. HAProxy then reads the request and responds. This means that we
7435 have one TCP ACK sent by the system for nothing, because the request could
7436 very well be acknowledged by HAProxy when it sends its response.
7437
7438 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
7439 sending this useless ACK on platforms which support it (currently at least
7440 Linux). It must not cause any problem, because the system will send it anyway
7441 after 40 ms if the response takes more time than expected to come.
7442
7443 During complex network debugging sessions, it may be desirable to disable
7444 this optimization because delayed ACKs can make troubleshooting more complex
7445 when trying to identify where packets are delayed. It is then possible to
Davor Ocelice9ed2812017-12-25 17:49:28 +01007446 fall back to normal behavior by specifying "no option tcp-smart-accept".
Willy Tarreau9ea05a72009-06-14 12:07:01 +02007447
7448 It is also possible to force it for non-HTTP proxies by simply specifying
7449 "option tcp-smart-accept". For instance, it can make sense with some services
7450 such as SMTP where the server speaks first.
7451
7452 It is recommended to avoid forcing this option in a defaults section. In case
7453 of doubt, consider setting it back to automatic values by prepending the
7454 "default" keyword before it, or disabling it using the "no" keyword.
7455
Willy Tarreaud88edf22009-06-14 15:48:17 +02007456 See also : "option tcp-smart-connect"
7457
7458
7459option tcp-smart-connect
7460no option tcp-smart-connect
7461 Enable or disable the saving of one ACK packet during the connect sequence
7462 May be used in sections : defaults | frontend | listen | backend
7463 yes | no | yes | yes
7464 Arguments : none
7465
7466 On certain systems (at least Linux), HAProxy can ask the kernel not to
7467 immediately send an empty ACK upon a connection request, but to directly
7468 send the buffer request instead. This saves one packet on the network and
7469 thus boosts performance. It can also be useful for some servers, because they
7470 immediately get the request along with the incoming connection.
7471
7472 This feature is enabled when "option tcp-smart-connect" is set in a backend.
7473 It is not enabled by default because it makes network troubleshooting more
7474 complex.
7475
7476 It only makes sense to enable it with protocols where the client speaks first
7477 such as HTTP. In other situations, if there is no data to send in place of
7478 the ACK, a normal ACK is sent.
7479
7480 If this option has been enabled in a "defaults" section, it can be disabled
7481 in a specific instance by prepending the "no" keyword before it.
7482
7483 See also : "option tcp-smart-accept"
7484
Willy Tarreau9ea05a72009-06-14 12:07:01 +02007485
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007486option tcpka
7487 Enable or disable the sending of TCP keepalive packets on both sides
7488 May be used in sections : defaults | frontend | listen | backend
7489 yes | yes | yes | yes
7490 Arguments : none
7491
7492 When there is a firewall or any session-aware component between a client and
7493 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01007494 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007495 components decides to expire a session which has remained idle for too long.
7496
7497 Enabling socket-level TCP keep-alives makes the system regularly send packets
7498 to the other end of the connection, leaving it active. The delay between
7499 keep-alive probes is controlled by the system only and depends both on the
7500 operating system and its tuning parameters.
7501
7502 It is important to understand that keep-alive packets are neither emitted nor
7503 received at the application level. It is only the network stacks which sees
7504 them. For this reason, even if one side of the proxy already uses keep-alives
7505 to maintain its connection alive, those keep-alive packets will not be
7506 forwarded to the other side of the proxy.
7507
7508 Please note that this has nothing to do with HTTP keep-alive.
7509
7510 Using option "tcpka" enables the emission of TCP keep-alive probes on both
7511 the client and server sides of a connection. Note that this is meaningful
7512 only in "defaults" or "listen" sections. If this option is used in a
7513 frontend, only the client side will get keep-alives, and if this option is
7514 used in a backend, only the server side will get keep-alives. For this
7515 reason, it is strongly recommended to explicitly use "option clitcpka" and
7516 "option srvtcpka" when the configuration is split between frontends and
7517 backends.
7518
7519 See also : "option clitcpka", "option srvtcpka"
7520
Willy Tarreau844e3c52008-01-11 16:28:18 +01007521
7522option tcplog
7523 Enable advanced logging of TCP connections with session state and timers
7524 May be used in sections : defaults | frontend | listen | backend
Tim Duesterhus9ad9f352018-02-05 20:52:27 +01007525 yes | yes | yes | no
Willy Tarreau844e3c52008-01-11 16:28:18 +01007526 Arguments : none
7527
7528 By default, the log output format is very poor, as it only contains the
7529 source and destination addresses, and the instance name. By specifying
7530 "option tcplog", each log line turns into a much richer format including, but
7531 not limited to, the connection timers, the session status, the connections
7532 numbers, the frontend, backend and server name, and of course the source
7533 address and ports. This option is useful for pure TCP proxies in order to
7534 find which of the client or server disconnects or times out. For normal HTTP
7535 proxies, it's better to use "option httplog" which is even more complete.
7536
Guillaume de Lafond29f45602017-03-31 19:52:15 +02007537 "option tcplog" overrides any previous "log-format" directive.
7538
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007539 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007540
7541
Willy Tarreau844e3c52008-01-11 16:28:18 +01007542option transparent
7543no option transparent
7544 Enable client-side transparent proxying
7545 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01007546 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01007547 Arguments : none
7548
7549 This option was introduced in order to provide layer 7 persistence to layer 3
7550 load balancers. The idea is to use the OS's ability to redirect an incoming
7551 connection for a remote address to a local process (here HAProxy), and let
7552 this process know what address was initially requested. When this option is
7553 used, sessions without cookies will be forwarded to the original destination
7554 IP address of the incoming request (which should match that of another
7555 equipment), while requests with cookies will still be forwarded to the
7556 appropriate server.
7557
7558 Note that contrary to a common belief, this option does NOT make HAProxy
7559 present the client's IP to the server when establishing the connection.
7560
Willy Tarreaua1146052011-03-01 09:51:54 +01007561 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007562 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007563
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007564
Simon Horman98637e52014-06-20 12:30:16 +09007565external-check command <command>
7566 Executable to run when performing an external-check
7567 May be used in sections : defaults | frontend | listen | backend
7568 yes | no | yes | yes
7569
7570 Arguments :
7571 <command> is the external command to run
7572
Simon Horman98637e52014-06-20 12:30:16 +09007573 The arguments passed to the to the command are:
7574
Cyril Bonté777be862014-12-02 21:21:35 +01007575 <proxy_address> <proxy_port> <server_address> <server_port>
Simon Horman98637e52014-06-20 12:30:16 +09007576
Cyril Bonté777be862014-12-02 21:21:35 +01007577 The <proxy_address> and <proxy_port> are derived from the first listener
7578 that is either IPv4, IPv6 or a UNIX socket. In the case of a UNIX socket
7579 listener the proxy_address will be the path of the socket and the
7580 <proxy_port> will be the string "NOT_USED". In a backend section, it's not
7581 possible to determine a listener, and both <proxy_address> and <proxy_port>
7582 will have the string value "NOT_USED".
Simon Horman98637e52014-06-20 12:30:16 +09007583
Cyril Bonté72cda2a2014-12-27 22:28:39 +01007584 Some values are also provided through environment variables.
7585
7586 Environment variables :
7587 HAPROXY_PROXY_ADDR The first bind address if available (or empty if not
7588 applicable, for example in a "backend" section).
7589
7590 HAPROXY_PROXY_ID The backend id.
7591
7592 HAPROXY_PROXY_NAME The backend name.
7593
7594 HAPROXY_PROXY_PORT The first bind port if available (or empty if not
7595 applicable, for example in a "backend" section or
7596 for a UNIX socket).
7597
7598 HAPROXY_SERVER_ADDR The server address.
7599
7600 HAPROXY_SERVER_CURCONN The current number of connections on the server.
7601
7602 HAPROXY_SERVER_ID The server id.
7603
7604 HAPROXY_SERVER_MAXCONN The server max connections.
7605
7606 HAPROXY_SERVER_NAME The server name.
7607
7608 HAPROXY_SERVER_PORT The server port if available (or empty for a UNIX
7609 socket).
7610
7611 PATH The PATH environment variable used when executing
7612 the command may be set using "external-check path".
7613
William Lallemand4d03e432019-06-14 15:35:37 +02007614 See also "2.3. Environment variables" for other variables.
7615
Simon Horman98637e52014-06-20 12:30:16 +09007616 If the command executed and exits with a zero status then the check is
7617 considered to have passed, otherwise the check is considered to have
7618 failed.
7619
7620 Example :
7621 external-check command /bin/true
7622
7623 See also : "external-check", "option external-check", "external-check path"
7624
7625
7626external-check path <path>
7627 The value of the PATH environment variable used when running an external-check
7628 May be used in sections : defaults | frontend | listen | backend
7629 yes | no | yes | yes
7630
7631 Arguments :
7632 <path> is the path used when executing external command to run
7633
7634 The default path is "".
7635
7636 Example :
7637 external-check path "/usr/bin:/bin"
7638
7639 See also : "external-check", "option external-check",
7640 "external-check command"
7641
7642
Emeric Brun647caf12009-06-30 17:57:00 +02007643persist rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007644persist rdp-cookie(<name>)
Emeric Brun647caf12009-06-30 17:57:00 +02007645 Enable RDP cookie-based persistence
7646 May be used in sections : defaults | frontend | listen | backend
7647 yes | no | yes | yes
7648 Arguments :
7649 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02007650 default cookie name "msts" will be used. There currently is no
7651 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02007652
7653 This statement enables persistence based on an RDP cookie. The RDP cookie
7654 contains all information required to find the server in the list of known
Davor Ocelice9ed2812017-12-25 17:49:28 +01007655 servers. So when this option is set in the backend, the request is analyzed
Emeric Brun647caf12009-06-30 17:57:00 +02007656 and if an RDP cookie is found, it is decoded. If it matches a known server
7657 which is still UP (or if "option persist" is set), then the connection is
7658 forwarded to this server.
7659
7660 Note that this only makes sense in a TCP backend, but for this to work, the
7661 frontend must have waited long enough to ensure that an RDP cookie is present
7662 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007663 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02007664 a single "listen" section.
7665
Willy Tarreau61e28f22010-05-16 22:31:05 +02007666 Also, it is important to understand that the terminal server will emit this
7667 RDP cookie only if it is configured for "token redirection mode", which means
7668 that the "IP address redirection" option is disabled.
7669
Emeric Brun647caf12009-06-30 17:57:00 +02007670 Example :
7671 listen tse-farm
7672 bind :3389
7673 # wait up to 5s for an RDP cookie in the request
7674 tcp-request inspect-delay 5s
7675 tcp-request content accept if RDP_COOKIE
7676 # apply RDP cookie persistence
7677 persist rdp-cookie
7678 # if server is unknown, let's balance on the same cookie.
Cyril Bontédc4d9032012-04-08 21:57:39 +02007679 # alternatively, "balance leastconn" may be useful too.
Emeric Brun647caf12009-06-30 17:57:00 +02007680 balance rdp-cookie
7681 server srv1 1.1.1.1:3389
7682 server srv2 1.1.1.2:3389
7683
Simon Hormanab814e02011-06-24 14:50:20 +09007684 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
7685 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02007686
7687
Willy Tarreau3a7d2072009-03-05 23:48:25 +01007688rate-limit sessions <rate>
7689 Set a limit on the number of new sessions accepted per second on a frontend
7690 May be used in sections : defaults | frontend | listen | backend
7691 yes | yes | yes | no
7692 Arguments :
7693 <rate> The <rate> parameter is an integer designating the maximum number
7694 of new sessions per second to accept on the frontend.
7695
7696 When the frontend reaches the specified number of new sessions per second, it
7697 stops accepting new connections until the rate drops below the limit again.
7698 During this time, the pending sessions will be kept in the socket's backlog
7699 (in system buffers) and haproxy will not even be aware that sessions are
7700 pending. When applying very low limit on a highly loaded service, it may make
7701 sense to increase the socket's backlog using the "backlog" keyword.
7702
7703 This feature is particularly efficient at blocking connection-based attacks
7704 or service abuse on fragile servers. Since the session rate is measured every
7705 millisecond, it is extremely accurate. Also, the limit applies immediately,
7706 no delay is needed at all to detect the threshold.
7707
7708 Example : limit the connection rate on SMTP to 10 per second max
7709 listen smtp
7710 mode tcp
7711 bind :25
7712 rate-limit sessions 10
Panagiotis Panagiotopoulos7282d8e2016-02-11 16:37:15 +02007713 server smtp1 127.0.0.1:1025
Willy Tarreau3a7d2072009-03-05 23:48:25 +01007714
Willy Tarreaua17c2d92011-07-25 08:16:20 +02007715 Note : when the maximum rate is reached, the frontend's status is not changed
7716 but its sockets appear as "WAITING" in the statistics if the
7717 "socket-stats" option is enabled.
Willy Tarreau3a7d2072009-03-05 23:48:25 +01007718
7719 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
7720
7721
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007722redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
7723redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
7724redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007725 Return an HTTP redirection if/unless a condition is matched
7726 May be used in sections : defaults | frontend | listen | backend
7727 no | yes | yes | yes
7728
7729 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01007730 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007731
Willy Tarreau0140f252008-11-19 21:07:09 +01007732 Arguments :
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007733 <loc> With "redirect location", the exact value in <loc> is placed into
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007734 the HTTP "Location" header. When used in an "http-request" rule,
7735 <loc> value follows the log-format rules and can include some
7736 dynamic values (see Custom Log Format in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007737
7738 <pfx> With "redirect prefix", the "Location" header is built from the
7739 concatenation of <pfx> and the complete URI path, including the
7740 query string, unless the "drop-query" option is specified (see
7741 below). As a special case, if <pfx> equals exactly "/", then
7742 nothing is inserted before the original URI. It allows one to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007743 redirect to the same URL (for instance, to insert a cookie). When
7744 used in an "http-request" rule, <pfx> value follows the log-format
7745 rules and can include some dynamic values (see Custom Log Format
7746 in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007747
7748 <sch> With "redirect scheme", then the "Location" header is built by
7749 concatenating <sch> with "://" then the first occurrence of the
7750 "Host" header, and then the URI path, including the query string
7751 unless the "drop-query" option is specified (see below). If no
7752 path is found or if the path is "*", then "/" is used instead. If
7753 no "Host" header is found, then an empty host component will be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007754 returned, which most recent browsers interpret as redirecting to
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007755 the same host. This directive is mostly used to redirect HTTP to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007756 HTTPS. When used in an "http-request" rule, <sch> value follows
7757 the log-format rules and can include some dynamic values (see
7758 Custom Log Format in section 8.2.4).
Willy Tarreau0140f252008-11-19 21:07:09 +01007759
7760 <code> The code is optional. It indicates which type of HTTP redirection
Willy Tarreaub67fdc42013-03-29 19:28:11 +01007761 is desired. Only codes 301, 302, 303, 307 and 308 are supported,
7762 with 302 used by default if no code is specified. 301 means
7763 "Moved permanently", and a browser may cache the Location. 302
Baptiste Assmannea849c02015-08-03 11:42:50 +02007764 means "Moved temporarily" and means that the browser should not
Willy Tarreaub67fdc42013-03-29 19:28:11 +01007765 cache the redirection. 303 is equivalent to 302 except that the
7766 browser will fetch the location with a GET method. 307 is just
7767 like 302 but makes it clear that the same method must be reused.
7768 Likewise, 308 replaces 301 if the same method must be used.
Willy Tarreau0140f252008-11-19 21:07:09 +01007769
7770 <option> There are several options which can be specified to adjust the
Davor Ocelice9ed2812017-12-25 17:49:28 +01007771 expected behavior of a redirection :
Willy Tarreau0140f252008-11-19 21:07:09 +01007772
7773 - "drop-query"
7774 When this keyword is used in a prefix-based redirection, then the
7775 location will be set without any possible query-string, which is useful
7776 for directing users to a non-secure page for instance. It has no effect
7777 with a location-type redirect.
7778
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01007779 - "append-slash"
7780 This keyword may be used in conjunction with "drop-query" to redirect
7781 users who use a URL not ending with a '/' to the same one with the '/'.
7782 It can be useful to ensure that search engines will only see one URL.
7783 For this, a return code 301 is preferred.
7784
Willy Tarreau0140f252008-11-19 21:07:09 +01007785 - "set-cookie NAME[=value]"
7786 A "Set-Cookie" header will be added with NAME (and optionally "=value")
7787 to the response. This is sometimes used to indicate that a user has
7788 been seen, for instance to protect against some types of DoS. No other
7789 cookie option is added, so the cookie will be a session cookie. Note
7790 that for a browser, a sole cookie name without an equal sign is
7791 different from a cookie with an equal sign.
7792
7793 - "clear-cookie NAME[=]"
7794 A "Set-Cookie" header will be added with NAME (and optionally "="), but
7795 with the "Max-Age" attribute set to zero. This will tell the browser to
7796 delete this cookie. It is useful for instance on logout pages. It is
7797 important to note that clearing the cookie "NAME" will not remove a
7798 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
7799 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007800
7801 Example: move the login URL only to HTTPS.
7802 acl clear dst_port 80
7803 acl secure dst_port 8080
7804 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01007805 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01007806 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01007807 acl cookie_set hdr_sub(cookie) SEEN=1
7808
7809 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01007810 redirect prefix https://mysite.com if login_page !secure
7811 redirect prefix http://mysite.com drop-query if login_page !uid_given
7812 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01007813 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007814
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01007815 Example: send redirects for request for articles without a '/'.
7816 acl missing_slash path_reg ^/article/[^/]*$
7817 redirect code 301 prefix / drop-query append-slash if missing_slash
7818
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007819 Example: redirect all HTTP traffic to HTTPS when SSL is handled by haproxy.
David BERARDe7153042012-11-03 00:11:31 +01007820 redirect scheme https if !{ ssl_fc }
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007821
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007822 Example: append 'www.' prefix in front of all hosts not having it
Coen Rosdorff596659b2016-04-11 11:33:49 +02007823 http-request redirect code 301 location \
7824 http://www.%[hdr(host)]%[capture.req.uri] \
7825 unless { hdr_beg(host) -i www }
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007826
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007827 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007828
Willy Tarreau303c0352008-01-17 19:01:39 +01007829
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02007830retries <value>
7831 Set the number of retries to perform on a server after a connection failure
7832 May be used in sections: defaults | frontend | listen | backend
7833 yes | no | yes | yes
7834 Arguments :
7835 <value> is the number of times a connection attempt should be retried on
7836 a server when a connection either is refused or times out. The
7837 default value is 3.
7838
7839 It is important to understand that this value applies to the number of
7840 connection attempts, not full requests. When a connection has effectively
7841 been established to a server, there will be no more retry.
7842
7843 In order to avoid immediate reconnections to a server which is restarting,
Joseph Lynch726ab712015-05-11 23:25:34 -07007844 a turn-around timer of min("timeout connect", one second) is applied before
7845 a retry occurs.
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02007846
7847 When "option redispatch" is set, the last retry may be performed on another
7848 server even if a cookie references a different server.
7849
7850 See also : "option redispatch"
7851
7852
Olivier Houcharda254a372019-04-05 15:30:12 +02007853retry-on [list of keywords]
7854 Specify when to attempt to automatically retry a failed request
7855 May be used in sections: defaults | frontend | listen | backend
7856 yes | no | yes | yes
7857 Arguments :
7858 <keywords> is a list of keywords or HTTP status codes, each representing a
7859 type of failure event on which an attempt to retry the request
7860 is desired. Please read the notes at the bottom before changing
7861 this setting. The following keywords are supported :
7862
7863 none never retry
7864
7865 conn-failure retry when the connection or the SSL handshake failed
7866 and the request could not be sent. This is the default.
7867
7868 empty-response retry when the server connection was closed after part
7869 of the request was sent, and nothing was received from
7870 the server. This type of failure may be caused by the
7871 request timeout on the server side, poor network
7872 condition, or a server crash or restart while
7873 processing the request.
7874
Olivier Houcharde3249a92019-05-03 23:01:47 +02007875 junk-response retry when the server returned something not looking
7876 like a complete HTTP response. This includes partial
7877 responses headers as well as non-HTTP contents. It
7878 usually is a bad idea to retry on such events, which
7879 may be caused a configuration issue (wrong server port)
7880 or by the request being harmful to the server (buffer
7881 overflow attack for example).
7882
Olivier Houcharda254a372019-04-05 15:30:12 +02007883 response-timeout the server timeout stroke while waiting for the server
7884 to respond to the request. This may be caused by poor
7885 network condition, the reuse of an idle connection
7886 which has expired on the path, or by the request being
7887 extremely expensive to process. It generally is a bad
7888 idea to retry on such events on servers dealing with
7889 heavy database processing (full scans, etc) as it may
7890 amplify denial of service attacks.
7891
Olivier Houchard865d8392019-05-03 22:46:27 +02007892 0rtt-rejected retry requests which were sent over early data and were
7893 rejected by the server. These requests are generally
7894 considered to be safe to retry.
7895
Olivier Houcharda254a372019-04-05 15:30:12 +02007896 <status> any HTTP status code among "404" (Not Found), "408"
7897 (Request Timeout), "425" (Too Early), "500" (Server
7898 Error), "501" (Not Implemented), "502" (Bad Gateway),
7899 "503" (Service Unavailable), "504" (Gateway Timeout).
7900
Olivier Houchardddf0e032019-05-10 18:05:40 +02007901 all-retryable-errors
7902 retry request for any error that are considered
7903 retryable. This currently activates "conn-failure",
7904 "empty-response", "junk-response", "response-timeout",
7905 "0rtt-rejected", "500", "502", "503", and "504".
7906
Olivier Houcharda254a372019-04-05 15:30:12 +02007907 Using this directive replaces any previous settings with the new ones; it is
7908 not cumulative.
7909
7910 Please note that using anything other than "none" and "conn-failure" requires
7911 to allocate a buffer and copy the whole request into it, so it has memory and
7912 performance impacts. Requests not fitting in a single buffer will never be
7913 retried (see the global tune.bufsize setting).
7914
7915 You have to make sure the application has a replay protection mechanism built
7916 in such as a unique transaction IDs passed in requests, or that replaying the
7917 same request has no consequence, or it is very dangerous to use any retry-on
7918 value beside "conn-failure" and "none". Static file servers and caches are
7919 generally considered safe against any type of retry. Using a status code can
7920 be useful to quickly leave a server showing an abnormal behavior (out of
7921 memory, file system issues, etc), but in this case it may be a good idea to
7922 immediately redispatch the connection to another server (please see "option
7923 redispatch" for this). Last, it is important to understand that most causes
7924 of failures are the requests themselves and that retrying a request causing a
7925 server to misbehave will often make the situation even worse for this server,
7926 or for the whole service in case of redispatch.
7927
7928 Unless you know exactly how the application deals with replayed requests, you
7929 should not use this directive.
7930
7931 The default is "conn-failure".
7932
7933 See also: "retries", "option redispatch", "tune.bufsize"
7934
David du Colombier486df472011-03-17 10:40:26 +01007935server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007936 Declare a server in a backend
7937 May be used in sections : defaults | frontend | listen | backend
7938 no | no | yes | yes
7939 Arguments :
7940 <name> is the internal name assigned to this server. This name will
Davor Ocelice9ed2812017-12-25 17:49:28 +01007941 appear in logs and alerts. If "http-send-name-header" is
Mark Lamourinec2247f02012-01-04 13:02:01 -05007942 set, it will be added to the request header sent to the server.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007943
David du Colombier486df472011-03-17 10:40:26 +01007944 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
7945 resolvable hostname is supported, but this name will be resolved
7946 during start-up. Address "0.0.0.0" or "*" has a special meaning.
7947 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +02007948 address as the one from the client connection. This is useful in
7949 transparent proxy architectures where the client's connection is
7950 intercepted and haproxy must forward to the original destination
7951 address. This is more or less what the "transparent" keyword does
7952 except that with a server it's possible to limit concurrency and
Willy Tarreau24709282013-03-10 21:32:12 +01007953 to report statistics. Optionally, an address family prefix may be
7954 used before the address to force the family regardless of the
7955 address format, which can be useful to specify a path to a unix
7956 socket with no slash ('/'). Currently supported prefixes are :
7957 - 'ipv4@' -> address is always IPv4
7958 - 'ipv6@' -> address is always IPv6
7959 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +02007960 - 'abns@' -> address is in abstract namespace (Linux only)
William Lallemand2fe7dd02018-09-11 16:51:29 +02007961 - 'sockpair@' -> address is the FD of a connected unix
7962 socket or of a socketpair. During a connection, the
7963 backend creates a pair of connected sockets, and passes
7964 one of them over the FD. The bind part will use the
7965 received socket as the client FD. Should be used
7966 carefully.
William Lallemandb2f07452015-05-12 14:27:13 +02007967 You may want to reference some environment variables in the
7968 address parameter, see section 2.3 about environment
Willy Tarreau6a031d12016-11-07 19:42:35 +01007969 variables. The "init-addr" setting can be used to modify the way
7970 IP addresses should be resolved upon startup.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007971
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007972 <port> is an optional port specification. If set, all connections will
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007973 be sent to this port. If unset, the same port the client
7974 connected to will be used. The port may also be prefixed by a "+"
7975 or a "-". In this case, the server's port will be determined by
7976 adding this value to the client's port.
7977
7978 <param*> is a list of parameters for this server. The "server" keywords
7979 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007980 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007981
7982 Examples :
7983 server first 10.1.1.1:1080 cookie first check inter 1000
7984 server second 10.1.1.2:1080 cookie second check inter 1000
Willy Tarreau24709282013-03-10 21:32:12 +01007985 server transp ipv4@
William Lallemandb2f07452015-05-12 14:27:13 +02007986 server backup "${SRV_BACKUP}:1080" backup
7987 server www1_dc1 "${LAN_DC1}.101:80"
7988 server www1_dc2 "${LAN_DC2}.101:80"
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007989
Willy Tarreau55dcaf62015-09-27 15:03:15 +02007990 Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
7991 sun_path length is used for the address length. Some other programs
7992 such as socat use the string length only by default. Pass the option
7993 ",unix-tightsocklen=0" to any abstract socket definition in socat to
7994 make it compatible with HAProxy's.
7995
Mark Lamourinec2247f02012-01-04 13:02:01 -05007996 See also: "default-server", "http-send-name-header" and section 5 about
7997 server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007998
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007999server-state-file-name [<file>]
8000 Set the server state file to read, load and apply to servers available in
8001 this backend. It only applies when the directive "load-server-state-from-file"
8002 is set to "local". When <file> is not provided or if this directive is not
8003 set, then backend name is used. If <file> starts with a slash '/', then it is
8004 considered as an absolute path. Otherwise, <file> is concatenated to the
8005 global directive "server-state-file-base".
8006
8007 Example: the minimal configuration below would make HAProxy look for the
8008 state server file '/etc/haproxy/states/bk':
8009
8010 global
8011 server-state-file-base /etc/haproxy/states
8012
8013 backend bk
8014 load-server-state-from-file
8015
8016 See also: "server-state-file-base", "load-server-state-from-file", and
8017 "show servers state"
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008018
Frédéric Lécaillecb4502e2017-04-20 13:36:25 +02008019server-template <prefix> <num | range> <fqdn>[:<port>] [params*]
8020 Set a template to initialize servers with shared parameters.
8021 The names of these servers are built from <prefix> and <num | range> parameters.
8022 May be used in sections : defaults | frontend | listen | backend
8023 no | no | yes | yes
8024
8025 Arguments:
8026 <prefix> A prefix for the server names to be built.
8027
8028 <num | range>
8029 If <num> is provided, this template initializes <num> servers
8030 with 1 up to <num> as server name suffixes. A range of numbers
8031 <num_low>-<num_high> may also be used to use <num_low> up to
8032 <num_high> as server name suffixes.
8033
8034 <fqdn> A FQDN for all the servers this template initializes.
8035
8036 <port> Same meaning as "server" <port> argument (see "server" keyword).
8037
8038 <params*>
8039 Remaining server parameters among all those supported by "server"
8040 keyword.
8041
8042 Examples:
8043 # Initializes 3 servers with srv1, srv2 and srv3 as names,
8044 # google.com as FQDN, and health-check enabled.
8045 server-template srv 1-3 google.com:80 check
8046
8047 # or
8048 server-template srv 3 google.com:80 check
8049
8050 # would be equivalent to:
8051 server srv1 google.com:80 check
8052 server srv2 google.com:80 check
8053 server srv3 google.com:80 check
8054
8055
8056
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008057source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02008058source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01008059source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008060 Set the source address for outgoing connections
8061 May be used in sections : defaults | frontend | listen | backend
8062 yes | no | yes | yes
8063 Arguments :
8064 <addr> is the IPv4 address HAProxy will bind to before connecting to a
8065 server. This address is also used as a source for health checks.
Willy Tarreau24709282013-03-10 21:32:12 +01008066
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008067 The default value of 0.0.0.0 means that the system will select
Willy Tarreau24709282013-03-10 21:32:12 +01008068 the most appropriate address to reach its destination. Optionally
8069 an address family prefix may be used before the address to force
8070 the family regardless of the address format, which can be useful
8071 to specify a path to a unix socket with no slash ('/'). Currently
8072 supported prefixes are :
8073 - 'ipv4@' -> address is always IPv4
8074 - 'ipv6@' -> address is always IPv6
8075 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +02008076 - 'abns@' -> address is in abstract namespace (Linux only)
Cyril Bonté307ee1e2015-09-28 23:16:06 +02008077 You may want to reference some environment variables in the
8078 address parameter, see section 2.3 about environment variables.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008079
8080 <port> is an optional port. It is normally not needed but may be useful
8081 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02008082 the system will select a free port. Note that port ranges are not
8083 supported in the backend. If you want to force port ranges, you
8084 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008085
8086 <addr2> is the IP address to present to the server when connections are
8087 forwarded in full transparent proxy mode. This is currently only
8088 supported on some patched Linux kernels. When this address is
8089 specified, clients connecting to the server will be presented
8090 with this address, while health checks will still use the address
8091 <addr>.
8092
8093 <port2> is the optional port to present to the server when connections
8094 are forwarded in full transparent proxy mode (see <addr2> above).
8095 The default value of zero means the system will select a free
8096 port.
8097
Willy Tarreaubce70882009-09-07 11:51:47 +02008098 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
8099 This is the name of a comma-separated header list which can
8100 contain multiple IP addresses. By default, the last occurrence is
8101 used. This is designed to work with the X-Forwarded-For header
Baptiste Assmannea3e73b2013-02-02 23:47:49 +01008102 and to automatically bind to the client's IP address as seen
Willy Tarreaubce70882009-09-07 11:51:47 +02008103 by previous proxy, typically Stunnel. In order to use another
8104 occurrence from the last one, please see the <occ> parameter
8105 below. When the header (or occurrence) is not found, no binding
8106 is performed so that the proxy's default IP address is used. Also
8107 keep in mind that the header name is case insensitive, as for any
8108 HTTP header.
8109
8110 <occ> is the occurrence number of a value to be used in a multi-value
8111 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008112 in order to specify which occurrence to use for the source IP
Willy Tarreaubce70882009-09-07 11:51:47 +02008113 address. Positive values indicate a position from the first
8114 occurrence, 1 being the first one. Negative values indicate
8115 positions relative to the last one, -1 being the last one. This
8116 is helpful for situations where an X-Forwarded-For header is set
8117 at the entry point of an infrastructure and must be used several
8118 proxy layers away. When this value is not specified, -1 is
8119 assumed. Passing a zero here disables the feature.
8120
Willy Tarreaud53f96b2009-02-04 18:46:54 +01008121 <name> is an optional interface name to which to bind to for outgoing
8122 traffic. On systems supporting this features (currently, only
8123 Linux), this allows one to bind all traffic to the server to
8124 this interface even if it is not the one the system would select
8125 based on routing tables. This should be used with extreme care.
8126 Note that using this option requires root privileges.
8127
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008128 The "source" keyword is useful in complex environments where a specific
8129 address only is allowed to connect to the servers. It may be needed when a
8130 private address must be used through a public gateway for instance, and it is
8131 known that the system cannot determine the adequate source address by itself.
8132
8133 An extension which is available on certain patched Linux kernels may be used
8134 through the "usesrc" optional keyword. It makes it possible to connect to the
8135 servers with an IP address which does not belong to the system itself. This
8136 is called "full transparent proxy mode". For this to work, the destination
8137 servers have to route their traffic back to this address through the machine
8138 running HAProxy, and IP forwarding must generally be enabled on this machine.
8139
8140 In this "full transparent proxy" mode, it is possible to force a specific IP
8141 address to be presented to the servers. This is not much used in fact. A more
8142 common use is to tell HAProxy to present the client's IP address. For this,
8143 there are two methods :
8144
8145 - present the client's IP and port addresses. This is the most transparent
8146 mode, but it can cause problems when IP connection tracking is enabled on
8147 the machine, because a same connection may be seen twice with different
8148 states. However, this solution presents the huge advantage of not
8149 limiting the system to the 64k outgoing address+port couples, because all
8150 of the client ranges may be used.
8151
8152 - present only the client's IP address and select a spare port. This
8153 solution is still quite elegant but slightly less transparent (downstream
8154 firewalls logs will not match upstream's). It also presents the downside
8155 of limiting the number of concurrent connections to the usual 64k ports.
8156 However, since the upstream and downstream ports are different, local IP
8157 connection tracking on the machine will not be upset by the reuse of the
8158 same session.
8159
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008160 This option sets the default source for all servers in the backend. It may
8161 also be specified in a "defaults" section. Finer source address specification
8162 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008163 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008164
Baptiste Assmann91bd3372015-07-17 21:59:42 +02008165 In order to work, "usesrc" requires root privileges.
8166
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008167 Examples :
8168 backend private
8169 # Connect to the servers using our 192.168.1.200 source address
8170 source 192.168.1.200
8171
8172 backend transparent_ssl1
8173 # Connect to the SSL farm from the client's source address
8174 source 192.168.1.200 usesrc clientip
8175
8176 backend transparent_ssl2
8177 # Connect to the SSL farm from the client's source address and port
8178 # not recommended if IP conntrack is present on the local machine.
8179 source 192.168.1.200 usesrc client
8180
8181 backend transparent_ssl3
8182 # Connect to the SSL farm from the client's source address. It
8183 # is more conntrack-friendly.
8184 source 192.168.1.200 usesrc clientip
8185
8186 backend transparent_smtp
8187 # Connect to the SMTP farm from the client's source address/port
8188 # with Tproxy version 4.
8189 source 0.0.0.0 usesrc clientip
8190
Willy Tarreaubce70882009-09-07 11:51:47 +02008191 backend transparent_http
8192 # Connect to the servers using the client's IP as seen by previous
8193 # proxy.
8194 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
8195
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008196 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008197 the Linux kernel on www.balabit.com, the "bind" keyword.
8198
Willy Tarreau844e3c52008-01-11 16:28:18 +01008199
Cyril Bonté66c327d2010-10-12 00:14:37 +02008200stats admin { if | unless } <cond>
8201 Enable statistics admin level if/unless a condition is matched
8202 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008203 no | yes | yes | yes
Cyril Bonté66c327d2010-10-12 00:14:37 +02008204
8205 This statement enables the statistics admin level if/unless a condition is
8206 matched.
8207
8208 The admin level allows to enable/disable servers from the web interface. By
8209 default, statistics page is read-only for security reasons.
8210
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008211 Note : Consider not using this feature in multi-process mode (nbproc > 1)
8212 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01008213 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008214
Cyril Bonté23b39d92011-02-10 22:54:44 +01008215 Currently, the POST request is limited to the buffer size minus the reserved
8216 buffer space, which means that if the list of servers is too long, the
8217 request won't be processed. It is recommended to alter few servers at a
8218 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02008219
8220 Example :
8221 # statistics admin level only for localhost
8222 backend stats_localhost
8223 stats enable
8224 stats admin if LOCALHOST
8225
8226 Example :
8227 # statistics admin level always enabled because of the authentication
8228 backend stats_auth
8229 stats enable
8230 stats auth admin:AdMiN123
8231 stats admin if TRUE
8232
8233 Example :
8234 # statistics admin level depends on the authenticated user
8235 userlist stats-auth
8236 group admin users admin
8237 user admin insecure-password AdMiN123
8238 group readonly users haproxy
8239 user haproxy insecure-password haproxy
8240
8241 backend stats_auth
8242 stats enable
8243 acl AUTH http_auth(stats-auth)
8244 acl AUTH_ADMIN http_auth_group(stats-auth) admin
8245 stats http-request auth unless AUTH
8246 stats admin if AUTH_ADMIN
8247
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008248 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
8249 "bind-process", section 3.4 about userlists and section 7 about
8250 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02008251
8252
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008253stats auth <user>:<passwd>
8254 Enable statistics with authentication and grant access to an account
8255 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008256 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008257 Arguments :
8258 <user> is a user name to grant access to
8259
8260 <passwd> is the cleartext password associated to this user
8261
8262 This statement enables statistics with default settings, and restricts access
8263 to declared users only. It may be repeated as many times as necessary to
8264 allow as many users as desired. When a user tries to access the statistics
8265 without a valid account, a "401 Forbidden" response will be returned so that
8266 the browser asks the user to provide a valid user and password. The real
8267 which will be returned to the browser is configurable using "stats realm".
8268
8269 Since the authentication method is HTTP Basic Authentication, the passwords
8270 circulate in cleartext on the network. Thus, it was decided that the
8271 configuration file would also use cleartext passwords to remind the users
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02008272 that those ones should not be sensitive and not shared with any other account.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008273
8274 It is also possible to reduce the scope of the proxies which appear in the
8275 report using "stats scope".
8276
8277 Though this statement alone is enough to enable statistics reporting, it is
8278 recommended to set all other settings in order to avoid relying on default
8279 unobvious parameters.
8280
8281 Example :
8282 # public access (limited to this backend only)
8283 backend public_www
8284 server srv1 192.168.0.1:80
8285 stats enable
8286 stats hide-version
8287 stats scope .
8288 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008289 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008290 stats auth admin1:AdMiN123
8291 stats auth admin2:AdMiN321
8292
8293 # internal monitoring access (unlimited)
8294 backend private_monitoring
8295 stats enable
8296 stats uri /admin?stats
8297 stats refresh 5s
8298
8299 See also : "stats enable", "stats realm", "stats scope", "stats uri"
8300
8301
8302stats enable
8303 Enable statistics reporting with default settings
8304 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008305 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008306 Arguments : none
8307
8308 This statement enables statistics reporting with default settings defined
8309 at build time. Unless stated otherwise, these settings are used :
8310 - stats uri : /haproxy?stats
8311 - stats realm : "HAProxy Statistics"
8312 - stats auth : no authentication
8313 - stats scope : no restriction
8314
8315 Though this statement alone is enough to enable statistics reporting, it is
8316 recommended to set all other settings in order to avoid relying on default
8317 unobvious parameters.
8318
8319 Example :
8320 # public access (limited to this backend only)
8321 backend public_www
8322 server srv1 192.168.0.1:80
8323 stats enable
8324 stats hide-version
8325 stats scope .
8326 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008327 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008328 stats auth admin1:AdMiN123
8329 stats auth admin2:AdMiN321
8330
8331 # internal monitoring access (unlimited)
8332 backend private_monitoring
8333 stats enable
8334 stats uri /admin?stats
8335 stats refresh 5s
8336
8337 See also : "stats auth", "stats realm", "stats uri"
8338
8339
Willy Tarreaud63335a2010-02-26 12:56:52 +01008340stats hide-version
8341 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008342 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008343 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01008344 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008345
Willy Tarreaud63335a2010-02-26 12:56:52 +01008346 By default, the stats page reports some useful status information along with
8347 the statistics. Among them is HAProxy's version. However, it is generally
8348 considered dangerous to report precise version to anyone, as it can help them
8349 target known weaknesses with specific attacks. The "stats hide-version"
8350 statement removes the version from the statistics report. This is recommended
8351 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008352
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02008353 Though this statement alone is enough to enable statistics reporting, it is
8354 recommended to set all other settings in order to avoid relying on default
8355 unobvious parameters.
8356
Willy Tarreaud63335a2010-02-26 12:56:52 +01008357 Example :
8358 # public access (limited to this backend only)
8359 backend public_www
8360 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02008361 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01008362 stats hide-version
8363 stats scope .
8364 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008365 stats realm HAProxy\ Statistics
Willy Tarreaud63335a2010-02-26 12:56:52 +01008366 stats auth admin1:AdMiN123
8367 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008368
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008369 # internal monitoring access (unlimited)
8370 backend private_monitoring
8371 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01008372 stats uri /admin?stats
8373 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01008374
Willy Tarreaud63335a2010-02-26 12:56:52 +01008375 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008376
Willy Tarreau983e01e2010-01-11 18:42:06 +01008377
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02008378stats http-request { allow | deny | auth [realm <realm>] }
8379 [ { if | unless } <condition> ]
8380 Access control for statistics
8381
8382 May be used in sections: defaults | frontend | listen | backend
8383 no | no | yes | yes
8384
8385 As "http-request", these set of options allow to fine control access to
8386 statistics. Each option may be followed by if/unless and acl.
8387 First option with matched condition (or option without condition) is final.
8388 For "deny" a 403 error will be returned, for "allow" normal processing is
8389 performed, for "auth" a 401/407 error code is returned so the client
8390 should be asked to enter a username and password.
8391
8392 There is no fixed limit to the number of http-request statements per
8393 instance.
8394
8395 See also : "http-request", section 3.4 about userlists and section 7
8396 about ACL usage.
8397
8398
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008399stats realm <realm>
8400 Enable statistics and set authentication realm
8401 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008402 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008403 Arguments :
8404 <realm> is the name of the HTTP Basic Authentication realm reported to
8405 the browser. The browser uses it to display it in the pop-up
8406 inviting the user to enter a valid username and password.
8407
8408 The realm is read as a single word, so any spaces in it should be escaped
8409 using a backslash ('\').
8410
8411 This statement is useful only in conjunction with "stats auth" since it is
8412 only related to authentication.
8413
8414 Though this statement alone is enough to enable statistics reporting, it is
8415 recommended to set all other settings in order to avoid relying on default
8416 unobvious parameters.
8417
8418 Example :
8419 # public access (limited to this backend only)
8420 backend public_www
8421 server srv1 192.168.0.1:80
8422 stats enable
8423 stats hide-version
8424 stats scope .
8425 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008426 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008427 stats auth admin1:AdMiN123
8428 stats auth admin2:AdMiN321
8429
8430 # internal monitoring access (unlimited)
8431 backend private_monitoring
8432 stats enable
8433 stats uri /admin?stats
8434 stats refresh 5s
8435
8436 See also : "stats auth", "stats enable", "stats uri"
8437
8438
8439stats refresh <delay>
8440 Enable statistics with automatic refresh
8441 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008442 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008443 Arguments :
8444 <delay> is the suggested refresh delay, specified in seconds, which will
8445 be returned to the browser consulting the report page. While the
8446 browser is free to apply any delay, it will generally respect it
8447 and refresh the page this every seconds. The refresh interval may
8448 be specified in any other non-default time unit, by suffixing the
8449 unit after the value, as explained at the top of this document.
8450
8451 This statement is useful on monitoring displays with a permanent page
8452 reporting the load balancer's activity. When set, the HTML report page will
8453 include a link "refresh"/"stop refresh" so that the user can select whether
8454 he wants automatic refresh of the page or not.
8455
8456 Though this statement alone is enough to enable statistics reporting, it is
8457 recommended to set all other settings in order to avoid relying on default
8458 unobvious parameters.
8459
8460 Example :
8461 # public access (limited to this backend only)
8462 backend public_www
8463 server srv1 192.168.0.1:80
8464 stats enable
8465 stats hide-version
8466 stats scope .
8467 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008468 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008469 stats auth admin1:AdMiN123
8470 stats auth admin2:AdMiN321
8471
8472 # internal monitoring access (unlimited)
8473 backend private_monitoring
8474 stats enable
8475 stats uri /admin?stats
8476 stats refresh 5s
8477
8478 See also : "stats auth", "stats enable", "stats realm", "stats uri"
8479
8480
8481stats scope { <name> | "." }
8482 Enable statistics and limit access scope
8483 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008484 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008485 Arguments :
8486 <name> is the name of a listen, frontend or backend section to be
8487 reported. The special name "." (a single dot) designates the
8488 section in which the statement appears.
8489
8490 When this statement is specified, only the sections enumerated with this
8491 statement will appear in the report. All other ones will be hidden. This
8492 statement may appear as many times as needed if multiple sections need to be
8493 reported. Please note that the name checking is performed as simple string
8494 comparisons, and that it is never checked that a give section name really
8495 exists.
8496
8497 Though this statement alone is enough to enable statistics reporting, it is
8498 recommended to set all other settings in order to avoid relying on default
8499 unobvious parameters.
8500
8501 Example :
8502 # public access (limited to this backend only)
8503 backend public_www
8504 server srv1 192.168.0.1:80
8505 stats enable
8506 stats hide-version
8507 stats scope .
8508 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008509 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008510 stats auth admin1:AdMiN123
8511 stats auth admin2:AdMiN321
8512
8513 # internal monitoring access (unlimited)
8514 backend private_monitoring
8515 stats enable
8516 stats uri /admin?stats
8517 stats refresh 5s
8518
8519 See also : "stats auth", "stats enable", "stats realm", "stats uri"
8520
Willy Tarreaud63335a2010-02-26 12:56:52 +01008521
Willy Tarreauc9705a12010-07-27 20:05:50 +02008522stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01008523 Enable reporting of a description on the statistics page.
8524 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008525 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01008526
Willy Tarreauc9705a12010-07-27 20:05:50 +02008527 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01008528 description from global section is automatically used instead.
8529
8530 This statement is useful for users that offer shared services to their
8531 customers, where node or description should be different for each customer.
8532
8533 Though this statement alone is enough to enable statistics reporting, it is
8534 recommended to set all other settings in order to avoid relying on default
Davor Ocelice9ed2812017-12-25 17:49:28 +01008535 unobvious parameters. By default description is not shown.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008536
8537 Example :
8538 # internal monitoring access (unlimited)
8539 backend private_monitoring
8540 stats enable
8541 stats show-desc Master node for Europe, Asia, Africa
8542 stats uri /admin?stats
8543 stats refresh 5s
8544
8545 See also: "show-node", "stats enable", "stats uri" and "description" in
8546 global section.
8547
8548
8549stats show-legends
Willy Tarreaued2119c2014-04-24 22:10:39 +02008550 Enable reporting additional information on the statistics page
8551 May be used in sections : defaults | frontend | listen | backend
8552 yes | yes | yes | yes
8553 Arguments : none
8554
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03008555 Enable reporting additional information on the statistics page :
Willy Tarreaud63335a2010-02-26 12:56:52 +01008556 - cap: capabilities (proxy)
8557 - mode: one of tcp, http or health (proxy)
8558 - id: SNMP ID (proxy, socket, server)
8559 - IP (socket, server)
8560 - cookie (backend, server)
8561
8562 Though this statement alone is enough to enable statistics reporting, it is
8563 recommended to set all other settings in order to avoid relying on default
Davor Ocelice9ed2812017-12-25 17:49:28 +01008564 unobvious parameters. Default behavior is not to show this information.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008565
8566 See also: "stats enable", "stats uri".
8567
8568
8569stats show-node [ <name> ]
8570 Enable reporting of a host name on the statistics page.
8571 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008572 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01008573 Arguments:
8574 <name> is an optional name to be reported. If unspecified, the
8575 node name from global section is automatically used instead.
8576
8577 This statement is useful for users that offer shared services to their
8578 customers, where node or description might be different on a stats page
Davor Ocelice9ed2812017-12-25 17:49:28 +01008579 provided for each customer. Default behavior is not to show host name.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008580
8581 Though this statement alone is enough to enable statistics reporting, it is
8582 recommended to set all other settings in order to avoid relying on default
8583 unobvious parameters.
8584
8585 Example:
8586 # internal monitoring access (unlimited)
8587 backend private_monitoring
8588 stats enable
8589 stats show-node Europe-1
8590 stats uri /admin?stats
8591 stats refresh 5s
8592
8593 See also: "show-desc", "stats enable", "stats uri", and "node" in global
8594 section.
8595
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008596
8597stats uri <prefix>
8598 Enable statistics and define the URI prefix to access them
8599 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008600 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008601 Arguments :
8602 <prefix> is the prefix of any URI which will be redirected to stats. This
8603 prefix may contain a question mark ('?') to indicate part of a
8604 query string.
8605
8606 The statistics URI is intercepted on the relayed traffic, so it appears as a
8607 page within the normal application. It is strongly advised to ensure that the
8608 selected URI will never appear in the application, otherwise it will never be
8609 possible to reach it in the application.
8610
8611 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008612 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008613 It is generally a good idea to include a question mark in the URI so that
8614 intermediate proxies refrain from caching the results. Also, since any string
8615 beginning with the prefix will be accepted as a stats request, the question
8616 mark helps ensuring that no valid URI will begin with the same words.
8617
8618 It is sometimes very convenient to use "/" as the URI prefix, and put that
8619 statement in a "listen" instance of its own. That makes it easy to dedicate
8620 an address or a port to statistics only.
8621
8622 Though this statement alone is enough to enable statistics reporting, it is
8623 recommended to set all other settings in order to avoid relying on default
8624 unobvious parameters.
8625
8626 Example :
8627 # public access (limited to this backend only)
8628 backend public_www
8629 server srv1 192.168.0.1:80
8630 stats enable
8631 stats hide-version
8632 stats scope .
8633 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008634 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008635 stats auth admin1:AdMiN123
8636 stats auth admin2:AdMiN321
8637
8638 # internal monitoring access (unlimited)
8639 backend private_monitoring
8640 stats enable
8641 stats uri /admin?stats
8642 stats refresh 5s
8643
8644 See also : "stats auth", "stats enable", "stats realm"
8645
8646
Willy Tarreaud63335a2010-02-26 12:56:52 +01008647stick match <pattern> [table <table>] [{if | unless} <cond>]
8648 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008649 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +01008650 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008651
8652 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02008653 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008654 describes what elements of the incoming request or connection
Davor Ocelice9ed2812017-12-25 17:49:28 +01008655 will be analyzed in the hope to find a matching entry in a
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008656 stickiness table. This rule is mandatory.
8657
8658 <table> is an optional stickiness table name. If unspecified, the same
8659 backend's table is used. A stickiness table is declared using
8660 the "stick-table" statement.
8661
8662 <cond> is an optional matching condition. It makes it possible to match
8663 on a certain criterion only when other conditions are met (or
8664 not met). For instance, it could be used to match on a source IP
8665 address except when a request passes through a known proxy, in
8666 which case we'd match on a header containing that IP address.
8667
8668 Some protocols or applications require complex stickiness rules and cannot
8669 always simply rely on cookies nor hashing. The "stick match" statement
8670 describes a rule to extract the stickiness criterion from an incoming request
8671 or connection. See section 7 for a complete list of possible patterns and
8672 transformation rules.
8673
8674 The table has to be declared using the "stick-table" statement. It must be of
8675 a type compatible with the pattern. By default it is the one which is present
8676 in the same backend. It is possible to share a table with other backends by
8677 referencing it using the "table" keyword. If another table is referenced,
8678 the server's ID inside the backends are used. By default, all server IDs
8679 start at 1 in each backend, so the server ordering is enough. But in case of
8680 doubt, it is highly recommended to force server IDs using their "id" setting.
8681
8682 It is possible to restrict the conditions where a "stick match" statement
8683 will apply, using "if" or "unless" followed by a condition. See section 7 for
8684 ACL based conditions.
8685
8686 There is no limit on the number of "stick match" statements. The first that
8687 applies and matches will cause the request to be directed to the same server
8688 as was used for the request which created the entry. That way, multiple
8689 matches can be used as fallbacks.
8690
8691 The stick rules are checked after the persistence cookies, so they will not
8692 affect stickiness if a cookie has already been used to select a server. That
8693 way, it becomes very easy to insert cookies and match on IP addresses in
8694 order to maintain stickiness between HTTP and HTTPS.
8695
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008696 Note : Consider not using this feature in multi-process mode (nbproc > 1)
8697 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01008698 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008699
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008700 Example :
8701 # forward SMTP users to the same server they just used for POP in the
8702 # last 30 minutes
8703 backend pop
8704 mode tcp
8705 balance roundrobin
8706 stick store-request src
8707 stick-table type ip size 200k expire 30m
8708 server s1 192.168.1.1:110
8709 server s2 192.168.1.1:110
8710
8711 backend smtp
8712 mode tcp
8713 balance roundrobin
8714 stick match src table pop
8715 server s1 192.168.1.1:25
8716 server s2 192.168.1.1:25
8717
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008718 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +02008719 about ACLs and samples fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008720
8721
8722stick on <pattern> [table <table>] [{if | unless} <condition>]
8723 Define a request pattern to associate a user to a server
8724 May be used in sections : defaults | frontend | listen | backend
8725 no | no | yes | yes
8726
8727 Note : This form is exactly equivalent to "stick match" followed by
8728 "stick store-request", all with the same arguments. Please refer
8729 to both keywords for details. It is only provided as a convenience
8730 for writing more maintainable configurations.
8731
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008732 Note : Consider not using this feature in multi-process mode (nbproc > 1)
8733 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01008734 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008735
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008736 Examples :
8737 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +01008738 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008739
8740 # ...is strictly equivalent to this one :
8741 stick match src table pop if !localhost
8742 stick store-request src table pop if !localhost
8743
8744
8745 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
8746 # well as HTTP without cookie. Share the same table between both accesses.
8747 backend http
8748 mode http
8749 balance roundrobin
8750 stick on src table https
8751 cookie SRV insert indirect nocache
8752 server s1 192.168.1.1:80 cookie s1
8753 server s2 192.168.1.1:80 cookie s2
8754
8755 backend https
8756 mode tcp
8757 balance roundrobin
8758 stick-table type ip size 200k expire 30m
8759 stick on src
8760 server s1 192.168.1.1:443
8761 server s2 192.168.1.1:443
8762
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008763 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008764
8765
8766stick store-request <pattern> [table <table>] [{if | unless} <condition>]
8767 Define a request pattern used to create an entry in a stickiness table
8768 May be used in sections : defaults | frontend | listen | backend
8769 no | no | yes | yes
8770
8771 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02008772 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008773 describes what elements of the incoming request or connection
Davor Ocelice9ed2812017-12-25 17:49:28 +01008774 will be analyzed, extracted and stored in the table once a
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008775 server is selected.
8776
8777 <table> is an optional stickiness table name. If unspecified, the same
8778 backend's table is used. A stickiness table is declared using
8779 the "stick-table" statement.
8780
8781 <cond> is an optional storage condition. It makes it possible to store
8782 certain criteria only when some conditions are met (or not met).
8783 For instance, it could be used to store the source IP address
8784 except when the request passes through a known proxy, in which
8785 case we'd store a converted form of a header containing that IP
8786 address.
8787
8788 Some protocols or applications require complex stickiness rules and cannot
8789 always simply rely on cookies nor hashing. The "stick store-request" statement
8790 describes a rule to decide what to extract from the request and when to do
8791 it, in order to store it into a stickiness table for further requests to
8792 match it using the "stick match" statement. Obviously the extracted part must
8793 make sense and have a chance to be matched in a further request. Storing a
8794 client's IP address for instance often makes sense. Storing an ID found in a
8795 URL parameter also makes sense. Storing a source port will almost never make
8796 any sense because it will be randomly matched. See section 7 for a complete
8797 list of possible patterns and transformation rules.
8798
8799 The table has to be declared using the "stick-table" statement. It must be of
8800 a type compatible with the pattern. By default it is the one which is present
8801 in the same backend. It is possible to share a table with other backends by
8802 referencing it using the "table" keyword. If another table is referenced,
8803 the server's ID inside the backends are used. By default, all server IDs
8804 start at 1 in each backend, so the server ordering is enough. But in case of
8805 doubt, it is highly recommended to force server IDs using their "id" setting.
8806
8807 It is possible to restrict the conditions where a "stick store-request"
8808 statement will apply, using "if" or "unless" followed by a condition. This
8809 condition will be evaluated while parsing the request, so any criteria can be
8810 used. See section 7 for ACL based conditions.
8811
8812 There is no limit on the number of "stick store-request" statements, but
8813 there is a limit of 8 simultaneous stores per request or response. This
8814 makes it possible to store up to 8 criteria, all extracted from either the
8815 request or the response, regardless of the number of rules. Only the 8 first
8816 ones which match will be kept. Using this, it is possible to feed multiple
8817 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +01008818 another protocol or access method. Using multiple store-request rules with
8819 the same table is possible and may be used to find the best criterion to rely
8820 on, by arranging the rules by decreasing preference order. Only the first
8821 extracted criterion for a given table will be stored. All subsequent store-
8822 request rules referencing the same table will be skipped and their ACLs will
8823 not be evaluated.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008824
8825 The "store-request" rules are evaluated once the server connection has been
8826 established, so that the table will contain the real server that processed
8827 the request.
8828
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008829 Note : Consider not using this feature in multi-process mode (nbproc > 1)
8830 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01008831 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008832
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008833 Example :
8834 # forward SMTP users to the same server they just used for POP in the
8835 # last 30 minutes
8836 backend pop
8837 mode tcp
8838 balance roundrobin
8839 stick store-request src
8840 stick-table type ip size 200k expire 30m
8841 server s1 192.168.1.1:110
8842 server s2 192.168.1.1:110
8843
8844 backend smtp
8845 mode tcp
8846 balance roundrobin
8847 stick match src table pop
8848 server s1 192.168.1.1:25
8849 server s2 192.168.1.1:25
8850
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008851 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +02008852 about ACLs and sample fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008853
8854
Emeric Brun7c6b82e2010-09-24 16:34:28 +02008855stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +02008856 size <size> [expire <expire>] [nopurge] [peers <peersect>]
8857 [store <data_type>]*
Godbach64cef792013-12-04 16:08:22 +08008858 Configure the stickiness table for the current section
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008859 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +02008860 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008861
8862 Arguments :
8863 ip a table declared with "type ip" will only store IPv4 addresses.
8864 This form is very compact (about 50 bytes per entry) and allows
8865 very fast entry lookup and stores with almost no overhead. This
8866 is mainly used to store client source IP addresses.
8867
David du Colombier9a6d3c92011-03-17 10:40:24 +01008868 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
8869 This form is very compact (about 60 bytes per entry) and allows
8870 very fast entry lookup and stores with almost no overhead. This
8871 is mainly used to store client source IP addresses.
8872
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008873 integer a table declared with "type integer" will store 32bit integers
8874 which can represent a client identifier found in a request for
8875 instance.
8876
8877 string a table declared with "type string" will store substrings of up
8878 to <len> characters. If the string provided by the pattern
8879 extractor is larger than <len>, it will be truncated before
8880 being stored. During matching, at most <len> characters will be
8881 compared between the string in the table and the extracted
8882 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +02008883 to 32 characters.
8884
8885 binary a table declared with "type binary" will store binary blocks
8886 of <len> bytes. If the block provided by the pattern
8887 extractor is larger than <len>, it will be truncated before
Willy Tarreaube722a22014-06-13 16:31:59 +02008888 being stored. If the block provided by the sample expression
Emeric Brun7c6b82e2010-09-24 16:34:28 +02008889 is shorter than <len>, it will be padded by 0. When not
8890 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008891
8892 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +02008893 "string" type table (See type "string" above). Or the number
8894 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008895 changing this parameter as memory usage will proportionally
8896 increase.
8897
8898 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +01008899 value directly impacts memory usage. Count approximately
8900 50 bytes per entry, plus the size of a string if any. The size
8901 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008902
8903 [nopurge] indicates that we refuse to purge older entries when the table
8904 is full. When not specified and the table is full when haproxy
8905 wants to store an entry in it, it will flush a few of the oldest
8906 entries in order to release some space for the new ones. This is
Davor Ocelice9ed2812017-12-25 17:49:28 +01008907 most often the desired behavior. In some specific cases, it
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008908 be desirable to refuse new entries instead of purging the older
8909 ones. That may be the case when the amount of data to store is
8910 far above the hardware limits and we prefer not to offer access
8911 to new clients than to reject the ones already connected. When
8912 using this parameter, be sure to properly set the "expire"
8913 parameter (see below).
8914
Emeric Brunf099e792010-09-27 12:05:28 +02008915 <peersect> is the name of the peers section to use for replication. Entries
8916 which associate keys to server IDs are kept synchronized with
8917 the remote peers declared in this section. All entries are also
8918 automatically learned from the local peer (old process) during a
8919 soft restart.
8920
Willy Tarreau1abc6732015-05-01 19:21:02 +02008921 NOTE : each peers section may be referenced only by tables
8922 belonging to the same unique process.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008923
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008924 <expire> defines the maximum duration of an entry in the table since it
8925 was last created, refreshed or matched. The expiration delay is
8926 defined using the standard time format, similarly as the various
8927 timeouts. The maximum duration is slightly above 24 days. See
Jarno Huuskonene0ee0be2017-07-04 10:35:12 +03008928 section 2.4 for more information. If this delay is not specified,
Cyril Bontédc4d9032012-04-08 21:57:39 +02008929 the session won't automatically expire, but older entries will
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008930 be removed once full. Be sure not to use the "nopurge" parameter
8931 if not expiration delay is specified.
8932
Willy Tarreau08d5f982010-06-06 13:34:54 +02008933 <data_type> is used to store additional information in the stick-table. This
8934 may be used by ACLs in order to control various criteria related
8935 to the activity of the client matching the stick-table. For each
8936 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +02008937 that the additional data can fit. Several data types may be
8938 stored with an entry. Multiple data types may be specified after
8939 the "store" keyword, as a comma-separated list. Alternatively,
8940 it is possible to repeat the "store" keyword followed by one or
8941 several data types. Except for the "server_id" type which is
8942 automatically detected and enabled, all data types must be
8943 explicitly declared to be stored. If an ACL references a data
8944 type which is not stored, the ACL will simply not match. Some
8945 data types require an argument which must be passed just after
8946 the type between parenthesis. See below for the supported data
8947 types and their arguments.
8948
8949 The data types that can be stored with an entry are the following :
8950 - server_id : this is an integer which holds the numeric ID of the server a
8951 request was assigned to. It is used by the "stick match", "stick store",
8952 and "stick on" rules. It is automatically enabled when referenced.
8953
8954 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
8955 integer which may be used for anything. Most of the time it will be used
8956 to put a special tag on some entries, for instance to note that a
Davor Ocelice9ed2812017-12-25 17:49:28 +01008957 specific behavior was detected and must be known for future matches.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008958
Willy Tarreauba2ffd12013-05-29 15:54:14 +02008959 - gpc0_rate(<period>) : increment rate of the first General Purpose Counter
8960 over a period. It is a positive 32-bit integer integer which may be used
8961 for anything. Just like <gpc0>, it counts events, but instead of keeping
Davor Ocelice9ed2812017-12-25 17:49:28 +01008962 a cumulative number, it maintains the rate at which the counter is
Willy Tarreauba2ffd12013-05-29 15:54:14 +02008963 incremented. Most of the time it will be used to measure the frequency of
Davor Ocelice9ed2812017-12-25 17:49:28 +01008964 occurrence of certain events (e.g. requests to a specific URL).
Willy Tarreauba2ffd12013-05-29 15:54:14 +02008965
Frédéric Lécaille6778b272018-01-29 15:22:53 +01008966 - gpc1 : second General Purpose Counter. It is a positive 32-bit integer
8967 integer which may be used for anything. Most of the time it will be used
8968 to put a special tag on some entries, for instance to note that a
8969 specific behavior was detected and must be known for future matches.
8970
8971 - gpc1_rate(<period>) : increment rate of the second General Purpose Counter
8972 over a period. It is a positive 32-bit integer integer which may be used
8973 for anything. Just like <gpc1>, it counts events, but instead of keeping
8974 a cumulative number, it maintains the rate at which the counter is
8975 incremented. Most of the time it will be used to measure the frequency of
8976 occurrence of certain events (e.g. requests to a specific URL).
8977
Willy Tarreauc9705a12010-07-27 20:05:50 +02008978 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
8979 the absolute number of connections received from clients which matched
8980 this entry. It does not mean the connections were accepted, just that
8981 they were received.
8982
8983 - conn_cur : Current Connections. It is a positive 32-bit integer which
8984 stores the concurrent connection counts for the entry. It is incremented
8985 once an incoming connection matches the entry, and decremented once the
8986 connection leaves. That way it is possible to know at any time the exact
8987 number of concurrent connections for an entry.
8988
8989 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
8990 integer parameter <period> which indicates in milliseconds the length
8991 of the period over which the average is measured. It reports the average
8992 incoming connection rate over that period, in connections per period. The
8993 result is an integer which can be matched using ACLs.
8994
8995 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
8996 the absolute number of sessions received from clients which matched this
8997 entry. A session is a connection that was accepted by the layer 4 rules.
8998
8999 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
9000 integer parameter <period> which indicates in milliseconds the length
9001 of the period over which the average is measured. It reports the average
9002 incoming session rate over that period, in sessions per period. The
9003 result is an integer which can be matched using ACLs.
9004
9005 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
9006 counts the absolute number of HTTP requests received from clients which
9007 matched this entry. It does not matter whether they are valid requests or
9008 not. Note that this is different from sessions when keep-alive is used on
9009 the client side.
9010
9011 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
9012 integer parameter <period> which indicates in milliseconds the length
9013 of the period over which the average is measured. It reports the average
9014 HTTP request rate over that period, in requests per period. The result is
9015 an integer which can be matched using ACLs. It does not matter whether
9016 they are valid requests or not. Note that this is different from sessions
9017 when keep-alive is used on the client side.
9018
9019 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
9020 counts the absolute number of HTTP requests errors induced by clients
9021 which matched this entry. Errors are counted on invalid and truncated
9022 requests, as well as on denied or tarpitted requests, and on failed
9023 authentications. If the server responds with 4xx, then the request is
9024 also counted as an error since it's an error triggered by the client
Davor Ocelice9ed2812017-12-25 17:49:28 +01009025 (e.g. vulnerability scan).
Willy Tarreauc9705a12010-07-27 20:05:50 +02009026
9027 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
9028 integer parameter <period> which indicates in milliseconds the length
9029 of the period over which the average is measured. It reports the average
9030 HTTP request error rate over that period, in requests per period (see
9031 http_err_cnt above for what is accounted as an error). The result is an
9032 integer which can be matched using ACLs.
9033
9034 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
Davor Ocelice9ed2812017-12-25 17:49:28 +01009035 integer which counts the cumulative number of bytes received from clients
Willy Tarreauc9705a12010-07-27 20:05:50 +02009036 which matched this entry. Headers are included in the count. This may be
9037 used to limit abuse of upload features on photo or video servers.
9038
9039 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
9040 integer parameter <period> which indicates in milliseconds the length
9041 of the period over which the average is measured. It reports the average
9042 incoming bytes rate over that period, in bytes per period. It may be used
9043 to detect users which upload too much and too fast. Warning: with large
9044 uploads, it is possible that the amount of uploaded data will be counted
9045 once upon termination, thus causing spikes in the average transfer speed
9046 instead of having a smooth one. This may partially be smoothed with
9047 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
9048 recommended for better fairness.
9049
9050 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
Davor Ocelice9ed2812017-12-25 17:49:28 +01009051 integer which counts the cumulative number of bytes sent to clients which
Willy Tarreauc9705a12010-07-27 20:05:50 +02009052 matched this entry. Headers are included in the count. This may be used
9053 to limit abuse of bots sucking the whole site.
9054
9055 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
9056 an integer parameter <period> which indicates in milliseconds the length
9057 of the period over which the average is measured. It reports the average
9058 outgoing bytes rate over that period, in bytes per period. It may be used
9059 to detect users which download too much and too fast. Warning: with large
9060 transfers, it is possible that the amount of transferred data will be
9061 counted once upon termination, thus causing spikes in the average
9062 transfer speed instead of having a smooth one. This may partially be
9063 smoothed with "option contstats" though this is not perfect yet. Use of
9064 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +02009065
Willy Tarreauc00cdc22010-06-06 16:48:26 +02009066 There is only one stick-table per proxy. At the moment of writing this doc,
9067 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009068 to be required, simply create a dummy backend with a stick-table in it and
9069 reference it.
9070
9071 It is important to understand that stickiness based on learning information
9072 has some limitations, including the fact that all learned associations are
Baptiste Assmann123ff042016-03-06 23:29:28 +01009073 lost upon restart unless peers are properly configured to transfer such
9074 information upon restart (recommended). In general it can be good as a
9075 complement but not always as an exclusive stickiness.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009076
Willy Tarreauc9705a12010-07-27 20:05:50 +02009077 Last, memory requirements may be important when storing many data types.
9078 Indeed, storing all indicators above at once in each entry requires 116 bytes
9079 per entry, or 116 MB for a 1-million entries table. This is definitely not
9080 something that can be ignored.
9081
9082 Example:
9083 # Keep track of counters of up to 1 million IP addresses over 5 minutes
9084 # and store a general purpose counter and the average connection rate
9085 # computed over a sliding window of 30 seconds.
9086 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
9087
Jarno Huuskonene0ee0be2017-07-04 10:35:12 +03009088 See also : "stick match", "stick on", "stick store-request", section 2.4
David du Colombiera13d1b92011-03-17 10:40:22 +01009089 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009090
9091
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009092stick store-response <pattern> [table <table>] [{if | unless} <condition>]
Baptiste Assmann2f2d2ec2016-03-06 23:27:24 +01009093 Define a response pattern used to create an entry in a stickiness table
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009094 May be used in sections : defaults | frontend | listen | backend
9095 no | no | yes | yes
9096
9097 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02009098 <pattern> is a sample expression rule as described in section 7.3. It
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009099 describes what elements of the response or connection will
Davor Ocelice9ed2812017-12-25 17:49:28 +01009100 be analyzed, extracted and stored in the table once a
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009101 server is selected.
9102
9103 <table> is an optional stickiness table name. If unspecified, the same
9104 backend's table is used. A stickiness table is declared using
9105 the "stick-table" statement.
9106
9107 <cond> is an optional storage condition. It makes it possible to store
9108 certain criteria only when some conditions are met (or not met).
9109 For instance, it could be used to store the SSL session ID only
9110 when the response is a SSL server hello.
9111
9112 Some protocols or applications require complex stickiness rules and cannot
9113 always simply rely on cookies nor hashing. The "stick store-response"
9114 statement describes a rule to decide what to extract from the response and
9115 when to do it, in order to store it into a stickiness table for further
9116 requests to match it using the "stick match" statement. Obviously the
9117 extracted part must make sense and have a chance to be matched in a further
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009118 request. Storing an ID found in a header of a response makes sense.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009119 See section 7 for a complete list of possible patterns and transformation
9120 rules.
9121
9122 The table has to be declared using the "stick-table" statement. It must be of
9123 a type compatible with the pattern. By default it is the one which is present
9124 in the same backend. It is possible to share a table with other backends by
9125 referencing it using the "table" keyword. If another table is referenced,
9126 the server's ID inside the backends are used. By default, all server IDs
9127 start at 1 in each backend, so the server ordering is enough. But in case of
9128 doubt, it is highly recommended to force server IDs using their "id" setting.
9129
9130 It is possible to restrict the conditions where a "stick store-response"
9131 statement will apply, using "if" or "unless" followed by a condition. This
9132 condition will be evaluated while parsing the response, so any criteria can
9133 be used. See section 7 for ACL based conditions.
9134
9135 There is no limit on the number of "stick store-response" statements, but
9136 there is a limit of 8 simultaneous stores per request or response. This
9137 makes it possible to store up to 8 criteria, all extracted from either the
9138 request or the response, regardless of the number of rules. Only the 8 first
9139 ones which match will be kept. Using this, it is possible to feed multiple
9140 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +01009141 another protocol or access method. Using multiple store-response rules with
9142 the same table is possible and may be used to find the best criterion to rely
9143 on, by arranging the rules by decreasing preference order. Only the first
9144 extracted criterion for a given table will be stored. All subsequent store-
9145 response rules referencing the same table will be skipped and their ACLs will
9146 not be evaluated. However, even if a store-request rule references a table, a
9147 store-response rule may also use the same table. This means that each table
9148 may learn exactly one element from the request and one element from the
9149 response at once.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009150
9151 The table will contain the real server that processed the request.
9152
9153 Example :
9154 # Learn SSL session ID from both request and response and create affinity.
9155 backend https
9156 mode tcp
9157 balance roundrobin
Cyril Bontédc4d9032012-04-08 21:57:39 +02009158 # maximum SSL session ID length is 32 bytes.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009159 stick-table type binary len 32 size 30k expire 30m
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009160
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009161 acl clienthello req_ssl_hello_type 1
9162 acl serverhello rep_ssl_hello_type 2
9163
9164 # use tcp content accepts to detects ssl client and server hello.
9165 tcp-request inspect-delay 5s
9166 tcp-request content accept if clienthello
9167
9168 # no timeout on response inspect delay by default.
9169 tcp-response content accept if serverhello
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009170
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009171 # SSL session ID (SSLID) may be present on a client or server hello.
9172 # Its length is coded on 1 byte at offset 43 and its value starts
9173 # at offset 44.
9174
9175 # Match and learn on request if client hello.
9176 stick on payload_lv(43,1) if clienthello
9177
9178 # Learn on response if server hello.
9179 stick store-response payload_lv(43,1) if serverhello
Cyril Bontédc4d9032012-04-08 21:57:39 +02009180
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009181 server s1 192.168.1.1:443
9182 server s2 192.168.1.1:443
9183
9184 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
9185 extraction.
9186
9187
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009188tcp-check connect [params*]
9189 Opens a new connection
9190 May be used in sections: defaults | frontend | listen | backend
9191 no | no | yes | yes
9192
9193 When an application lies on more than a single TCP port or when HAProxy
9194 load-balance many services in a single backend, it makes sense to probe all
9195 the services individually before considering a server as operational.
9196
9197 When there are no TCP port configured on the server line neither server port
9198 directive, then the 'tcp-check connect port <port>' must be the first step
9199 of the sequence.
9200
9201 In a tcp-check ruleset a 'connect' is required, it is also mandatory to start
9202 the ruleset with a 'connect' rule. Purpose is to ensure admin know what they
9203 do.
9204
9205 Parameters :
9206 They are optional and can be used to describe how HAProxy should open and
9207 use the TCP connection.
9208
9209 port if not set, check port or server port is used.
9210 It tells HAProxy where to open the connection to.
9211 <port> must be a valid TCP port source integer, from 1 to 65535.
9212
9213 send-proxy send a PROXY protocol string
9214
9215 ssl opens a ciphered connection
9216
9217 Examples:
9218 # check HTTP and HTTPs services on a server.
9219 # first open port 80 thanks to server line port directive, then
9220 # tcp-check opens port 443, ciphered and run a request on it:
9221 option tcp-check
9222 tcp-check connect
9223 tcp-check send GET\ /\ HTTP/1.0\r\n
9224 tcp-check send Host:\ haproxy.1wt.eu\r\n
9225 tcp-check send \r\n
9226 tcp-check expect rstring (2..|3..)
9227 tcp-check connect port 443 ssl
9228 tcp-check send GET\ /\ HTTP/1.0\r\n
9229 tcp-check send Host:\ haproxy.1wt.eu\r\n
9230 tcp-check send \r\n
9231 tcp-check expect rstring (2..|3..)
9232 server www 10.0.0.1 check port 80
9233
9234 # check both POP and IMAP from a single server:
9235 option tcp-check
9236 tcp-check connect port 110
9237 tcp-check expect string +OK\ POP3\ ready
9238 tcp-check connect port 143
9239 tcp-check expect string *\ OK\ IMAP4\ ready
9240 server mail 10.0.0.1 check
9241
9242 See also : "option tcp-check", "tcp-check send", "tcp-check expect"
9243
9244
9245tcp-check expect [!] <match> <pattern>
Davor Ocelice9ed2812017-12-25 17:49:28 +01009246 Specify data to be collected and analyzed during a generic health check
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009247 May be used in sections: defaults | frontend | listen | backend
9248 no | no | yes | yes
9249
9250 Arguments :
9251 <match> is a keyword indicating how to look for a specific pattern in the
9252 response. The keyword may be one of "string", "rstring" or
9253 binary.
9254 The keyword may be preceded by an exclamation mark ("!") to negate
9255 the match. Spaces are allowed between the exclamation mark and the
9256 keyword. See below for more details on the supported keywords.
9257
9258 <pattern> is the pattern to look for. It may be a string or a regular
9259 expression. If the pattern contains spaces, they must be escaped
9260 with the usual backslash ('\').
9261 If the match is set to binary, then the pattern must be passed as
Davor Ocelice9ed2812017-12-25 17:49:28 +01009262 a series of hexadecimal digits in an even number. Each sequence of
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009263 two digits will represent a byte. The hexadecimal digits may be
9264 used upper or lower case.
9265
9266
9267 The available matches are intentionally similar to their http-check cousins :
9268
9269 string <string> : test the exact string matches in the response buffer.
9270 A health check response will be considered valid if the
9271 response's buffer contains this exact string. If the
9272 "string" keyword is prefixed with "!", then the response
9273 will be considered invalid if the body contains this
9274 string. This can be used to look for a mandatory pattern
9275 in a protocol response, or to detect a failure when a
9276 specific error appears in a protocol banner.
9277
9278 rstring <regex> : test a regular expression on the response buffer.
9279 A health check response will be considered valid if the
9280 response's buffer matches this expression. If the
9281 "rstring" keyword is prefixed with "!", then the response
9282 will be considered invalid if the body matches the
9283 expression.
9284
9285 binary <hexstring> : test the exact string in its hexadecimal form matches
9286 in the response buffer. A health check response will
9287 be considered valid if the response's buffer contains
9288 this exact hexadecimal string.
9289 Purpose is to match data on binary protocols.
9290
9291 It is important to note that the responses will be limited to a certain size
9292 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
9293 Thus, too large responses may not contain the mandatory pattern when using
9294 "string", "rstring" or binary. If a large response is absolutely required, it
9295 is possible to change the default max size by setting the global variable.
9296 However, it is worth keeping in mind that parsing very large responses can
9297 waste some CPU cycles, especially when regular expressions are used, and that
9298 it is always better to focus the checks on smaller resources. Also, in its
9299 current state, the check will not find any string nor regex past a null
9300 character in the response. Similarly it is not possible to request matching
9301 the null character.
9302
9303 Examples :
9304 # perform a POP check
9305 option tcp-check
9306 tcp-check expect string +OK\ POP3\ ready
9307
9308 # perform an IMAP check
9309 option tcp-check
9310 tcp-check expect string *\ OK\ IMAP4\ ready
9311
9312 # look for the redis master server
9313 option tcp-check
9314 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +02009315 tcp-check expect string +PONG
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009316 tcp-check send info\ replication\r\n
9317 tcp-check expect string role:master
9318 tcp-check send QUIT\r\n
9319 tcp-check expect string +OK
9320
9321
9322 See also : "option tcp-check", "tcp-check connect", "tcp-check send",
9323 "tcp-check send-binary", "http-check expect", tune.chksize
9324
9325
9326tcp-check send <data>
9327 Specify a string to be sent as a question during a generic health check
9328 May be used in sections: defaults | frontend | listen | backend
9329 no | no | yes | yes
9330
9331 <data> : the data to be sent as a question during a generic health check
9332 session. For now, <data> must be a string.
9333
9334 Examples :
9335 # look for the redis master server
9336 option tcp-check
9337 tcp-check send info\ replication\r\n
9338 tcp-check expect string role:master
9339
9340 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
9341 "tcp-check send-binary", tune.chksize
9342
9343
Davor Ocelice9ed2812017-12-25 17:49:28 +01009344tcp-check send-binary <hexstring>
9345 Specify a hex digits string to be sent as a binary question during a raw
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009346 tcp health check
9347 May be used in sections: defaults | frontend | listen | backend
9348 no | no | yes | yes
9349
9350 <data> : the data to be sent as a question during a generic health check
9351 session. For now, <data> must be a string.
Davor Ocelice9ed2812017-12-25 17:49:28 +01009352 <hexstring> : test the exact string in its hexadecimal form matches in the
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009353 response buffer. A health check response will be considered
9354 valid if the response's buffer contains this exact
9355 hexadecimal string.
9356 Purpose is to send binary data to ask on binary protocols.
9357
9358 Examples :
9359 # redis check in binary
9360 option tcp-check
9361 tcp-check send-binary 50494e470d0a # PING\r\n
9362 tcp-check expect binary 2b504F4e47 # +PONG
9363
9364
9365 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
9366 "tcp-check send", tune.chksize
9367
9368
Willy Tarreaue9656522010-08-17 15:40:09 +02009369tcp-request connection <action> [{if | unless} <condition>]
9370 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +02009371 May be used in sections : defaults | frontend | listen | backend
9372 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +02009373 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +02009374 <action> defines the action to perform if the condition applies. See
9375 below.
Willy Tarreau1a687942010-05-23 22:40:30 +02009376
Willy Tarreaue9656522010-08-17 15:40:09 +02009377 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009378
9379 Immediately after acceptance of a new incoming connection, it is possible to
9380 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +02009381 or dropped or have its counters tracked. Those conditions cannot make use of
9382 any data contents because the connection has not been read from yet, and the
9383 buffers are not yet allocated. This is used to selectively and very quickly
9384 accept or drop connections from various sources with a very low overhead. If
9385 some contents need to be inspected in order to take the decision, the
9386 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009387
Willy Tarreaue9656522010-08-17 15:40:09 +02009388 The "tcp-request connection" rules are evaluated in their exact declaration
9389 order. If no rule matches or if there is no rule, the default action is to
9390 accept the incoming connection. There is no specific limit to the number of
9391 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009392
Willy Tarreaua9083d02015-05-08 15:27:59 +02009393 Four types of actions are supported :
Willy Tarreaue9656522010-08-17 15:40:09 +02009394 - accept :
9395 accepts the connection if the condition is true (when used with "if")
9396 or false (when used with "unless"). The first such rule executed ends
9397 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009398
Willy Tarreaue9656522010-08-17 15:40:09 +02009399 - reject :
9400 rejects the connection if the condition is true (when used with "if")
9401 or false (when used with "unless"). The first such rule executed ends
9402 the rules evaluation. Rejected connections do not even become a
9403 session, which is why they are accounted separately for in the stats,
9404 as "denied connections". They are not considered for the session
9405 rate-limit and are not logged either. The reason is that these rules
9406 should only be used to filter extremely high connection rates such as
9407 the ones encountered during a massive DDoS attack. Under these extreme
9408 conditions, the simple action of logging each event would make the
9409 system collapse and would considerably lower the filtering capacity. If
9410 logging is absolutely desired, then "tcp-request content" rules should
Willy Tarreau4f614292016-10-21 17:49:36 +02009411 be used instead, as "tcp-request session" rules will not log either.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009412
Willy Tarreau4f0d9192013-06-11 20:40:55 +02009413 - expect-proxy layer4 :
9414 configures the client-facing connection to receive a PROXY protocol
9415 header before any byte is read from the socket. This is equivalent to
9416 having the "accept-proxy" keyword on the "bind" line, except that using
9417 the TCP rule allows the PROXY protocol to be accepted only for certain
9418 IP address ranges using an ACL. This is convenient when multiple layers
9419 of load balancers are passed through by traffic coming from public
9420 hosts.
9421
Bertrand Jacquin90759682016-06-06 15:35:39 +01009422 - expect-netscaler-cip layer4 :
9423 configures the client-facing connection to receive a NetScaler Client
9424 IP insertion protocol header before any byte is read from the socket.
9425 This is equivalent to having the "accept-netscaler-cip" keyword on the
9426 "bind" line, except that using the TCP rule allows the PROXY protocol
9427 to be accepted only for certain IP address ranges using an ACL. This
9428 is convenient when multiple layers of load balancers are passed
9429 through by traffic coming from public hosts.
9430
Willy Tarreau18bf01e2014-06-13 16:18:52 +02009431 - capture <sample> len <length> :
9432 This only applies to "tcp-request content" rules. It captures sample
9433 expression <sample> from the request buffer, and converts it to a
9434 string of at most <len> characters. The resulting string is stored into
9435 the next request "capture" slot, so it will possibly appear next to
9436 some captured HTTP headers. It will then automatically appear in the
9437 logs, and it will be possible to extract it using sample fetch rules to
9438 feed it into headers or anything. The length should be limited given
9439 that this size will be allocated for each capture during the whole
Willy Tarreaua9083d02015-05-08 15:27:59 +02009440 session life. Please check section 7.3 (Fetching samples) and "capture
9441 request header" for more information.
Willy Tarreau18bf01e2014-06-13 16:18:52 +02009442
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009443 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] :
Willy Tarreaue9656522010-08-17 15:40:09 +02009444 enables tracking of sticky counters from current connection. These
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +02009445 rules do not stop evaluation and do not change default action. The
9446 number of counters that may be simultaneously tracked by the same
9447 connection is set in MAX_SESS_STKCTR at build time (reported in
John Roeslerfb2fce12019-07-10 15:45:51 -05009448 haproxy -vv) which defaults to 3, so the track-sc number is between 0
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +02009449 and (MAX_SESS_STCKTR-1). The first "track-sc0" rule executed enables
9450 tracking of the counters of the specified table as the first set. The
9451 first "track-sc1" rule executed enables tracking of the counters of the
9452 specified table as the second set. The first "track-sc2" rule executed
9453 enables tracking of the counters of the specified table as the third
9454 set. It is a recommended practice to use the first set of counters for
9455 the per-frontend counters and the second set for the per-backend ones.
9456 But this is just a guideline, all may be used everywhere.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009457
Willy Tarreaue9656522010-08-17 15:40:09 +02009458 These actions take one or two arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02009459 <key> is mandatory, and is a sample expression rule as described
Willy Tarreau74ca5042013-06-11 23:12:07 +02009460 in section 7.3. It describes what elements of the incoming
Davor Ocelice9ed2812017-12-25 17:49:28 +01009461 request or connection will be analyzed, extracted, combined,
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009462 and used to select which table entry to update the counters.
9463 Note that "tcp-request connection" cannot use content-based
9464 fetches.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009465
Willy Tarreaue9656522010-08-17 15:40:09 +02009466 <table> is an optional table to be used instead of the default one,
9467 which is the stick-table declared in the current proxy. All
9468 the counters for the matches and updates for the key will
9469 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009470
Willy Tarreaue9656522010-08-17 15:40:09 +02009471 Once a "track-sc*" rule is executed, the key is looked up in the table
9472 and if it is not found, an entry is allocated for it. Then a pointer to
9473 that entry is kept during all the session's life, and this entry's
9474 counters are updated as often as possible, every time the session's
9475 counters are updated, and also systematically when the session ends.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009476 Counters are only updated for events that happen after the tracking has
9477 been started. For example, connection counters will not be updated when
9478 tracking layer 7 information, since the connection event happens before
9479 layer7 information is extracted.
9480
Willy Tarreaue9656522010-08-17 15:40:09 +02009481 If the entry tracks concurrent connection counters, one connection is
9482 counted for as long as the entry is tracked, and the entry will not
9483 expire during that time. Tracking counters also provides a performance
9484 advantage over just checking the keys, because only one table lookup is
9485 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009486
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02009487 - sc-inc-gpc0(<sc-id>):
9488 The "sc-inc-gpc0" increments the GPC0 counter according to the sticky
9489 counter designated by <sc-id>. If an error occurs, this action silently
9490 fails and the actions evaluation continues.
9491
Frédéric Lécaille6778b272018-01-29 15:22:53 +01009492 - sc-inc-gpc1(<sc-id>):
9493 The "sc-inc-gpc1" increments the GPC1 counter according to the sticky
9494 counter designated by <sc-id>. If an error occurs, this action silently
9495 fails and the actions evaluation continues.
9496
Cédric Dufour0d7712d2019-11-06 18:38:53 +01009497 - sc-set-gpt0(<sc-id>) { <int> | <expr> }:
9498 This action sets the 32-bit unsigned GPT0 tag according to the sticky
9499 counter designated by <sc-id> and the value of <int>/<expr>. The
9500 expected result is a boolean. If an error occurs, this action silently
9501 fails and the actions evaluation continues.
Thierry FOURNIER236657b2015-08-19 08:25:14 +02009502
William Lallemand2e785f22016-05-25 01:48:42 +02009503 - set-src <expr> :
9504 Is used to set the source IP address to the value of specified
9505 expression. Useful if you want to mask source IP for privacy.
9506 If you want to provide an IP from a HTTP header use "http-request
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02009507 set-src".
William Lallemand2e785f22016-05-25 01:48:42 +02009508
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02009509 Arguments:
9510 <expr> Is a standard HAProxy expression formed by a sample-fetch
9511 followed by some converters.
William Lallemand2e785f22016-05-25 01:48:42 +02009512
9513 Example:
William Lallemand2e785f22016-05-25 01:48:42 +02009514 tcp-request connection set-src src,ipmask(24)
9515
Willy Tarreau0c630532016-10-21 17:52:58 +02009516 When possible, set-src preserves the original source port as long as the
9517 address family allows it, otherwise the source port is set to 0.
William Lallemand2e785f22016-05-25 01:48:42 +02009518
William Lallemand44be6402016-05-25 01:51:35 +02009519 - set-src-port <expr> :
9520 Is used to set the source port address to the value of specified
9521 expression.
9522
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02009523 Arguments:
9524 <expr> Is a standard HAProxy expression formed by a sample-fetch
9525 followed by some converters.
William Lallemand44be6402016-05-25 01:51:35 +02009526
9527 Example:
William Lallemand44be6402016-05-25 01:51:35 +02009528 tcp-request connection set-src-port int(4000)
9529
Willy Tarreau0c630532016-10-21 17:52:58 +02009530 When possible, set-src-port preserves the original source address as long
9531 as the address family supports a port, otherwise it forces the source
9532 address to IPv4 "0.0.0.0" before rewriting the port.
William Lallemand44be6402016-05-25 01:51:35 +02009533
William Lallemand13e9b0c2016-05-25 02:34:07 +02009534 - set-dst <expr> :
9535 Is used to set the destination IP address to the value of specified
9536 expression. Useful if you want to mask IP for privacy in log.
9537 If you want to provide an IP from a HTTP header use "http-request
9538 set-dst". If you want to connect to the new address/port, use
9539 '0.0.0.0:0' as a server address in the backend.
9540
9541 <expr> Is a standard HAProxy expression formed by a sample-fetch
9542 followed by some converters.
9543
9544 Example:
9545
9546 tcp-request connection set-dst dst,ipmask(24)
9547 tcp-request connection set-dst ipv4(10.0.0.1)
9548
Willy Tarreau0c630532016-10-21 17:52:58 +02009549 When possible, set-dst preserves the original destination port as long as
9550 the address family allows it, otherwise the destination port is set to 0.
9551
William Lallemand13e9b0c2016-05-25 02:34:07 +02009552 - set-dst-port <expr> :
9553 Is used to set the destination port address to the value of specified
9554 expression. If you want to connect to the new address/port, use
9555 '0.0.0.0:0' as a server address in the backend.
9556
9557
9558 <expr> Is a standard HAProxy expression formed by a sample-fetch
9559 followed by some converters.
9560
9561 Example:
9562
9563 tcp-request connection set-dst-port int(4000)
9564
Willy Tarreau0c630532016-10-21 17:52:58 +02009565 When possible, set-dst-port preserves the original destination address as
9566 long as the address family supports a port, otherwise it forces the
9567 destination address to IPv4 "0.0.0.0" before rewriting the port.
9568
Willy Tarreau2d392c22015-08-24 01:43:45 +02009569 - "silent-drop" :
9570 This stops the evaluation of the rules and makes the client-facing
Davor Ocelice9ed2812017-12-25 17:49:28 +01009571 connection suddenly disappear using a system-dependent way that tries
Willy Tarreau2d392c22015-08-24 01:43:45 +02009572 to prevent the client from being notified. The effect it then that the
9573 client still sees an established connection while there's none on
9574 HAProxy. The purpose is to achieve a comparable effect to "tarpit"
9575 except that it doesn't use any local resource at all on the machine
9576 running HAProxy. It can resist much higher loads than "tarpit", and
Davor Ocelice9ed2812017-12-25 17:49:28 +01009577 slow down stronger attackers. It is important to understand the impact
9578 of using this mechanism. All stateful equipment placed between the
Willy Tarreau2d392c22015-08-24 01:43:45 +02009579 client and HAProxy (firewalls, proxies, load balancers) will also keep
9580 the established connection for a long time and may suffer from this
Davor Ocelice9ed2812017-12-25 17:49:28 +01009581 action. On modern Linux systems running with enough privileges, the
Willy Tarreau2d392c22015-08-24 01:43:45 +02009582 TCP_REPAIR socket option is used to block the emission of a TCP
9583 reset. On other systems, the socket's TTL is reduced to 1 so that the
9584 TCP reset doesn't pass the first router, though it's still delivered to
9585 local networks. Do not use it unless you fully understand how it works.
9586
Willy Tarreaue9656522010-08-17 15:40:09 +02009587 Note that the "if/unless" condition is optional. If no condition is set on
9588 the action, it is simply performed unconditionally. That can be useful for
9589 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009590
Willy Tarreaue9656522010-08-17 15:40:09 +02009591 Example: accept all connections from white-listed hosts, reject too fast
9592 connection without counting them, and track accepted connections.
9593 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009594
Willy Tarreaue9656522010-08-17 15:40:09 +02009595 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009596 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009597 tcp-request connection track-sc0 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009598
Willy Tarreaue9656522010-08-17 15:40:09 +02009599 Example: accept all connections from white-listed hosts, count all other
9600 connections and reject too fast ones. This results in abusive ones
9601 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009602
Willy Tarreaue9656522010-08-17 15:40:09 +02009603 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009604 tcp-request connection track-sc0 src
9605 tcp-request connection reject if { sc0_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009606
Willy Tarreau4f0d9192013-06-11 20:40:55 +02009607 Example: enable the PROXY protocol for traffic coming from all known proxies.
9608
9609 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
9610
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009611 See section 7 about ACL usage.
9612
Willy Tarreau4f614292016-10-21 17:49:36 +02009613 See also : "tcp-request session", "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009614
9615
Willy Tarreaue9656522010-08-17 15:40:09 +02009616tcp-request content <action> [{if | unless} <condition>]
9617 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +02009618 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02009619 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +02009620 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +02009621 <action> defines the action to perform if the condition applies. See
9622 below.
Willy Tarreau62644772008-07-16 18:36:06 +02009623
Willy Tarreaue9656522010-08-17 15:40:09 +02009624 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +02009625
Davor Ocelice9ed2812017-12-25 17:49:28 +01009626 A request's contents can be analyzed at an early stage of request processing
Willy Tarreaue9656522010-08-17 15:40:09 +02009627 called "TCP content inspection". During this stage, ACL-based rules are
9628 evaluated every time the request contents are updated, until either an
9629 "accept" or a "reject" rule matches, or the TCP request inspection delay
9630 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +02009631
Willy Tarreaue9656522010-08-17 15:40:09 +02009632 The first difference between these rules and "tcp-request connection" rules
9633 is that "tcp-request content" rules can make use of contents to take a
9634 decision. Most often, these decisions will consider a protocol recognition or
9635 validity. The second difference is that content-based rules can be used in
Willy Tarreauf3338342014-01-28 21:40:28 +01009636 both frontends and backends. In case of HTTP keep-alive with the client, all
9637 tcp-request content rules are evaluated again, so haproxy keeps a record of
9638 what sticky counters were assigned by a "tcp-request connection" versus a
9639 "tcp-request content" rule, and flushes all the content-related ones after
9640 processing an HTTP request, so that they may be evaluated again by the rules
9641 being evaluated again for the next request. This is of particular importance
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009642 when the rule tracks some L7 information or when it is conditioned by an
Willy Tarreauf3338342014-01-28 21:40:28 +01009643 L7-based ACL, since tracking may change between requests.
Willy Tarreau62644772008-07-16 18:36:06 +02009644
Willy Tarreaue9656522010-08-17 15:40:09 +02009645 Content-based rules are evaluated in their exact declaration order. If no
9646 rule matches or if there is no rule, the default action is to accept the
9647 contents. There is no specific limit to the number of rules which may be
9648 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +02009649
Thierry FOURNIER236657b2015-08-19 08:25:14 +02009650 Several types of actions are supported :
Willy Tarreau18bf01e2014-06-13 16:18:52 +02009651 - accept : the request is accepted
Baptiste Assmann333939c2019-01-21 08:34:50 +01009652 - do-resolve: perform a DNS resolution
Willy Tarreau18bf01e2014-06-13 16:18:52 +02009653 - reject : the request is rejected and the connection is closed
9654 - capture : the specified sample expression is captured
Patrick Hemmer268a7072018-05-11 12:52:31 -04009655 - set-priority-class <expr> | set-priority-offset <expr>
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009656 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02009657 - sc-inc-gpc0(<sc-id>)
Frédéric Lécaille6778b272018-01-29 15:22:53 +01009658 - sc-inc-gpc1(<sc-id>)
Cédric Dufour0d7712d2019-11-06 18:38:53 +01009659 - sc-set-gpt0(<sc-id>) { <int> | <expr> }
Baptiste Assmanne1afd4f2019-04-18 16:21:13 +02009660 - set-dst <expr>
9661 - set-dst-port <expr>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009662 - set-var(<var-name>) <expr>
Christopher Faulet85d79c92016-11-09 16:54:56 +01009663 - unset-var(<var-name>)
Willy Tarreau2d392c22015-08-24 01:43:45 +02009664 - silent-drop
Davor Ocelice9ed2812017-12-25 17:49:28 +01009665 - send-spoe-group <engine-name> <group-name>
Christopher Faulet579d83b2019-11-22 15:34:17 +01009666 - use-service <service-name>
Willy Tarreau62644772008-07-16 18:36:06 +02009667
Willy Tarreaue9656522010-08-17 15:40:09 +02009668 They have the same meaning as their counter-parts in "tcp-request connection"
9669 so please refer to that section for a complete description.
Baptiste Assmann333939c2019-01-21 08:34:50 +01009670 For "do-resolve" action, please check the "http-request do-resolve"
9671 configuration section.
Willy Tarreau62644772008-07-16 18:36:06 +02009672
Willy Tarreauf3338342014-01-28 21:40:28 +01009673 While there is nothing mandatory about it, it is recommended to use the
9674 track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request
9675 content" rules in the frontend, and track-sc2 for "tcp-request content"
9676 rules in the backend, because that makes the configuration more readable
9677 and easier to troubleshoot, but this is just a guideline and all counters
9678 may be used everywhere.
Willy Tarreau62644772008-07-16 18:36:06 +02009679
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009680 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +02009681 the action, it is simply performed unconditionally. That can be useful for
9682 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +02009683
Willy Tarreaue9656522010-08-17 15:40:09 +02009684 It is perfectly possible to match layer 7 contents with "tcp-request content"
Willy Tarreauc0239e02012-04-16 14:42:55 +02009685 rules, since HTTP-specific ACL matches are able to preliminarily parse the
9686 contents of a buffer before extracting the required data. If the buffered
9687 contents do not parse as a valid HTTP message, then the ACL does not match.
9688 The parser which is involved there is exactly the same as for all other HTTP
Willy Tarreauf3338342014-01-28 21:40:28 +01009689 processing, so there is no risk of parsing something differently. In an HTTP
9690 backend connected to from an HTTP frontend, it is guaranteed that HTTP
9691 contents will always be immediately present when the rule is evaluated first.
Willy Tarreau62644772008-07-16 18:36:06 +02009692
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009693 Tracking layer7 information is also possible provided that the information
Willy Tarreau4d54c7c2014-09-16 15:48:15 +02009694 are present when the rule is processed. The rule processing engine is able to
9695 wait until the inspect delay expires when the data to be tracked is not yet
9696 available.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009697
Baptiste Assmanne1afd4f2019-04-18 16:21:13 +02009698 The "set-dst" and "set-dst-port" are used to set respectively the destination
9699 IP and port. More information on how to use it at "http-request set-dst".
9700
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009701 The "set-var" is used to set the content of a variable. The variable is
Willy Tarreau4f614292016-10-21 17:49:36 +02009702 declared inline. For "tcp-request session" rules, only session-level
9703 variables can be used, without any layer7 contents.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009704
Daniel Schneller0b547052016-03-21 20:46:57 +01009705 <var-name> The name of the variable starts with an indication about
9706 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +01009707 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +01009708 "sess" : the variable is shared with the whole session
9709 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009710 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +01009711 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009712 processing
Daniel Schneller0b547052016-03-21 20:46:57 +01009713 "res" : the variable is shared only during response
9714 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009715 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +01009716 The name may only contain characters 'a-z', 'A-Z', '0-9',
9717 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009718
9719 <expr> Is a standard HAProxy expression formed by a sample-fetch
9720 followed by some converters.
9721
Christopher Faulet85d79c92016-11-09 16:54:56 +01009722 The "unset-var" is used to unset a variable. See above for details about
9723 <var-name>.
9724
Patrick Hemmer268a7072018-05-11 12:52:31 -04009725 The "set-priority-class" is used to set the queue priority class of the
9726 current request. The value must be a sample expression which converts to an
9727 integer in the range -2047..2047. Results outside this range will be
9728 truncated. The priority class determines the order in which queued requests
9729 are processed. Lower values have higher priority.
9730
9731 The "set-priority-offset" is used to set the queue priority timestamp offset
9732 of the current request. The value must be a sample expression which converts
9733 to an integer in the range -524287..524287. Results outside this range will be
9734 truncated. When a request is queued, it is ordered first by the priority
9735 class, then by the current timestamp adjusted by the given offset in
9736 milliseconds. Lower values have higher priority.
9737 Note that the resulting timestamp is is only tracked with enough precision for
9738 524,287ms (8m44s287ms). If the request is queued long enough to where the
9739 adjusted timestamp exceeds this value, it will be misidentified as highest
9740 priority. Thus it is important to set "timeout queue" to a value, where when
9741 combined with the offset, does not exceed this limit.
9742
Christopher Faulet76c09ef2017-09-21 11:03:52 +02009743 The "send-spoe-group" is used to trigger sending of a group of SPOE
9744 messages. To do so, the SPOE engine used to send messages must be defined, as
9745 well as the SPOE group to send. Of course, the SPOE engine must refer to an
9746 existing SPOE filter. If not engine name is provided on the SPOE filter line,
9747 the SPOE agent name must be used.
9748
9749 <engine-name> The SPOE engine name.
9750
9751 <group-name> The SPOE group name as specified in the engine configuration.
9752
Christopher Faulet579d83b2019-11-22 15:34:17 +01009753 The "use-service" is used to executes a TCP service which will reply to the
9754 request and stop the evaluation of the rules. This service may choose to
9755 reply by sending any valid response or it may immediately close the
9756 connection without sending anything. Outside natives services, it is possible
9757 to write your own services in Lua. No further "tcp-request" rules are
9758 evaluated.
9759
9760 Example:
9761 tcp-request content use-service lua.deny { src -f /etc/haproxy/blacklist.lst }
9762
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009763 Example:
9764
9765 tcp-request content set-var(sess.my_var) src
Christopher Faulet85d79c92016-11-09 16:54:56 +01009766 tcp-request content unset-var(sess.my_var2)
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009767
Willy Tarreau62644772008-07-16 18:36:06 +02009768 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +02009769 # Accept HTTP requests containing a Host header saying "example.com"
9770 # and reject everything else.
9771 acl is_host_com hdr(Host) -i example.com
9772 tcp-request inspect-delay 30s
Willy Tarreauc0239e02012-04-16 14:42:55 +02009773 tcp-request content accept if is_host_com
Willy Tarreaue9656522010-08-17 15:40:09 +02009774 tcp-request content reject
9775
9776 Example:
Willy Tarreau62644772008-07-16 18:36:06 +02009777 # reject SMTP connection if client speaks first
9778 tcp-request inspect-delay 30s
9779 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009780 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +02009781
9782 # Forward HTTPS connection only if client speaks
9783 tcp-request inspect-delay 30s
9784 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009785 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +02009786 tcp-request content reject
9787
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009788 Example:
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009789 # Track the last IP(stick-table type string) from X-Forwarded-For
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009790 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +02009791 tcp-request content track-sc0 hdr(x-forwarded-for,-1)
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009792 # Or track the last IP(stick-table type ip|ipv6) from X-Forwarded-For
9793 tcp-request content track-sc0 req.hdr_ip(x-forwarded-for,-1)
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009794
9795 Example:
9796 # track request counts per "base" (concatenation of Host+URL)
9797 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +02009798 tcp-request content track-sc0 base table req-rate
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009799
Willy Tarreaue9656522010-08-17 15:40:09 +02009800 Example: track per-frontend and per-backend counters, block abusers at the
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009801 frontend when the backend detects abuse(and marks gpc0).
Willy Tarreaue9656522010-08-17 15:40:09 +02009802
9803 frontend http
Davor Ocelice9ed2812017-12-25 17:49:28 +01009804 # Use General Purpose Counter 0 in SC0 as a global abuse counter
Willy Tarreaue9656522010-08-17 15:40:09 +02009805 # protecting all our sites
9806 stick-table type ip size 1m expire 5m store gpc0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009807 tcp-request connection track-sc0 src
9808 tcp-request connection reject if { sc0_get_gpc0 gt 0 }
Willy Tarreaue9656522010-08-17 15:40:09 +02009809 ...
9810 use_backend http_dynamic if { path_end .php }
9811
9812 backend http_dynamic
9813 # if a source makes too fast requests to this dynamic site (tracked
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009814 # by SC1), block it globally in the frontend.
Willy Tarreaue9656522010-08-17 15:40:09 +02009815 stick-table type ip size 1m expire 5m store http_req_rate(10s)
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009816 acl click_too_fast sc1_http_req_rate gt 10
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009817 acl mark_as_abuser sc0_inc_gpc0(http) gt 0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009818 tcp-request content track-sc1 src
Willy Tarreaue9656522010-08-17 15:40:09 +02009819 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +02009820
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009821 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02009822
Jarno Huuskonen95b012b2017-04-06 13:59:14 +03009823 See also : "tcp-request connection", "tcp-request session",
9824 "tcp-request inspect-delay", and "http-request".
Willy Tarreau62644772008-07-16 18:36:06 +02009825
9826
9827tcp-request inspect-delay <timeout>
9828 Set the maximum allowed time to wait for data during content inspection
9829 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02009830 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +02009831 Arguments :
9832 <timeout> is the timeout value specified in milliseconds by default, but
9833 can be in any other unit if the number is suffixed by the unit,
9834 as explained at the top of this document.
9835
9836 People using haproxy primarily as a TCP relay are often worried about the
9837 risk of passing any type of protocol to a server without any analysis. In
9838 order to be able to analyze the request contents, we must first withhold
9839 the data then analyze them. This statement simply enables withholding of
9840 data for at most the specified amount of time.
9841
Willy Tarreaufb356202010-08-03 14:02:05 +02009842 TCP content inspection applies very early when a connection reaches a
9843 frontend, then very early when the connection is forwarded to a backend. This
9844 means that a connection may experience a first delay in the frontend and a
9845 second delay in the backend if both have tcp-request rules.
9846
Willy Tarreau62644772008-07-16 18:36:06 +02009847 Note that when performing content inspection, haproxy will evaluate the whole
9848 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009849 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +02009850 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +01009851 contents are definitive. If no delay is set, haproxy will not wait at all
9852 and will immediately apply a verdict based on the available information.
9853 Obviously this is unlikely to be very useful and might even be racy, so such
9854 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +02009855
9856 As soon as a rule matches, the request is released and continues as usual. If
9857 the timeout is reached and no rule matches, the default policy will be to let
9858 it pass through unaffected.
9859
9860 For most protocols, it is enough to set it to a few seconds, as most clients
9861 send the full request immediately upon connection. Add 3 or more seconds to
9862 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +01009863 to use large values, for instance to ensure that the client never talks
Davor Ocelice9ed2812017-12-25 17:49:28 +01009864 before the server (e.g. SMTP), or to wait for a client to talk before passing
9865 data to the server (e.g. SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +02009866 least the inspection delay, otherwise it will expire first. If the client
9867 closes the connection or if the buffer is full, the delay immediately expires
9868 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +02009869
Willy Tarreau55165fe2009-05-10 12:02:55 +02009870 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +02009871 "timeout client".
9872
9873
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009874tcp-response content <action> [{if | unless} <condition>]
9875 Perform an action on a session response depending on a layer 4-7 condition
9876 May be used in sections : defaults | frontend | listen | backend
9877 no | no | yes | yes
9878 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +02009879 <action> defines the action to perform if the condition applies. See
9880 below.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009881
9882 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
9883
Davor Ocelice9ed2812017-12-25 17:49:28 +01009884 Response contents can be analyzed at an early stage of response processing
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009885 called "TCP content inspection". During this stage, ACL-based rules are
9886 evaluated every time the response contents are updated, until either an
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02009887 "accept", "close" or a "reject" rule matches, or a TCP response inspection
9888 delay is set and expires with no matching rule.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009889
9890 Most often, these decisions will consider a protocol recognition or validity.
9891
9892 Content-based rules are evaluated in their exact declaration order. If no
9893 rule matches or if there is no rule, the default action is to accept the
9894 contents. There is no specific limit to the number of rules which may be
9895 inserted.
9896
Thierry FOURNIER236657b2015-08-19 08:25:14 +02009897 Several types of actions are supported :
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009898 - accept :
9899 accepts the response if the condition is true (when used with "if")
9900 or false (when used with "unless"). The first such rule executed ends
9901 the rules evaluation.
9902
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02009903 - close :
9904 immediately closes the connection with the server if the condition is
9905 true (when used with "if"), or false (when used with "unless"). The
9906 first such rule executed ends the rules evaluation. The main purpose of
9907 this action is to force a connection to be finished between a client
9908 and a server after an exchange when the application protocol expects
9909 some long time outs to elapse first. The goal is to eliminate idle
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009910 connections which take significant resources on servers with certain
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02009911 protocols.
9912
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009913 - reject :
9914 rejects the response if the condition is true (when used with "if")
9915 or false (when used with "unless"). The first such rule executed ends
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009916 the rules evaluation. Rejected session are immediately closed.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009917
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009918 - set-var(<var-name>) <expr>
9919 Sets a variable.
9920
Christopher Faulet85d79c92016-11-09 16:54:56 +01009921 - unset-var(<var-name>)
9922 Unsets a variable.
9923
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02009924 - sc-inc-gpc0(<sc-id>):
9925 This action increments the GPC0 counter according to the sticky
9926 counter designated by <sc-id>. If an error occurs, this action fails
9927 silently and the actions evaluation continues.
9928
Frédéric Lécaille6778b272018-01-29 15:22:53 +01009929 - sc-inc-gpc1(<sc-id>):
9930 This action increments the GPC1 counter according to the sticky
9931 counter designated by <sc-id>. If an error occurs, this action fails
9932 silently and the actions evaluation continues.
9933
Cédric Dufour0d7712d2019-11-06 18:38:53 +01009934 - sc-set-gpt0(<sc-id>) { <int> | <expr> }
9935 This action sets the 32-bit unsigned GPT0 tag according to the sticky
9936 counter designated by <sc-id> and the value of <int>/<expr>. The
9937 expected result is a boolean. If an error occurs, this action silently
9938 fails and the actions evaluation continues.
Thierry FOURNIER236657b2015-08-19 08:25:14 +02009939
Willy Tarreau2d392c22015-08-24 01:43:45 +02009940 - "silent-drop" :
9941 This stops the evaluation of the rules and makes the client-facing
Davor Ocelice9ed2812017-12-25 17:49:28 +01009942 connection suddenly disappear using a system-dependent way that tries
Willy Tarreau2d392c22015-08-24 01:43:45 +02009943 to prevent the client from being notified. The effect it then that the
9944 client still sees an established connection while there's none on
9945 HAProxy. The purpose is to achieve a comparable effect to "tarpit"
9946 except that it doesn't use any local resource at all on the machine
9947 running HAProxy. It can resist much higher loads than "tarpit", and
Davor Ocelice9ed2812017-12-25 17:49:28 +01009948 slow down stronger attackers. It is important to understand the impact
9949 of using this mechanism. All stateful equipment placed between the
Willy Tarreau2d392c22015-08-24 01:43:45 +02009950 client and HAProxy (firewalls, proxies, load balancers) will also keep
9951 the established connection for a long time and may suffer from this
Davor Ocelice9ed2812017-12-25 17:49:28 +01009952 action. On modern Linux systems running with enough privileges, the
Willy Tarreau2d392c22015-08-24 01:43:45 +02009953 TCP_REPAIR socket option is used to block the emission of a TCP
9954 reset. On other systems, the socket's TTL is reduced to 1 so that the
9955 TCP reset doesn't pass the first router, though it's still delivered to
9956 local networks. Do not use it unless you fully understand how it works.
9957
Christopher Faulet76c09ef2017-09-21 11:03:52 +02009958 - send-spoe-group <engine-name> <group-name>
9959 Send a group of SPOE messages.
9960
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009961 Note that the "if/unless" condition is optional. If no condition is set on
9962 the action, it is simply performed unconditionally. That can be useful for
9963 for changing the default action to a reject.
9964
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009965 It is perfectly possible to match layer 7 contents with "tcp-response
9966 content" rules, but then it is important to ensure that a full response has
9967 been buffered, otherwise no contents will match. In order to achieve this,
9968 the best solution involves detecting the HTTP protocol during the inspection
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009969 period.
9970
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009971 The "set-var" is used to set the content of a variable. The variable is
9972 declared inline.
9973
Daniel Schneller0b547052016-03-21 20:46:57 +01009974 <var-name> The name of the variable starts with an indication about
9975 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +01009976 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +01009977 "sess" : the variable is shared with the whole session
9978 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009979 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +01009980 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009981 processing
Daniel Schneller0b547052016-03-21 20:46:57 +01009982 "res" : the variable is shared only during response
9983 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009984 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +01009985 The name may only contain characters 'a-z', 'A-Z', '0-9',
9986 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009987
9988 <expr> Is a standard HAProxy expression formed by a sample-fetch
9989 followed by some converters.
9990
9991 Example:
9992
9993 tcp-request content set-var(sess.my_var) src
9994
Christopher Faulet85d79c92016-11-09 16:54:56 +01009995 The "unset-var" is used to unset a variable. See above for details about
9996 <var-name>.
9997
9998 Example:
9999
10000 tcp-request content unset-var(sess.my_var)
10001
Christopher Faulet76c09ef2017-09-21 11:03:52 +020010002 The "send-spoe-group" is used to trigger sending of a group of SPOE
10003 messages. To do so, the SPOE engine used to send messages must be defined, as
10004 well as the SPOE group to send. Of course, the SPOE engine must refer to an
10005 existing SPOE filter. If not engine name is provided on the SPOE filter line,
10006 the SPOE agent name must be used.
10007
10008 <engine-name> The SPOE engine name.
10009
10010 <group-name> The SPOE group name as specified in the engine configuration.
10011
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010012 See section 7 about ACL usage.
10013
10014 See also : "tcp-request content", "tcp-response inspect-delay"
10015
10016
Willy Tarreau4f614292016-10-21 17:49:36 +020010017tcp-request session <action> [{if | unless} <condition>]
10018 Perform an action on a validated session depending on a layer 5 condition
10019 May be used in sections : defaults | frontend | listen | backend
10020 no | yes | yes | no
10021 Arguments :
10022 <action> defines the action to perform if the condition applies. See
10023 below.
10024
10025 <condition> is a standard layer5-only ACL-based condition (see section 7).
10026
Davor Ocelice9ed2812017-12-25 17:49:28 +010010027 Once a session is validated, (i.e. after all handshakes have been completed),
Willy Tarreau4f614292016-10-21 17:49:36 +020010028 it is possible to evaluate some conditions to decide whether this session
10029 must be accepted or dropped or have its counters tracked. Those conditions
10030 cannot make use of any data contents because no buffers are allocated yet and
10031 the processing cannot wait at this stage. The main use case it to copy some
10032 early information into variables (since variables are accessible in the
10033 session), or to keep track of some information collected after the handshake,
10034 such as SSL-level elements (SNI, ciphers, client cert's CN) or information
Davor Ocelice9ed2812017-12-25 17:49:28 +010010035 from the PROXY protocol header (e.g. track a source forwarded this way). The
Willy Tarreau4f614292016-10-21 17:49:36 +020010036 extracted information can thus be copied to a variable or tracked using
10037 "track-sc" rules. Of course it is also possible to decide to accept/reject as
10038 with other rulesets. Most operations performed here could also be performed
10039 in "tcp-request content" rules, except that in HTTP these rules are evaluated
10040 for each new request, and that might not always be acceptable. For example a
10041 rule might increment a counter on each evaluation. It would also be possible
10042 that a country is resolved by geolocation from the source IP address,
10043 assigned to a session-wide variable, then the source address rewritten from
10044 an HTTP header for all requests. If some contents need to be inspected in
10045 order to take the decision, the "tcp-request content" statements must be used
10046 instead.
10047
10048 The "tcp-request session" rules are evaluated in their exact declaration
10049 order. If no rule matches or if there is no rule, the default action is to
10050 accept the incoming session. There is no specific limit to the number of
10051 rules which may be inserted.
10052
10053 Several types of actions are supported :
10054 - accept : the request is accepted
10055 - reject : the request is rejected and the connection is closed
10056 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
10057 - sc-inc-gpc0(<sc-id>)
Frédéric Lécaille6778b272018-01-29 15:22:53 +010010058 - sc-inc-gpc1(<sc-id>)
Cédric Dufour0d7712d2019-11-06 18:38:53 +010010059 - sc-set-gpt0(<sc-id>) { <int> | <expr> }
Willy Tarreau4f614292016-10-21 17:49:36 +020010060 - set-var(<var-name>) <expr>
Christopher Faulet85d79c92016-11-09 16:54:56 +010010061 - unset-var(<var-name>)
Willy Tarreau4f614292016-10-21 17:49:36 +020010062 - silent-drop
10063
10064 These actions have the same meaning as their respective counter-parts in
10065 "tcp-request connection" and "tcp-request content", so please refer to these
10066 sections for a complete description.
10067
10068 Note that the "if/unless" condition is optional. If no condition is set on
10069 the action, it is simply performed unconditionally. That can be useful for
10070 "track-sc*" actions as well as for changing the default action to a reject.
10071
10072 Example: track the original source address by default, or the one advertised
10073 in the PROXY protocol header for connection coming from the local
10074 proxies. The first connection-level rule enables receipt of the
10075 PROXY protocol for these ones, the second rule tracks whatever
10076 address we decide to keep after optional decoding.
10077
10078 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
10079 tcp-request session track-sc0 src
10080
10081 Example: accept all sessions from white-listed hosts, reject too fast
10082 sessions without counting them, and track accepted sessions.
10083 This results in session rate being capped from abusive sources.
10084
10085 tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
10086 tcp-request session reject if { src_sess_rate gt 10 }
10087 tcp-request session track-sc0 src
10088
10089 Example: accept all sessions from white-listed hosts, count all other
10090 sessions and reject too fast ones. This results in abusive ones
10091 being blocked as long as they don't slow down.
10092
10093 tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
10094 tcp-request session track-sc0 src
10095 tcp-request session reject if { sc0_sess_rate gt 10 }
10096
10097 See section 7 about ACL usage.
10098
10099 See also : "tcp-request connection", "tcp-request content", "stick-table"
10100
10101
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010102tcp-response inspect-delay <timeout>
10103 Set the maximum allowed time to wait for a response during content inspection
10104 May be used in sections : defaults | frontend | listen | backend
10105 no | no | yes | yes
10106 Arguments :
10107 <timeout> is the timeout value specified in milliseconds by default, but
10108 can be in any other unit if the number is suffixed by the unit,
10109 as explained at the top of this document.
10110
10111 See also : "tcp-response content", "tcp-request inspect-delay".
10112
10113
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010114timeout check <timeout>
10115 Set additional check timeout, but only after a connection has been already
10116 established.
10117
10118 May be used in sections: defaults | frontend | listen | backend
10119 yes | no | yes | yes
10120 Arguments:
10121 <timeout> is the timeout value specified in milliseconds by default, but
10122 can be in any other unit if the number is suffixed by the unit,
10123 as explained at the top of this document.
10124
10125 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
10126 for check and "timeout check" as an additional read timeout. The "min" is
Davor Ocelice9ed2812017-12-25 17:49:28 +010010127 used so that people running with *very* long "timeout connect" (e.g. those
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010128 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +010010129 (Please also note that there is no valid reason to have such long connect
10130 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
10131 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010132
10133 If "timeout check" is not set haproxy uses "inter" for complete check
10134 timeout (connect + read) exactly like all <1.3.15 version.
10135
10136 In most cases check request is much simpler and faster to handle than normal
10137 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +010010138 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010139
10140 This parameter is specific to backends, but can be specified once for all in
10141 "defaults" sections. This is in fact one of the easiest solutions not to
10142 forget about it.
10143
Willy Tarreau41a340d2008-01-22 12:25:31 +010010144 See also: "timeout connect", "timeout queue", "timeout server",
10145 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010146
10147
Willy Tarreau0ba27502007-12-24 16:55:16 +010010148timeout client <timeout>
Willy Tarreau0ba27502007-12-24 16:55:16 +010010149 Set the maximum inactivity time on the client side.
10150 May be used in sections : defaults | frontend | listen | backend
10151 yes | yes | yes | no
10152 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010010153 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +010010154 can be in any other unit if the number is suffixed by the unit,
10155 as explained at the top of this document.
10156
10157 The inactivity timeout applies when the client is expected to acknowledge or
10158 send data. In HTTP mode, this timeout is particularly important to consider
10159 during the first phase, when the client sends the request, and during the
Baptiste Assmann2e1941e2016-03-06 23:24:12 +010010160 response while it is reading data sent by the server. That said, for the
10161 first phase, it is preferable to set the "timeout http-request" to better
10162 protect HAProxy from Slowloris like attacks. The value is specified in
10163 milliseconds by default, but can be in any other unit if the number is
Willy Tarreau0ba27502007-12-24 16:55:16 +010010164 suffixed by the unit, as specified at the top of this document. In TCP mode
10165 (and to a lesser extent, in HTTP mode), it is highly recommended that the
10166 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010010167 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +010010168 losses by specifying timeouts that are slightly above multiples of 3 seconds
Davor Ocelice9ed2812017-12-25 17:49:28 +010010169 (e.g. 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
10170 sessions (e.g. WebSocket and HTTP), it's worth considering "timeout tunnel",
Willy Tarreau05cdd962014-05-10 14:30:07 +020010171 which overrides "timeout client" and "timeout server" for tunnels, as well as
10172 "timeout client-fin" for half-closed connections.
Willy Tarreau0ba27502007-12-24 16:55:16 +010010173
10174 This parameter is specific to frontends, but can be specified once for all in
10175 "defaults" sections. This is in fact one of the easiest solutions not to
10176 forget about it. An unspecified timeout results in an infinite timeout, which
10177 is not recommended. Such a usage is accepted and works but reports a warning
John Roeslerfb2fce12019-07-10 15:45:51 -050010178 during startup because it may result in accumulation of expired sessions in
Willy Tarreau0ba27502007-12-24 16:55:16 +010010179 the system if the system's timeouts are not configured either.
10180
Willy Tarreau95c4e142017-11-26 12:18:55 +010010181 This also applies to HTTP/2 connections, which will be closed with GOAWAY.
Lukas Tribus75df9d72017-11-24 19:05:12 +010010182
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020010183 See also : "timeout server", "timeout tunnel", "timeout http-request".
Willy Tarreau0ba27502007-12-24 16:55:16 +010010184
Willy Tarreau0ba27502007-12-24 16:55:16 +010010185
Willy Tarreau05cdd962014-05-10 14:30:07 +020010186timeout client-fin <timeout>
10187 Set the inactivity timeout on the client side for half-closed connections.
10188 May be used in sections : defaults | frontend | listen | backend
10189 yes | yes | yes | no
10190 Arguments :
10191 <timeout> is the timeout value specified in milliseconds by default, but
10192 can be in any other unit if the number is suffixed by the unit,
10193 as explained at the top of this document.
10194
10195 The inactivity timeout applies when the client is expected to acknowledge or
10196 send data while one direction is already shut down. This timeout is different
10197 from "timeout client" in that it only applies to connections which are closed
10198 in one direction. This is particularly useful to avoid keeping connections in
10199 FIN_WAIT state for too long when clients do not disconnect cleanly. This
10200 problem is particularly common long connections such as RDP or WebSocket.
10201 Note that this timeout can override "timeout tunnel" when a connection shuts
Willy Tarreau599391a2017-11-24 10:16:00 +010010202 down in one direction. It is applied to idle HTTP/2 connections once a GOAWAY
10203 frame was sent, often indicating an expectation that the connection quickly
10204 ends.
Willy Tarreau05cdd962014-05-10 14:30:07 +020010205
10206 This parameter is specific to frontends, but can be specified once for all in
10207 "defaults" sections. By default it is not set, so half-closed connections
10208 will use the other timeouts (timeout.client or timeout.tunnel).
10209
10210 See also : "timeout client", "timeout server-fin", and "timeout tunnel".
10211
10212
Willy Tarreau0ba27502007-12-24 16:55:16 +010010213timeout connect <timeout>
Willy Tarreau0ba27502007-12-24 16:55:16 +010010214 Set the maximum time to wait for a connection attempt to a server to succeed.
10215 May be used in sections : defaults | frontend | listen | backend
10216 yes | no | yes | yes
10217 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010010218 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +010010219 can be in any other unit if the number is suffixed by the unit,
10220 as explained at the top of this document.
10221
10222 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010010223 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +010010224 cover one or several TCP packet losses by specifying timeouts that are
Davor Ocelice9ed2812017-12-25 17:49:28 +010010225 slightly above multiples of 3 seconds (e.g. 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010226 connect timeout also presets both queue and tarpit timeouts to the same value
10227 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +010010228
10229 This parameter is specific to backends, but can be specified once for all in
10230 "defaults" sections. This is in fact one of the easiest solutions not to
10231 forget about it. An unspecified timeout results in an infinite timeout, which
10232 is not recommended. Such a usage is accepted and works but reports a warning
John Roeslerfb2fce12019-07-10 15:45:51 -050010233 during startup because it may result in accumulation of failed sessions in
Willy Tarreau0ba27502007-12-24 16:55:16 +010010234 the system if the system's timeouts are not configured either.
10235
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020010236 See also: "timeout check", "timeout queue", "timeout server", "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +010010237
Willy Tarreau0ba27502007-12-24 16:55:16 +010010238
Willy Tarreaub16a5742010-01-10 14:46:16 +010010239timeout http-keep-alive <timeout>
10240 Set the maximum allowed time to wait for a new HTTP request to appear
10241 May be used in sections : defaults | frontend | listen | backend
10242 yes | yes | yes | yes
10243 Arguments :
10244 <timeout> is the timeout value specified in milliseconds by default, but
10245 can be in any other unit if the number is suffixed by the unit,
10246 as explained at the top of this document.
10247
10248 By default, the time to wait for a new request in case of keep-alive is set
10249 by "timeout http-request". However this is not always convenient because some
10250 people want very short keep-alive timeouts in order to release connections
10251 faster, and others prefer to have larger ones but still have short timeouts
10252 once the request has started to present itself.
10253
10254 The "http-keep-alive" timeout covers these needs. It will define how long to
10255 wait for a new HTTP request to start coming after a response was sent. Once
10256 the first byte of request has been seen, the "http-request" timeout is used
10257 to wait for the complete request to come. Note that empty lines prior to a
10258 new request do not refresh the timeout and are not counted as a new request.
10259
10260 There is also another difference between the two timeouts : when a connection
10261 expires during timeout http-keep-alive, no error is returned, the connection
10262 just closes. If the connection expires in "http-request" while waiting for a
10263 connection to complete, a HTTP 408 error is returned.
10264
10265 In general it is optimal to set this value to a few tens to hundreds of
10266 milliseconds, to allow users to fetch all objects of a page at once but
Davor Ocelice9ed2812017-12-25 17:49:28 +010010267 without waiting for further clicks. Also, if set to a very small value (e.g.
Willy Tarreaub16a5742010-01-10 14:46:16 +010010268 1 millisecond) it will probably only accept pipelined requests but not the
10269 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +020010270 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +010010271
10272 If this parameter is not set, the "http-request" timeout applies, and if both
10273 are not set, "timeout client" still applies at the lower level. It should be
10274 set in the frontend to take effect, unless the frontend is in TCP mode, in
10275 which case the HTTP backend's timeout will be used.
10276
Willy Tarreau95c4e142017-11-26 12:18:55 +010010277 When using HTTP/2 "timeout client" is applied instead. This is so we can keep
10278 using short keep-alive timeouts in HTTP/1.1 while using longer ones in HTTP/2
Lukas Tribus75df9d72017-11-24 19:05:12 +010010279 (where we only have one connection per client and a connection setup).
10280
Willy Tarreaub16a5742010-01-10 14:46:16 +010010281 See also : "timeout http-request", "timeout client".
10282
10283
Willy Tarreau036fae02008-01-06 13:24:40 +010010284timeout http-request <timeout>
10285 Set the maximum allowed time to wait for a complete HTTP request
10286 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +020010287 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +010010288 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010010289 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +010010290 can be in any other unit if the number is suffixed by the unit,
10291 as explained at the top of this document.
10292
10293 In order to offer DoS protection, it may be required to lower the maximum
10294 accepted time to receive a complete HTTP request without affecting the client
10295 timeout. This helps protecting against established connections on which
10296 nothing is sent. The client timeout cannot offer a good protection against
10297 this abuse because it is an inactivity timeout, which means that if the
10298 attacker sends one character every now and then, the timeout will not
10299 trigger. With the HTTP request timeout, no matter what speed the client
Willy Tarreau2705a612014-05-23 17:38:34 +020010300 types, the request will be aborted if it does not complete in time. When the
10301 timeout expires, an HTTP 408 response is sent to the client to inform it
10302 about the problem, and the connection is closed. The logs will report
10303 termination codes "cR". Some recent browsers are having problems with this
Davor Ocelice9ed2812017-12-25 17:49:28 +010010304 standard, well-documented behavior, so it might be needed to hide the 408
Willy Tarreau0f228a02015-05-01 15:37:53 +020010305 code using "option http-ignore-probes" or "errorfile 408 /dev/null". See
10306 more details in the explanations of the "cR" termination code in section 8.5.
Willy Tarreau036fae02008-01-06 13:24:40 +010010307
Baptiste Assmanneccdf432015-10-28 13:49:01 +010010308 By default, this timeout only applies to the header part of the request,
10309 and not to any data. As soon as the empty line is received, this timeout is
10310 not used anymore. When combined with "option http-buffer-request", this
10311 timeout also applies to the body of the request..
10312 It is used again on keep-alive connections to wait for a second
Willy Tarreaub16a5742010-01-10 14:46:16 +010010313 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +010010314
10315 Generally it is enough to set it to a few seconds, as most clients send the
10316 full request immediately upon connection. Add 3 or more seconds to cover TCP
Davor Ocelice9ed2812017-12-25 17:49:28 +010010317 retransmits but that's all. Setting it to very low values (e.g. 50 ms) will
Willy Tarreau036fae02008-01-06 13:24:40 +010010318 generally work on local networks as long as there are no packet losses. This
10319 will prevent people from sending bare HTTP requests using telnet.
10320
10321 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +020010322 chunk of the incoming request. It should be set in the frontend to take
10323 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
10324 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +010010325
Willy Tarreau0f228a02015-05-01 15:37:53 +020010326 See also : "errorfile", "http-ignore-probes", "timeout http-keep-alive", and
Baptiste Assmanneccdf432015-10-28 13:49:01 +010010327 "timeout client", "option http-buffer-request".
Willy Tarreau036fae02008-01-06 13:24:40 +010010328
Willy Tarreau844e3c52008-01-11 16:28:18 +010010329
10330timeout queue <timeout>
10331 Set the maximum time to wait in the queue for a connection slot to be free
10332 May be used in sections : defaults | frontend | listen | backend
10333 yes | no | yes | yes
10334 Arguments :
10335 <timeout> is the timeout value specified in milliseconds by default, but
10336 can be in any other unit if the number is suffixed by the unit,
10337 as explained at the top of this document.
10338
10339 When a server's maxconn is reached, connections are left pending in a queue
10340 which may be server-specific or global to the backend. In order not to wait
10341 indefinitely, a timeout is applied to requests pending in the queue. If the
10342 timeout is reached, it is considered that the request will almost never be
10343 served, so it is dropped and a 503 error is returned to the client.
10344
10345 The "timeout queue" statement allows to fix the maximum time for a request to
10346 be left pending in a queue. If unspecified, the same value as the backend's
10347 connection timeout ("timeout connect") is used, for backwards compatibility
10348 with older versions with no "timeout queue" parameter.
10349
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020010350 See also : "timeout connect".
Willy Tarreau844e3c52008-01-11 16:28:18 +010010351
10352
10353timeout server <timeout>
Willy Tarreau844e3c52008-01-11 16:28:18 +010010354 Set the maximum inactivity time on the server side.
10355 May be used in sections : defaults | frontend | listen | backend
10356 yes | no | yes | yes
10357 Arguments :
10358 <timeout> is the timeout value specified in milliseconds by default, but
10359 can be in any other unit if the number is suffixed by the unit,
10360 as explained at the top of this document.
10361
10362 The inactivity timeout applies when the server is expected to acknowledge or
10363 send data. In HTTP mode, this timeout is particularly important to consider
10364 during the first phase of the server's response, when it has to send the
10365 headers, as it directly represents the server's processing time for the
10366 request. To find out what value to put there, it's often good to start with
10367 what would be considered as unacceptable response times, then check the logs
10368 to observe the response time distribution, and adjust the value accordingly.
10369
10370 The value is specified in milliseconds by default, but can be in any other
10371 unit if the number is suffixed by the unit, as specified at the top of this
10372 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
10373 recommended that the client timeout remains equal to the server timeout in
10374 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010010375 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +010010376 packet losses by specifying timeouts that are slightly above multiples of 3
Davor Ocelice9ed2812017-12-25 17:49:28 +010010377 seconds (e.g. 4 or 5 seconds minimum). If some long-lived sessions are mixed
10378 with short-lived sessions (e.g. WebSocket and HTTP), it's worth considering
Willy Tarreauce887fd2012-05-12 12:50:00 +020010379 "timeout tunnel", which overrides "timeout client" and "timeout server" for
10380 tunnels.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010381
10382 This parameter is specific to backends, but can be specified once for all in
10383 "defaults" sections. This is in fact one of the easiest solutions not to
10384 forget about it. An unspecified timeout results in an infinite timeout, which
10385 is not recommended. Such a usage is accepted and works but reports a warning
John Roeslerfb2fce12019-07-10 15:45:51 -050010386 during startup because it may result in accumulation of expired sessions in
Willy Tarreau844e3c52008-01-11 16:28:18 +010010387 the system if the system's timeouts are not configured either.
10388
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020010389 See also : "timeout client" and "timeout tunnel".
Willy Tarreau844e3c52008-01-11 16:28:18 +010010390
Willy Tarreau05cdd962014-05-10 14:30:07 +020010391
10392timeout server-fin <timeout>
10393 Set the inactivity timeout on the server side for half-closed connections.
10394 May be used in sections : defaults | frontend | listen | backend
10395 yes | no | yes | yes
10396 Arguments :
10397 <timeout> is the timeout value specified in milliseconds by default, but
10398 can be in any other unit if the number is suffixed by the unit,
10399 as explained at the top of this document.
10400
10401 The inactivity timeout applies when the server is expected to acknowledge or
10402 send data while one direction is already shut down. This timeout is different
10403 from "timeout server" in that it only applies to connections which are closed
10404 in one direction. This is particularly useful to avoid keeping connections in
10405 FIN_WAIT state for too long when a remote server does not disconnect cleanly.
10406 This problem is particularly common long connections such as RDP or WebSocket.
10407 Note that this timeout can override "timeout tunnel" when a connection shuts
10408 down in one direction. This setting was provided for completeness, but in most
10409 situations, it should not be needed.
10410
10411 This parameter is specific to backends, but can be specified once for all in
10412 "defaults" sections. By default it is not set, so half-closed connections
10413 will use the other timeouts (timeout.server or timeout.tunnel).
10414
10415 See also : "timeout client-fin", "timeout server", and "timeout tunnel".
10416
Willy Tarreau844e3c52008-01-11 16:28:18 +010010417
10418timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +010010419 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +010010420 May be used in sections : defaults | frontend | listen | backend
10421 yes | yes | yes | yes
10422 Arguments :
10423 <timeout> is the tarpit duration specified in milliseconds by default, but
10424 can be in any other unit if the number is suffixed by the unit,
10425 as explained at the top of this document.
10426
Christopher Faulet87f1f3d2019-07-18 14:51:20 +020010427 When a connection is tarpitted using "http-request tarpit", it is maintained
10428 open with no activity for a certain amount of time, then closed. "timeout
10429 tarpit" defines how long it will be maintained open.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010430
10431 The value is specified in milliseconds by default, but can be in any other
10432 unit if the number is suffixed by the unit, as specified at the top of this
10433 document. If unspecified, the same value as the backend's connection timeout
10434 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +010010435 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010436
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020010437 See also : "timeout connect".
Willy Tarreau844e3c52008-01-11 16:28:18 +010010438
10439
Willy Tarreauce887fd2012-05-12 12:50:00 +020010440timeout tunnel <timeout>
10441 Set the maximum inactivity time on the client and server side for tunnels.
10442 May be used in sections : defaults | frontend | listen | backend
10443 yes | no | yes | yes
10444 Arguments :
10445 <timeout> is the timeout value specified in milliseconds by default, but
10446 can be in any other unit if the number is suffixed by the unit,
10447 as explained at the top of this document.
10448
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010449 The tunnel timeout applies when a bidirectional connection is established
Willy Tarreauce887fd2012-05-12 12:50:00 +020010450 between a client and a server, and the connection remains inactive in both
10451 directions. This timeout supersedes both the client and server timeouts once
10452 the connection becomes a tunnel. In TCP, this timeout is used as soon as no
Davor Ocelice9ed2812017-12-25 17:49:28 +010010453 analyzer remains attached to either connection (e.g. tcp content rules are
10454 accepted). In HTTP, this timeout is used when a connection is upgraded (e.g.
Willy Tarreauce887fd2012-05-12 12:50:00 +020010455 when switching to the WebSocket protocol, or forwarding a CONNECT request
10456 to a proxy), or after the first response when no keepalive/close option is
10457 specified.
10458
Willy Tarreau05cdd962014-05-10 14:30:07 +020010459 Since this timeout is usually used in conjunction with long-lived connections,
10460 it usually is a good idea to also set "timeout client-fin" to handle the
10461 situation where a client suddenly disappears from the net and does not
10462 acknowledge a close, or sends a shutdown and does not acknowledge pending
10463 data anymore. This can happen in lossy networks where firewalls are present,
10464 and is detected by the presence of large amounts of sessions in a FIN_WAIT
10465 state.
10466
Willy Tarreauce887fd2012-05-12 12:50:00 +020010467 The value is specified in milliseconds by default, but can be in any other
10468 unit if the number is suffixed by the unit, as specified at the top of this
10469 document. Whatever the expected normal idle time, it is a good practice to
10470 cover at least one or several TCP packet losses by specifying timeouts that
Davor Ocelice9ed2812017-12-25 17:49:28 +010010471 are slightly above multiples of 3 seconds (e.g. 4 or 5 seconds minimum).
Willy Tarreauce887fd2012-05-12 12:50:00 +020010472
10473 This parameter is specific to backends, but can be specified once for all in
10474 "defaults" sections. This is in fact one of the easiest solutions not to
10475 forget about it.
10476
10477 Example :
10478 defaults http
10479 option http-server-close
10480 timeout connect 5s
10481 timeout client 30s
Willy Tarreau05cdd962014-05-10 14:30:07 +020010482 timeout client-fin 30s
Willy Tarreauce887fd2012-05-12 12:50:00 +020010483 timeout server 30s
10484 timeout tunnel 1h # timeout to use with WebSocket and CONNECT
10485
Willy Tarreau05cdd962014-05-10 14:30:07 +020010486 See also : "timeout client", "timeout client-fin", "timeout server".
Willy Tarreauce887fd2012-05-12 12:50:00 +020010487
10488
Willy Tarreau844e3c52008-01-11 16:28:18 +010010489transparent (deprecated)
10490 Enable client-side transparent proxying
10491 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +010010492 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +010010493 Arguments : none
10494
10495 This keyword was introduced in order to provide layer 7 persistence to layer
10496 3 load balancers. The idea is to use the OS's ability to redirect an incoming
10497 connection for a remote address to a local process (here HAProxy), and let
10498 this process know what address was initially requested. When this option is
10499 used, sessions without cookies will be forwarded to the original destination
10500 IP address of the incoming request (which should match that of another
10501 equipment), while requests with cookies will still be forwarded to the
10502 appropriate server.
10503
10504 The "transparent" keyword is deprecated, use "option transparent" instead.
10505
10506 Note that contrary to a common belief, this option does NOT make HAProxy
10507 present the client's IP to the server when establishing the connection.
10508
Willy Tarreau844e3c52008-01-11 16:28:18 +010010509 See also: "option transparent"
10510
William Lallemanda73203e2012-03-12 12:48:57 +010010511unique-id-format <string>
10512 Generate a unique ID for each request.
10513 May be used in sections : defaults | frontend | listen | backend
10514 yes | yes | yes | no
10515 Arguments :
10516 <string> is a log-format string.
10517
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010518 This keyword creates a ID for each request using the custom log format. A
10519 unique ID is useful to trace a request passing through many components of
10520 a complex infrastructure. The newly created ID may also be logged using the
10521 %ID tag the log-format string.
William Lallemanda73203e2012-03-12 12:48:57 +010010522
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010523 The format should be composed from elements that are guaranteed to be
10524 unique when combined together. For instance, if multiple haproxy instances
10525 are involved, it might be important to include the node name. It is often
10526 needed to log the incoming connection's source and destination addresses
10527 and ports. Note that since multiple requests may be performed over the same
10528 connection, including a request counter may help differentiate them.
10529 Similarly, a timestamp may protect against a rollover of the counter.
10530 Logging the process ID will avoid collisions after a service restart.
William Lallemanda73203e2012-03-12 12:48:57 +010010531
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010532 It is recommended to use hexadecimal notation for many fields since it
10533 makes them more compact and saves space in logs.
William Lallemanda73203e2012-03-12 12:48:57 +010010534
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010535 Example:
William Lallemanda73203e2012-03-12 12:48:57 +010010536
Julien Vehentf21be322014-03-07 08:27:34 -050010537 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +010010538
10539 will generate:
10540
10541 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
10542
10543 See also: "unique-id-header"
10544
10545unique-id-header <name>
10546 Add a unique ID header in the HTTP request.
10547 May be used in sections : defaults | frontend | listen | backend
10548 yes | yes | yes | no
10549 Arguments :
10550 <name> is the name of the header.
10551
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010552 Add a unique-id header in the HTTP request sent to the server, using the
10553 unique-id-format. It can't work if the unique-id-format doesn't exist.
William Lallemanda73203e2012-03-12 12:48:57 +010010554
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010555 Example:
William Lallemanda73203e2012-03-12 12:48:57 +010010556
Julien Vehentf21be322014-03-07 08:27:34 -050010557 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +010010558 unique-id-header X-Unique-ID
10559
10560 will generate:
10561
10562 X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
10563
10564 See also: "unique-id-format"
Willy Tarreau844e3c52008-01-11 16:28:18 +010010565
Willy Tarreauf51658d2014-04-23 01:21:56 +020010566use_backend <backend> [{if | unless} <condition>]
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020010567 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010568 May be used in sections : defaults | frontend | listen | backend
10569 no | yes | yes | no
10570 Arguments :
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010010571 <backend> is the name of a valid backend or "listen" section, or a
10572 "log-format" string resolving to a backend name.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010573
Willy Tarreauf51658d2014-04-23 01:21:56 +020010574 <condition> is a condition composed of ACLs, as described in section 7. If
10575 it is omitted, the rule is unconditionally applied.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010576
10577 When doing content-switching, connections arrive on a frontend and are then
10578 dispatched to various backends depending on a number of conditions. The
10579 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020010580 "use_backend" keyword. While it is normally used with HTTP processing, it can
Davor Ocelice9ed2812017-12-25 17:49:28 +010010581 also be used in pure TCP, either without content using stateless ACLs (e.g.
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020010582 source address validation) or combined with a "tcp-request" rule to wait for
10583 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010584
10585 There may be as many "use_backend" rules as desired. All of these rules are
10586 evaluated in their declaration order, and the first one which matches will
10587 assign the backend.
10588
10589 In the first form, the backend will be used if the condition is met. In the
10590 second form, the backend will be used if the condition is not met. If no
10591 condition is valid, the backend defined with "default_backend" will be used.
10592 If no default backend is defined, either the servers in the same section are
10593 used (in case of a "listen" section) or, in case of a frontend, no server is
10594 used and a 503 service unavailable response is returned.
10595
Willy Tarreau51aecc72009-07-12 09:47:04 +020010596 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010597 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +020010598 and backend processing will immediately follow, or the backend will wait for
10599 a complete HTTP request to get in. This feature is useful when a frontend
10600 must decode several protocols on a unique port, one of them being HTTP.
10601
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010010602 When <backend> is a simple name, it is resolved at configuration time, and an
10603 error is reported if the specified backend does not exist. If <backend> is
10604 a log-format string instead, no check may be done at configuration time, so
10605 the backend name is resolved dynamically at run time. If the resulting
10606 backend name does not correspond to any valid backend, no other rule is
10607 evaluated, and the default_backend directive is applied instead. Note that
10608 when using dynamic backend names, it is highly recommended to use a prefix
10609 that no other backend uses in order to ensure that an unauthorized backend
10610 cannot be forced from the request.
10611
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010612 It is worth mentioning that "use_backend" rules with an explicit name are
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010010613 used to detect the association between frontends and backends to compute the
10614 backend's "fullconn" setting. This cannot be done for dynamic names.
10615
10616 See also: "default_backend", "tcp-request", "fullconn", "log-format", and
10617 section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +010010618
Christopher Fauletb30b3102019-09-12 23:03:09 +020010619use-fcgi-app <name>
10620 Defines the FastCGI application to use for the backend.
10621 May be used in sections : defaults | frontend | listen | backend
10622 no | no | yes | yes
10623 Arguments :
10624 <name> is the name of the FastCGI application to use.
10625
10626 See section 10.1 about FastCGI application setup for details.
Willy Tarreau036fae02008-01-06 13:24:40 +010010627
Willy Tarreau4a5cade2012-04-05 21:09:48 +020010628use-server <server> if <condition>
10629use-server <server> unless <condition>
10630 Only use a specific server if/unless an ACL-based condition is matched.
10631 May be used in sections : defaults | frontend | listen | backend
10632 no | no | yes | yes
10633 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010634 <server> is the name of a valid server in the same backend section.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020010635
10636 <condition> is a condition composed of ACLs, as described in section 7.
10637
10638 By default, connections which arrive to a backend are load-balanced across
10639 the available servers according to the configured algorithm, unless a
10640 persistence mechanism such as a cookie is used and found in the request.
10641
10642 Sometimes it is desirable to forward a particular request to a specific
10643 server without having to declare a dedicated backend for this server. This
10644 can be achieved using the "use-server" rules. These rules are evaluated after
10645 the "redirect" rules and before evaluating cookies, and they have precedence
10646 on them. There may be as many "use-server" rules as desired. All of these
10647 rules are evaluated in their declaration order, and the first one which
10648 matches will assign the server.
10649
10650 If a rule designates a server which is down, and "option persist" is not used
10651 and no force-persist rule was validated, it is ignored and evaluation goes on
10652 with the next rules until one matches.
10653
10654 In the first form, the server will be used if the condition is met. In the
10655 second form, the server will be used if the condition is not met. If no
10656 condition is valid, the processing continues and the server will be assigned
10657 according to other persistence mechanisms.
10658
10659 Note that even if a rule is matched, cookie processing is still performed but
10660 does not assign the server. This allows prefixed cookies to have their prefix
10661 stripped.
10662
10663 The "use-server" statement works both in HTTP and TCP mode. This makes it
10664 suitable for use with content-based inspection. For instance, a server could
10665 be selected in a farm according to the TLS SNI field. And if these servers
10666 have their weight set to zero, they will not be used for other traffic.
10667
10668 Example :
10669 # intercept incoming TLS requests based on the SNI field
10670 use-server www if { req_ssl_sni -i www.example.com }
10671 server www 192.168.0.1:443 weight 0
10672 use-server mail if { req_ssl_sni -i mail.example.com }
10673 server mail 192.168.0.1:587 weight 0
10674 use-server imap if { req_ssl_sni -i imap.example.com }
Lukas Tribus98a3e3f2017-03-26 12:55:35 +000010675 server imap 192.168.0.1:993 weight 0
Willy Tarreau4a5cade2012-04-05 21:09:48 +020010676 # all the rest is forwarded to this server
10677 server default 192.168.0.2:443 check
10678
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010679 See also: "use_backend", section 5 about server and section 7 about ACLs.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020010680
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010681
Davor Ocelice9ed2812017-12-25 17:49:28 +0100106825. Bind and server options
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010683--------------------------
10684
10685The "bind", "server" and "default-server" keywords support a number of settings
10686depending on some build options and on the system HAProxy was built on. These
10687settings generally each consist in one word sometimes followed by a value,
10688written on the same line as the "bind" or "server" line. All these options are
10689described in this section.
10690
10691
106925.1. Bind options
10693-----------------
10694
10695The "bind" keyword supports a certain number of settings which are all passed
10696as arguments on the same line. The order in which those arguments appear makes
10697no importance, provided that they appear after the bind address. All of these
10698parameters are optional. Some of them consist in a single words (booleans),
10699while other ones expect a value after them. In this case, the value must be
10700provided immediately after the setting name.
10701
10702The currently supported settings are the following ones.
10703
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010010704accept-netscaler-cip <magic number>
10705 Enforces the use of the NetScaler Client IP insertion protocol over any
10706 connection accepted by any of the TCP sockets declared on the same line. The
10707 NetScaler Client IP insertion protocol dictates the layer 3/4 addresses of
10708 the incoming connection to be used everywhere an address is used, with the
10709 only exception of "tcp-request connection" rules which will only see the
10710 real connection address. Logs will reflect the addresses indicated in the
10711 protocol, unless it is violated, in which case the real address will still
10712 be used. This keyword combined with support from external components can be
10713 used as an efficient and reliable alternative to the X-Forwarded-For
Bertrand Jacquin90759682016-06-06 15:35:39 +010010714 mechanism which is not always reliable and not even always usable. See also
10715 "tcp-request connection expect-netscaler-cip" for a finer-grained setting of
10716 which client is allowed to use the protocol.
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010010717
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010718accept-proxy
10719 Enforces the use of the PROXY protocol over any connection accepted by any of
Willy Tarreau77992672014-06-14 11:06:17 +020010720 the sockets declared on the same line. Versions 1 and 2 of the PROXY protocol
10721 are supported and correctly detected. The PROXY protocol dictates the layer
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010722 3/4 addresses of the incoming connection to be used everywhere an address is
10723 used, with the only exception of "tcp-request connection" rules which will
10724 only see the real connection address. Logs will reflect the addresses
10725 indicated in the protocol, unless it is violated, in which case the real
Davor Ocelice9ed2812017-12-25 17:49:28 +010010726 address will still be used. This keyword combined with support from external
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010727 components can be used as an efficient and reliable alternative to the
10728 X-Forwarded-For mechanism which is not always reliable and not even always
Willy Tarreau4f0d9192013-06-11 20:40:55 +020010729 usable. See also "tcp-request connection expect-proxy" for a finer-grained
10730 setting of which client is allowed to use the protocol.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010731
Olivier Houchardc2aae742017-09-22 18:26:28 +020010732allow-0rtt
Bertrand Jacquina25282b2018-08-14 00:56:13 +010010733 Allow receiving early data when using TLSv1.3. This is disabled by default,
Olivier Houchard69752962019-01-08 15:35:32 +010010734 due to security considerations. Because it is vulnerable to replay attacks,
John Roeslerfb2fce12019-07-10 15:45:51 -050010735 you should only allow if for requests that are safe to replay, i.e. requests
Olivier Houchard69752962019-01-08 15:35:32 +010010736 that are idempotent. You can use the "wait-for-handshake" action for any
10737 request that wouldn't be safe with early data.
Olivier Houchardc2aae742017-09-22 18:26:28 +020010738
Willy Tarreauab861d32013-04-02 02:30:41 +020010739alpn <protocols>
10740 This enables the TLS ALPN extension and advertises the specified protocol
10741 list as supported on top of ALPN. The protocol list consists in a comma-
10742 delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
John Roeslerfb2fce12019-07-10 15:45:51 -050010743 quotes). This requires that the SSL library is built with support for TLS
Willy Tarreauab861d32013-04-02 02:30:41 +020010744 extensions enabled (check with haproxy -vv). The ALPN extension replaces the
Willy Tarreau95c4e142017-11-26 12:18:55 +010010745 initial NPN extension. ALPN is required to enable HTTP/2 on an HTTP frontend.
10746 Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the
10747 now obsolete NPN extension. At the time of writing this, most browsers still
10748 support both ALPN and NPN for HTTP/2 so a fallback to NPN may still work for
10749 a while. But ALPN must be used whenever possible. If both HTTP/2 and HTTP/1.1
10750 are expected to be supported, both versions can be advertised, in order of
10751 preference, like below :
10752
10753 bind :443 ssl crt pub.pem alpn h2,http/1.1
Willy Tarreauab861d32013-04-02 02:30:41 +020010754
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010755backlog <backlog>
Willy Tarreaue2711c72019-02-27 15:39:41 +010010756 Sets the socket's backlog to this value. If unspecified or 0, the frontend's
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010757 backlog is used instead, which generally defaults to the maxconn value.
10758
Emmanuel Hocdete7f2b732017-01-09 16:15:54 +010010759curves <curves>
10760 This setting is only available when support for OpenSSL was built in. It sets
10761 the string describing the list of elliptic curves algorithms ("curve suite")
10762 that are negotiated during the SSL/TLS handshake with ECDHE. The format of the
10763 string is a colon-delimited list of curve name.
10764 Example: "X25519:P-256" (without quote)
10765 When "curves" is set, "ecdhe" parameter is ignored.
10766
Emeric Brun7fb34422012-09-28 15:26:15 +020010767ecdhe <named curve>
10768 This setting is only available when support for OpenSSL was built in. It sets
Emeric Brun6924ef82013-03-06 14:08:53 +010010769 the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default,
10770 used named curve is prime256v1.
Emeric Brun7fb34422012-09-28 15:26:15 +020010771
Emeric Brunfd33a262012-10-11 16:28:27 +020010772ca-file <cafile>
Emeric Brun1a073b42012-09-28 17:07:34 +020010773 This setting is only available when support for OpenSSL was built in. It
10774 designates a PEM file from which to load CA certificates used to verify
10775 client's certificate.
10776
Emeric Brunb6dc9342012-09-28 17:55:37 +020010777ca-ignore-err [all|<errorID>,...]
10778 This setting is only available when support for OpenSSL was built in.
10779 Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
10780 If set to 'all', all errors are ignored. SSL handshake is not aborted if an
10781 error is ignored.
10782
Christopher Faulet31af49d2015-06-09 17:29:50 +020010783ca-sign-file <cafile>
10784 This setting is only available when support for OpenSSL was built in. It
10785 designates a PEM file containing both the CA certificate and the CA private
10786 key used to create and sign server's certificates. This is a mandatory
10787 setting when the dynamic generation of certificates is enabled. See
10788 'generate-certificates' for details.
10789
Bertrand Jacquind4d0a232016-11-13 16:37:12 +000010790ca-sign-pass <passphrase>
Christopher Faulet31af49d2015-06-09 17:29:50 +020010791 This setting is only available when support for OpenSSL was built in. It is
10792 the CA private key passphrase. This setting is optional and used only when
10793 the dynamic generation of certificates is enabled. See
10794 'generate-certificates' for details.
10795
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010796ciphers <ciphers>
10797 This setting is only available when support for OpenSSL was built in. It sets
10798 the string describing the list of cipher algorithms ("cipher suite") that are
Bertrand Jacquin8cf7c1e2019-02-03 18:35:25 +000010799 negotiated during the SSL/TLS handshake up to TLSv1.2. The format of the
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000010800 string is defined in "man 1 ciphers" from OpenSSL man pages. For background
Dirkjan Bussink415150f2018-09-14 11:14:21 +020010801 information and recommendations see e.g.
10802 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
10803 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
10804 cipher configuration, please check the "ciphersuites" keyword.
10805
10806ciphersuites <ciphersuites>
10807 This setting is only available when support for OpenSSL was built in and
10808 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the string describing
10809 the list of cipher algorithms ("cipher suite") that are negotiated during the
10810 TLSv1.3 handshake. The format of the string is defined in "man 1 ciphers" from
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000010811 OpenSSL man pages under the "ciphersuites" section. For cipher configuration
10812 for TLSv1.2 and earlier, please check the "ciphers" keyword.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010813
Emeric Brunfd33a262012-10-11 16:28:27 +020010814crl-file <crlfile>
Emeric Brun1a073b42012-09-28 17:07:34 +020010815 This setting is only available when support for OpenSSL was built in. It
10816 designates a PEM file from which to load certificate revocation list used
10817 to verify client's certificate.
10818
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010819crt <cert>
Alex Davies0fbf0162013-03-02 16:04:50 +000010820 This setting is only available when support for OpenSSL was built in. It
10821 designates a PEM file containing both the required certificates and any
10822 associated private keys. This file can be built by concatenating multiple
10823 PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA
10824 requires an intermediate certificate, this can also be concatenated into this
10825 file.
10826
10827 If the OpenSSL used supports Diffie-Hellman, parameters present in this file
10828 are loaded.
10829
10830 If a directory name is used instead of a PEM file, then all files found in
Cyril Bonté3180f7b2015-01-25 00:16:08 +010010831 that directory will be loaded in alphabetic order unless their name ends with
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010010832 '.issuer', '.ocsp' or '.sctl' (reserved extensions). This directive may be
10833 specified multiple times in order to load certificates from multiple files or
10834 directories. The certificates will be presented to clients who provide a
10835 valid TLS Server Name Indication field matching one of their CN or alt
Davor Ocelice9ed2812017-12-25 17:49:28 +010010836 subjects. Wildcards are supported, where a wildcard character '*' is used
10837 instead of the first hostname component (e.g. *.example.org matches
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010010838 www.example.org but not www.sub.example.org).
Alex Davies0fbf0162013-03-02 16:04:50 +000010839
10840 If no SNI is provided by the client or if the SSL library does not support
10841 TLS extensions, or if the client provides an SNI hostname which does not
10842 match any certificate, then the first loaded certificate will be presented.
10843 This means that when loading certificates from a directory, it is highly
Cyril Bonté3180f7b2015-01-25 00:16:08 +010010844 recommended to load the default one first as a file or to ensure that it will
10845 always be the first one in the directory.
Alex Davies0fbf0162013-03-02 16:04:50 +000010846
Emeric Brune032bfa2012-09-28 13:01:45 +020010847 Note that the same cert may be loaded multiple times without side effects.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010848
Davor Ocelice9ed2812017-12-25 17:49:28 +010010849 Some CAs (such as GoDaddy) offer a drop down list of server types that do not
Alex Davies0fbf0162013-03-02 16:04:50 +000010850 include HAProxy when obtaining a certificate. If this happens be sure to
Davor Ocelice9ed2812017-12-25 17:49:28 +010010851 choose a web server that the CA believes requires an intermediate CA (for
10852 GoDaddy, selection Apache Tomcat will get the correct bundle, but many
Alex Davies0fbf0162013-03-02 16:04:50 +000010853 others, e.g. nginx, result in a wrong bundle that will not work for some
10854 clients).
10855
Emeric Brun4147b2e2014-06-16 18:36:30 +020010856 For each PEM file, haproxy checks for the presence of file at the same path
10857 suffixed by ".ocsp". If such file is found, support for the TLS Certificate
10858 Status Request extension (also known as "OCSP stapling") is automatically
10859 enabled. The content of this file is optional. If not empty, it must contain
10860 a valid OCSP Response in DER format. In order to be valid an OCSP Response
10861 must comply with the following rules: it has to indicate a good status,
10862 it has to be a single response for the certificate of the PEM file, and it
10863 has to be valid at the moment of addition. If these rules are not respected
10864 the OCSP Response is ignored and a warning is emitted. In order to identify
10865 which certificate an OCSP Response applies to, the issuer's certificate is
10866 necessary. If the issuer's certificate is not found in the PEM file, it will
10867 be loaded from a file at the same path as the PEM file suffixed by ".issuer"
10868 if it exists otherwise it will fail with an error.
10869
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010010870 For each PEM file, haproxy also checks for the presence of file at the same
10871 path suffixed by ".sctl". If such file is found, support for Certificate
10872 Transparency (RFC6962) TLS extension is enabled. The file must contain a
10873 valid Signed Certificate Timestamp List, as described in RFC. File is parsed
10874 to check basic syntax, but no signatures are verified.
10875
yanbzhu6c25e9e2016-01-05 12:52:02 -050010876 There are cases where it is desirable to support multiple key types, e.g. RSA
10877 and ECDSA in the cipher suites offered to the clients. This allows clients
10878 that support EC certificates to be able to use EC ciphers, while
10879 simultaneously supporting older, RSA only clients.
yanbzhud19630c2015-12-14 15:10:25 -050010880
10881 In order to provide this functionality, multiple PEM files, each with a
10882 different key type, are required. To associate these PEM files into a
10883 "cert bundle" that is recognized by haproxy, they must be named in the
10884 following way: All PEM files that are to be bundled must have the same base
10885 name, with a suffix indicating the key type. Currently, three suffixes are
10886 supported: rsa, dsa and ecdsa. For example, if www.example.com has two PEM
10887 files, an RSA file and an ECDSA file, they must be named: "example.pem.rsa"
10888 and "example.pem.ecdsa". The first part of the filename is arbitrary; only the
10889 suffix matters. To load this bundle into haproxy, specify the base name only:
10890
10891 Example : bind :8443 ssl crt example.pem
10892
yanbzhu6c25e9e2016-01-05 12:52:02 -050010893 Note that the suffix is not given to haproxy; this tells haproxy to look for
yanbzhud19630c2015-12-14 15:10:25 -050010894 a cert bundle.
10895
Davor Ocelice9ed2812017-12-25 17:49:28 +010010896 HAProxy will load all PEM files in the bundle at the same time to try to
yanbzhud19630c2015-12-14 15:10:25 -050010897 support multiple key types. PEM files are combined based on Common Name
10898 (CN) and Subject Alternative Name (SAN) to support SNI lookups. This means
10899 that even if you give haproxy a cert bundle, if there are no shared CN/SAN
10900 entries in the certificates in that bundle, haproxy will not be able to
10901 provide multi-cert support.
10902
10903 Assuming bundle in the example above contained the following:
10904
10905 Filename | CN | SAN
10906 -------------------+-----------------+-------------------
10907 example.pem.rsa | www.example.com | rsa.example.com
yanbzhu6c25e9e2016-01-05 12:52:02 -050010908 -------------------+-----------------+-------------------
yanbzhud19630c2015-12-14 15:10:25 -050010909 example.pem.ecdsa | www.example.com | ecdsa.example.com
10910 -------------------+-----------------+-------------------
10911
10912 Users connecting with an SNI of "www.example.com" will be able
10913 to use both RSA and ECDSA cipher suites. Users connecting with an SNI of
10914 "rsa.example.com" will only be able to use RSA cipher suites, and users
10915 connecting with "ecdsa.example.com" will only be able to use ECDSA cipher
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020010916 suites. With BoringSSL and Openssl >= 1.1.1 multi-cert is natively supported,
10917 no need to bundle certificates. ECDSA certificate will be preferred if client
10918 support it.
yanbzhud19630c2015-12-14 15:10:25 -050010919
10920 If a directory name is given as the <cert> argument, haproxy will
10921 automatically search and load bundled files in that directory.
10922
10923 OSCP files (.ocsp) and issuer files (.issuer) are supported with multi-cert
10924 bundling. Each certificate can have its own .ocsp and .issuer file. At this
10925 time, sctl is not supported in multi-certificate bundling.
10926
Emeric Brunb6dc9342012-09-28 17:55:37 +020010927crt-ignore-err <errors>
Alex Davies0fbf0162013-03-02 16:04:50 +000010928 This setting is only available when support for OpenSSL was built in. Sets a
Davor Ocelice9ed2812017-12-25 17:49:28 +010010929 comma separated list of errorIDs to ignore during verify at depth == 0. If
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010930 set to 'all', all errors are ignored. SSL handshake is not aborted if an error
Alex Davies0fbf0162013-03-02 16:04:50 +000010931 is ignored.
Emeric Brunb6dc9342012-09-28 17:55:37 +020010932
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010010933crt-list <file>
10934 This setting is only available when support for OpenSSL was built in. It
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010935 designates a list of PEM file with an optional ssl configuration and a SNI
10936 filter per certificate, with the following format for each line :
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010010937
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010938 <crtfile> [\[<sslbindconf> ...\]] [[!]<snifilter> ...]
10939
Emmanuel Hocdet174dfe52017-07-28 15:01:05 +020010940 sslbindconf support "npn", "alpn", "verify", "ca-file", "no-ca-names",
10941 crl-file", "ecdhe", "curves", "ciphers" configuration. With BoringSSL
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020010942 and Openssl >= 1.1.1 "ssl-min-ver" and "ssl-max-ver" are also supported.
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010943 It override the configuration set in bind line for the certificate.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010010944
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +020010945 Wildcards are supported in the SNI filter. Negative filter are also supported,
10946 only useful in combination with a wildcard filter to exclude a particular SNI.
10947 The certificates will be presented to clients who provide a valid TLS Server
10948 Name Indication field matching one of the SNI filters. If no SNI filter is
10949 specified, the CN and alt subjects are used. This directive may be specified
10950 multiple times. See the "crt" option for more information. The default
10951 certificate is still needed to meet OpenSSL expectations. If it is not used,
10952 the 'strict-sni' option may be used.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010010953
yanbzhu6c25e9e2016-01-05 12:52:02 -050010954 Multi-cert bundling (see "crt") is supported with crt-list, as long as only
Emmanuel Hocdetd294aea2016-05-13 11:14:06 +020010955 the base name is given in the crt-list. SNI filter will do the same work on
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020010956 all bundled certificates. With BoringSSL and Openssl >= 1.1.1 multi-cert is
10957 natively supported, avoid multi-cert bundling. RSA and ECDSA certificates can
10958 be declared in a row, and set different ssl and filter parameter.
yanbzhud19630c2015-12-14 15:10:25 -050010959
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010960 crt-list file example:
10961 cert1.pem
Emmanuel Hocdet05942112017-02-20 16:11:50 +010010962 cert2.pem [alpn h2,http/1.1]
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010963 certW.pem *.domain.tld !secure.domain.tld
Emmanuel Hocdet05942112017-02-20 16:11:50 +010010964 certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010965
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010966defer-accept
10967 Is an optional keyword which is supported only on certain Linux kernels. It
10968 states that a connection will only be accepted once some data arrive on it,
10969 or at worst after the first retransmit. This should be used only on protocols
Davor Ocelice9ed2812017-12-25 17:49:28 +010010970 for which the client talks first (e.g. HTTP). It can slightly improve
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010971 performance by ensuring that most of the request is already available when
10972 the connection is accepted. On the other hand, it will not be able to detect
10973 connections which don't talk. It is important to note that this option is
10974 broken in all kernels up to 2.6.31, as the connection is never accepted until
10975 the client talks. This can cause issues with front firewalls which would see
10976 an established connection while the proxy will only see it in SYN_RECV. This
10977 option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
10978
William Lallemandf6975e92017-05-26 17:42:10 +020010979expose-fd listeners
10980 This option is only usable with the stats socket. It gives your stats socket
10981 the capability to pass listeners FD to another HAProxy process.
William Lallemande202b1e2017-06-01 17:38:56 +020010982 During a reload with the master-worker mode, the process is automatically
10983 reexecuted adding -x and one of the stats socket with this option.
Davor Ocelice9ed2812017-12-25 17:49:28 +010010984 See also "-x" in the management guide.
William Lallemandf6975e92017-05-26 17:42:10 +020010985
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010986force-sslv3
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010987 This option enforces use of SSLv3 only on SSL connections instantiated from
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010988 this listener. SSLv3 is generally less expensive than the TLS counterparts
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010989 for high connection rates. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010990 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010991
10992force-tlsv10
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010993 This option enforces use of TLSv1.0 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010994 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010995 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010996
10997force-tlsv11
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010998 This option enforces use of TLSv1.1 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010999 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011000 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011001
11002force-tlsv12
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011003 This option enforces use of TLSv1.2 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011004 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011005 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011006
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011007force-tlsv13
11008 This option enforces use of TLSv1.3 only on SSL connections instantiated from
11009 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011010 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011011
Christopher Faulet31af49d2015-06-09 17:29:50 +020011012generate-certificates
11013 This setting is only available when support for OpenSSL was built in. It
11014 enables the dynamic SSL certificates generation. A CA certificate and its
11015 private key are necessary (see 'ca-sign-file'). When HAProxy is configured as
11016 a transparent forward proxy, SSL requests generate errors because of a common
11017 name mismatch on the certificate presented to the client. With this option
11018 enabled, HAProxy will try to forge a certificate using the SNI hostname
11019 indicated by the client. This is done only if no certificate matches the SNI
11020 hostname (see 'crt-list'). If an error occurs, the default certificate is
11021 used, else the 'strict-sni' option is set.
11022 It can also be used when HAProxy is configured as a reverse proxy to ease the
11023 deployment of an architecture with many backends.
11024
11025 Creating a SSL certificate is an expensive operation, so a LRU cache is used
11026 to store forged certificates (see 'tune.ssl.ssl-ctx-cache-size'). It
Davor Ocelice9ed2812017-12-25 17:49:28 +010011027 increases the HAProxy's memory footprint to reduce latency when the same
Christopher Faulet31af49d2015-06-09 17:29:50 +020011028 certificate is used many times.
11029
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011030gid <gid>
11031 Sets the group of the UNIX sockets to the designated system gid. It can also
11032 be set by default in the global section's "unix-bind" statement. Note that
11033 some platforms simply ignore this. This setting is equivalent to the "group"
11034 setting except that the group ID is used instead of its name. This setting is
11035 ignored by non UNIX sockets.
11036
11037group <group>
11038 Sets the group of the UNIX sockets to the designated system group. It can
11039 also be set by default in the global section's "unix-bind" statement. Note
11040 that some platforms simply ignore this. This setting is equivalent to the
11041 "gid" setting except that the group name is used instead of its gid. This
11042 setting is ignored by non UNIX sockets.
11043
11044id <id>
11045 Fixes the socket ID. By default, socket IDs are automatically assigned, but
11046 sometimes it is more convenient to fix them to ease monitoring. This value
11047 must be strictly positive and unique within the listener/frontend. This
11048 option can only be used when defining only a single socket.
11049
11050interface <interface>
Lukas Tribusfce2e962013-02-12 22:13:19 +010011051 Restricts the socket to a specific interface. When specified, only packets
11052 received from that particular interface are processed by the socket. This is
11053 currently only supported on Linux. The interface must be a primary system
11054 interface, not an aliased interface. It is also possible to bind multiple
11055 frontends to the same address if they are bound to different interfaces. Note
11056 that binding to a network interface requires root privileges. This parameter
Jérôme Magnin61275192018-02-07 11:39:58 +010011057 is only compatible with TCPv4/TCPv6 sockets. When specified, return traffic
11058 uses the same interface as inbound traffic, and its associated routing table,
11059 even if there are explicit routes through different interfaces configured.
11060 This can prove useful to address asymmetric routing issues when the same
11061 client IP addresses need to be able to reach frontends hosted on different
11062 interfaces.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011063
Willy Tarreauabb175f2012-09-24 12:43:26 +020011064level <level>
11065 This setting is used with the stats sockets only to restrict the nature of
11066 the commands that can be issued on the socket. It is ignored by other
11067 sockets. <level> can be one of :
Davor Ocelice9ed2812017-12-25 17:49:28 +010011068 - "user" is the least privileged level; only non-sensitive stats can be
Willy Tarreauabb175f2012-09-24 12:43:26 +020011069 read, and no change is allowed. It would make sense on systems where it
11070 is not easy to restrict access to the socket.
11071 - "operator" is the default level and fits most common uses. All data can
Davor Ocelice9ed2812017-12-25 17:49:28 +010011072 be read, and only non-sensitive changes are permitted (e.g. clear max
Willy Tarreauabb175f2012-09-24 12:43:26 +020011073 counters).
Davor Ocelice9ed2812017-12-25 17:49:28 +010011074 - "admin" should be used with care, as everything is permitted (e.g. clear
Willy Tarreauabb175f2012-09-24 12:43:26 +020011075 all counters).
11076
Andjelko Iharosc4df59e2017-07-20 11:59:48 +020011077severity-output <format>
11078 This setting is used with the stats sockets only to configure severity
11079 level output prepended to informational feedback messages. Severity
11080 level of messages can range between 0 and 7, conforming to syslog
11081 rfc5424. Valid and successful socket commands requesting data
11082 (i.e. "show map", "get acl foo" etc.) will never have a severity level
11083 prepended. It is ignored by other sockets. <format> can be one of :
11084 - "none" (default) no severity level is prepended to feedback messages.
11085 - "number" severity level is prepended as a number.
11086 - "string" severity level is prepended as a string following the
11087 rfc5424 convention.
11088
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011089maxconn <maxconn>
11090 Limits the sockets to this number of concurrent connections. Extraneous
11091 connections will remain in the system's backlog until a connection is
11092 released. If unspecified, the limit will be the same as the frontend's
11093 maxconn. Note that in case of port ranges or multiple addresses, the same
11094 value will be applied to each socket. This setting enables different
11095 limitations on expensive sockets, for instance SSL entries which may easily
11096 eat all memory.
11097
11098mode <mode>
11099 Sets the octal mode used to define access permissions on the UNIX socket. It
11100 can also be set by default in the global section's "unix-bind" statement.
11101 Note that some platforms simply ignore this. This setting is ignored by non
11102 UNIX sockets.
11103
11104mss <maxseg>
11105 Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming
11106 connections. This can be used to force a lower MSS for certain specific
11107 ports, for instance for connections passing through a VPN. Note that this
11108 relies on a kernel feature which is theoretically supported under Linux but
11109 was buggy in all versions prior to 2.6.28. It may or may not work on other
11110 operating systems. It may also not change the advertised value but change the
11111 effective size of outgoing segments. The commonly advertised value for TCPv4
11112 over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is
11113 positive, it will be used as the advertised MSS. If it is negative, it will
11114 indicate by how much to reduce the incoming connection's advertised MSS for
11115 outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.
11116
11117name <name>
11118 Sets an optional name for these sockets, which will be reported on the stats
11119 page.
11120
Willy Tarreaud72f0f32015-10-13 14:50:22 +020011121namespace <name>
11122 On Linux, it is possible to specify which network namespace a socket will
11123 belong to. This directive makes it possible to explicitly bind a listener to
11124 a namespace different from the default one. Please refer to your operating
11125 system's documentation to find more details about network namespaces.
11126
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011127nice <nice>
11128 Sets the 'niceness' of connections initiated from the socket. Value must be
11129 in the range -1024..1024 inclusive, and defaults to zero. Positive values
11130 means that such connections are more friendly to others and easily offer
11131 their place in the scheduler. On the opposite, negative values mean that
11132 connections want to run with a higher priority than others. The difference
11133 only happens under high loads when the system is close to saturation.
11134 Negative values are appropriate for low-latency or administration services,
11135 and high values are generally recommended for CPU intensive tasks such as SSL
11136 processing or bulk transfers which are less sensible to latency. For example,
11137 it may make sense to use a positive value for an SMTP socket and a negative
11138 one for an RDP socket.
11139
Emmanuel Hocdet174dfe52017-07-28 15:01:05 +020011140no-ca-names
11141 This setting is only available when support for OpenSSL was built in. It
11142 prevents from send CA names in server hello message when ca-file is used.
11143
Emeric Brun9b3009b2012-10-05 11:55:06 +020011144no-sslv3
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011145 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011146 disables support for SSLv3 on any sockets instantiated from the listener when
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011147 SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011148 be enabled using any configuration option. This option is also available on
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011149 global statement "ssl-default-bind-options". Use "ssl-min-ver" and
11150 "ssl-max-ver" instead.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011151
Emeric Brun90ad8722012-10-02 14:00:59 +020011152no-tls-tickets
11153 This setting is only available when support for OpenSSL was built in. It
11154 disables the stateless session resumption (RFC 5077 TLS Ticket
11155 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011156 session resumption is more expensive in CPU usage. This option is also
11157 available on global statement "ssl-default-bind-options".
Emeric Brun90ad8722012-10-02 14:00:59 +020011158
Emeric Brun9b3009b2012-10-05 11:55:06 +020011159no-tlsv10
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011160 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011161 disables support for TLSv1.0 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011162 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011163 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011164 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
11165 and "ssl-max-ver" instead.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011166
Emeric Brun9b3009b2012-10-05 11:55:06 +020011167no-tlsv11
Emeric Brunf5da4932012-09-28 19:42:54 +020011168 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011169 disables support for TLSv1.1 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011170 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011171 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011172 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
11173 and "ssl-max-ver" instead.
Emeric Brunf5da4932012-09-28 19:42:54 +020011174
Emeric Brun9b3009b2012-10-05 11:55:06 +020011175no-tlsv12
Emeric Brunf5da4932012-09-28 19:42:54 +020011176 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011177 disables support for TLSv1.2 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011178 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011179 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011180 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
11181 and "ssl-max-ver" instead.
Emeric Brunf5da4932012-09-28 19:42:54 +020011182
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011183no-tlsv13
11184 This setting is only available when support for OpenSSL was built in. It
11185 disables support for TLSv1.3 on any sockets instantiated from the listener
11186 when SSL is supported. Note that SSLv2 is forced disabled in the code and
11187 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011188 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
11189 and "ssl-max-ver" instead.
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011190
Willy Tarreau6c9a3d52012-10-18 18:57:14 +020011191npn <protocols>
11192 This enables the NPN TLS extension and advertises the specified protocol list
11193 as supported on top of NPN. The protocol list consists in a comma-delimited
11194 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
John Roeslerfb2fce12019-07-10 15:45:51 -050011195 This requires that the SSL library is built with support for TLS extensions
Willy Tarreauab861d32013-04-02 02:30:41 +020011196 enabled (check with haproxy -vv). Note that the NPN extension has been
Willy Tarreau95c4e142017-11-26 12:18:55 +010011197 replaced with the ALPN extension (see the "alpn" keyword), though this one is
11198 only available starting with OpenSSL 1.0.2. If HTTP/2 is desired on an older
11199 version of OpenSSL, NPN might still be used as most clients still support it
11200 at the time of writing this. It is possible to enable both NPN and ALPN
11201 though it probably doesn't make any sense out of testing.
Willy Tarreau6c9a3d52012-10-18 18:57:14 +020011202
Lukas Tribus53ae85c2017-05-04 15:45:40 +000011203prefer-client-ciphers
11204 Use the client's preference when selecting the cipher suite, by default
11205 the server's preference is enforced. This option is also available on
11206 global statement "ssl-default-bind-options".
Lukas Tribus926594f2018-05-18 17:55:57 +020011207 Note that with OpenSSL >= 1.1.1 ChaCha20-Poly1305 is reprioritized anyway
11208 (without setting this option), if a ChaCha20-Poly1305 cipher is at the top of
11209 the client cipher list.
Lukas Tribus53ae85c2017-05-04 15:45:40 +000011210
Christopher Fauletc644fa92017-11-23 22:44:11 +010011211process <process-set>[/<thread-set>]
Willy Tarreaua36b3242019-02-02 13:14:34 +010011212 This restricts the list of processes or threads on which this listener is
Christopher Fauletc644fa92017-11-23 22:44:11 +010011213 allowed to run. It does not enforce any process but eliminates those which do
Davor Ocelice9ed2812017-12-25 17:49:28 +010011214 not match. If the frontend uses a "bind-process" setting, the intersection
Christopher Fauletc644fa92017-11-23 22:44:11 +010011215 between the two is applied. If in the end the listener is not allowed to run
11216 on any remaining process, a warning is emitted, and the listener will either
11217 run on the first process of the listener if a single process was specified,
11218 or on all of its processes if multiple processes were specified. If a thread
Davor Ocelice9ed2812017-12-25 17:49:28 +010011219 set is specified, it limits the threads allowed to process incoming
Willy Tarreaua36b3242019-02-02 13:14:34 +010011220 connections for this listener, for the the process set. If multiple processes
11221 and threads are configured, a warning is emitted, as it either results from a
11222 configuration error or a misunderstanding of these models. For the unlikely
11223 case where several ranges are needed, this directive may be repeated.
11224 <process-set> and <thread-set> must use the format
Christopher Fauletc644fa92017-11-23 22:44:11 +010011225
11226 all | odd | even | number[-[number]]
11227
11228 Ranges can be partially defined. The higher bound can be omitted. In such
11229 case, it is replaced by the corresponding maximum value. The main purpose of
11230 this directive is to be used with the stats sockets and have one different
11231 socket per process. The second purpose is to have multiple bind lines sharing
11232 the same IP:port but not the same process in a listener, so that the system
11233 can distribute the incoming connections into multiple queues and allow a
11234 smoother inter-process load balancing. Currently Linux 3.9 and above is known
11235 for supporting this. See also "bind-process" and "nbproc".
Willy Tarreau6ae1ba62014-05-07 19:01:58 +020011236
Christopher Fauleta717b992018-04-10 14:43:00 +020011237proto <name>
11238 Forces the multiplexer's protocol to use for the incoming connections. It
11239 must be compatible with the mode of the frontend (TCP or HTTP). It must also
11240 be usable on the frontend side. The list of available protocols is reported
11241 in haproxy -vv.
11242 Idea behind this optipon is to bypass the selection of the best multiplexer's
11243 protocol for all connections instantiated from this listening socket. For
Joseph Herlant71b4b152018-11-13 16:55:16 -080011244 instance, it is possible to force the http/2 on clear TCP by specifying "proto
Christopher Fauleta717b992018-04-10 14:43:00 +020011245 h2" on the bind line.
11246
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011247ssl
11248 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011249 enables SSL deciphering on connections instantiated from this listener. A
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011250 certificate is necessary (see "crt" above). All contents in the buffers will
11251 appear in clear text, so that ACLs and HTTP processing will only have access
Emmanuel Hocdetbd695fe2017-05-15 15:53:41 +020011252 to deciphered contents. SSLv3 is disabled per default, use "ssl-min-ver SSLv3"
11253 to enable it.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011254
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011255ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
11256 This option enforces use of <version> or lower on SSL connections instantiated
11257 from this listener. This option is also available on global statement
11258 "ssl-default-bind-options". See also "ssl-min-ver".
11259
11260ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
11261 This option enforces use of <version> or upper on SSL connections instantiated
11262 from this listener. This option is also available on global statement
11263 "ssl-default-bind-options". See also "ssl-max-ver".
11264
Emmanuel Hocdet65623372013-01-24 17:17:15 +010011265strict-sni
11266 This setting is only available when support for OpenSSL was built in. The
11267 SSL/TLS negotiation is allow only if the client provided an SNI which match
11268 a certificate. The default certificate is not used.
11269 See the "crt" option for more information.
11270
Willy Tarreau2af207a2015-02-04 00:45:58 +010011271tcp-ut <delay>
Tim Düsterhus4896c442016-11-29 02:15:19 +010011272 Sets the TCP User Timeout for all incoming connections instantiated from this
Willy Tarreau2af207a2015-02-04 00:45:58 +010011273 listening socket. This option is available on Linux since version 2.6.37. It
11274 allows haproxy to configure a timeout for sockets which contain data not
Davor Ocelice9ed2812017-12-25 17:49:28 +010011275 receiving an acknowledgment for the configured delay. This is especially
Willy Tarreau2af207a2015-02-04 00:45:58 +010011276 useful on long-lived connections experiencing long idle periods such as
11277 remote terminals or database connection pools, where the client and server
11278 timeouts must remain high to allow a long period of idle, but where it is
11279 important to detect that the client has disappeared in order to release all
11280 resources associated with its connection (and the server's session). The
11281 argument is a delay expressed in milliseconds by default. This only works
11282 for regular TCP connections, and is ignored for other protocols.
11283
Willy Tarreau1c862c52012-10-05 16:21:00 +020011284tfo
Lukas Tribus0defb902013-02-13 23:35:39 +010011285 Is an optional keyword which is supported only on Linux kernels >= 3.7. It
Willy Tarreau1c862c52012-10-05 16:21:00 +020011286 enables TCP Fast Open on the listening socket, which means that clients which
11287 support this feature will be able to send a request and receive a response
11288 during the 3-way handshake starting from second connection, thus saving one
11289 round-trip after the first connection. This only makes sense with protocols
11290 that use high connection rates and where each round trip matters. This can
11291 possibly cause issues with many firewalls which do not accept data on SYN
11292 packets, so this option should only be enabled once well tested. This option
Lukas Tribus0999f762013-04-02 16:43:24 +020011293 is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may
11294 need to build HAProxy with USE_TFO=1 if your libc doesn't define
11295 TCP_FASTOPEN.
Willy Tarreau1c862c52012-10-05 16:21:00 +020011296
Nenad Merdanovic188ad3e2015-02-27 19:56:50 +010011297tls-ticket-keys <keyfile>
11298 Sets the TLS ticket keys file to load the keys from. The keys need to be 48
Emeric Brun9e754772019-01-10 17:51:55 +010011299 or 80 bytes long, depending if aes128 or aes256 is used, encoded with base64
11300 with one line per key (ex. openssl rand 80 | openssl base64 -A | xargs echo).
11301 The first key determines the key length used for next keys: you can't mix
11302 aes128 and aes256 keys. Number of keys is specified by the TLS_TICKETS_NO
11303 build option (default 3) and at least as many keys need to be present in
11304 the file. Last TLS_TICKETS_NO keys will be used for decryption and the
11305 penultimate one for encryption. This enables easy key rotation by just
11306 appending new key to the file and reloading the process. Keys must be
11307 periodically rotated (ex. every 12h) or Perfect Forward Secrecy is
11308 compromised. It is also a good idea to keep the keys off any permanent
Nenad Merdanovic188ad3e2015-02-27 19:56:50 +010011309 storage such as hard drives (hint: use tmpfs and don't swap those files).
11310 Lifetime hint can be changed using tune.ssl.timeout.
11311
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011312transparent
11313 Is an optional keyword which is supported only on certain Linux kernels. It
11314 indicates that the addresses will be bound even if they do not belong to the
11315 local machine, and that packets targeting any of these addresses will be
11316 intercepted just as if the addresses were locally configured. This normally
11317 requires that IP forwarding is enabled. Caution! do not use this with the
11318 default address '*', as it would redirect any traffic for the specified port.
11319 This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1.
11320 This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on
11321 kernel version. Some distribution kernels include backports of the feature,
11322 so check for support with your vendor.
11323
Willy Tarreau77e3af92012-11-24 15:07:23 +010011324v4v6
11325 Is an optional keyword which is supported only on most recent systems
11326 including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4
11327 and IPv6 when it uses the default address. Doing so is sometimes necessary
11328 on systems which bind to IPv6 only by default. It has no effect on non-IPv6
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011329 sockets, and is overridden by the "v6only" option.
Willy Tarreau77e3af92012-11-24 15:07:23 +010011330
Willy Tarreau9b6700f2012-11-24 11:55:28 +010011331v6only
11332 Is an optional keyword which is supported only on most recent systems
11333 including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only
11334 when it uses the default address. Doing so is sometimes preferred to doing it
Willy Tarreau77e3af92012-11-24 15:07:23 +010011335 system-wide as it is per-listener. It has no effect on non-IPv6 sockets and
11336 has precedence over the "v4v6" option.
Willy Tarreau9b6700f2012-11-24 11:55:28 +010011337
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011338uid <uid>
11339 Sets the owner of the UNIX sockets to the designated system uid. It can also
11340 be set by default in the global section's "unix-bind" statement. Note that
11341 some platforms simply ignore this. This setting is equivalent to the "user"
11342 setting except that the user numeric ID is used instead of its name. This
11343 setting is ignored by non UNIX sockets.
11344
11345user <user>
11346 Sets the owner of the UNIX sockets to the designated system user. It can also
11347 be set by default in the global section's "unix-bind" statement. Note that
11348 some platforms simply ignore this. This setting is equivalent to the "uid"
11349 setting except that the user name is used instead of its uid. This setting is
11350 ignored by non UNIX sockets.
11351
Emeric Brun1a073b42012-09-28 17:07:34 +020011352verify [none|optional|required]
11353 This setting is only available when support for OpenSSL was built in. If set
11354 to 'none', client certificate is not requested. This is the default. In other
11355 cases, a client certificate is requested. If the client does not provide a
11356 certificate after the request and if 'verify' is set to 'required', then the
11357 handshake is aborted, while it would have succeeded if set to 'optional'. The
Emeric Brunfd33a262012-10-11 16:28:27 +020011358 certificate provided by the client is always verified using CAs from
11359 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
11360 is aborted, regardless of the 'verify' option, unless the error code exactly
11361 matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020011362
Willy Tarreaub6205fd2012-09-24 12:27:33 +0200113635.2. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +010011364------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020011365
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010011366The "server" and "default-server" keywords support a certain number of settings
11367which are all passed as arguments on the server line. The order in which those
11368arguments appear does not count, and they are all optional. Some of those
11369settings are single words (booleans) while others expect one or several values
11370after them. In this case, the values must immediately follow the setting name.
11371Except default-server, all those settings must be specified after the server's
11372address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +020011373
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011374 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010011375 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +020011376
Frédéric Lécailled2376272017-03-21 18:52:12 +010011377Note that all these settings are supported both by "server" and "default-server"
11378keywords, except "id" which is only supported by "server".
11379
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011380The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +010011381
Willy Tarreauceb4ac92012-04-28 00:41:46 +020011382addr <ipv4|ipv6>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011383 Using the "addr" parameter, it becomes possible to use a different IP address
Baptiste Assmann13f83532016-03-06 23:14:36 +010011384 to send health-checks or to probe the agent-check. On some servers, it may be
11385 desirable to dedicate an IP address to specific component able to perform
11386 complex tests which are more suitable to health-checks than the application.
11387 This parameter is ignored if the "check" parameter is not set. See also the
11388 "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +020011389
Simon Hormand60d6912013-11-25 10:46:36 +090011390agent-check
11391 Enable an auxiliary agent check which is run independently of a regular
Willy Tarreau81f5d942013-12-09 20:51:51 +010011392 health check. An agent health check is performed by making a TCP connection
Willy Tarreau7a0139e2018-12-16 08:42:56 +010011393 to the port set by the "agent-port" parameter and reading an ASCII string
11394 terminated by the first '\r' or '\n' met. The string is made of a series of
11395 words delimited by spaces, tabs or commas in any order, each consisting of :
Simon Hormand60d6912013-11-25 10:46:36 +090011396
Willy Tarreau81f5d942013-12-09 20:51:51 +010011397 - An ASCII representation of a positive integer percentage, e.g. "75%".
Simon Hormand60d6912013-11-25 10:46:36 +090011398 Values in this format will set the weight proportional to the initial
Willy Tarreauc5af3a62014-10-07 15:27:33 +020011399 weight of a server as configured when haproxy starts. Note that a zero
11400 weight is reported on the stats page as "DRAIN" since it has the same
11401 effect on the server (it's removed from the LB farm).
Simon Hormand60d6912013-11-25 10:46:36 +090011402
Davor Ocelice9ed2812017-12-25 17:49:28 +010011403 - The string "maxconn:" followed by an integer (no space between). Values
11404 in this format will set the maxconn of a server. The maximum number of
11405 connections advertised needs to be multiplied by the number of load
11406 balancers and different backends that use this health check to get the
11407 total number of connections the server might receive. Example: maxconn:30
Nenad Merdanovic174dd372016-04-24 23:10:06 +020011408
Willy Tarreau81f5d942013-12-09 20:51:51 +010011409 - The word "ready". This will turn the server's administrative state to the
Davor Ocelice9ed2812017-12-25 17:49:28 +010011410 READY mode, thus canceling any DRAIN or MAINT state
Simon Hormand60d6912013-11-25 10:46:36 +090011411
Willy Tarreau81f5d942013-12-09 20:51:51 +010011412 - The word "drain". This will turn the server's administrative state to the
11413 DRAIN mode, thus it will not accept any new connections other than those
11414 that are accepted via persistence.
Simon Hormand60d6912013-11-25 10:46:36 +090011415
Willy Tarreau81f5d942013-12-09 20:51:51 +010011416 - The word "maint". This will turn the server's administrative state to the
11417 MAINT mode, thus it will not accept any new connections at all, and health
11418 checks will be stopped.
Simon Hormand60d6912013-11-25 10:46:36 +090011419
Willy Tarreau81f5d942013-12-09 20:51:51 +010011420 - The words "down", "failed", or "stopped", optionally followed by a
11421 description string after a sharp ('#'). All of these mark the server's
11422 operating state as DOWN, but since the word itself is reported on the stats
11423 page, the difference allows an administrator to know if the situation was
11424 expected or not : the service may intentionally be stopped, may appear up
Davor Ocelice9ed2812017-12-25 17:49:28 +010011425 but fail some validity tests, or may be seen as down (e.g. missing process,
Willy Tarreau81f5d942013-12-09 20:51:51 +010011426 or port not responding).
Simon Hormand60d6912013-11-25 10:46:36 +090011427
Willy Tarreau81f5d942013-12-09 20:51:51 +010011428 - The word "up" sets back the server's operating state as UP if health checks
11429 also report that the service is accessible.
Simon Hormand60d6912013-11-25 10:46:36 +090011430
Willy Tarreau81f5d942013-12-09 20:51:51 +010011431 Parameters which are not advertised by the agent are not changed. For
11432 example, an agent might be designed to monitor CPU usage and only report a
11433 relative weight and never interact with the operating status. Similarly, an
11434 agent could be designed as an end-user interface with 3 radio buttons
11435 allowing an administrator to change only the administrative state. However,
11436 it is important to consider that only the agent may revert its own actions,
11437 so if a server is set to DRAIN mode or to DOWN state using the agent, the
11438 agent must implement the other equivalent actions to bring the service into
11439 operations again.
Simon Hormand60d6912013-11-25 10:46:36 +090011440
Simon Horman2f1f9552013-11-25 10:46:37 +090011441 Failure to connect to the agent is not considered an error as connectivity
11442 is tested by the regular health check which is enabled by the "check"
Willy Tarreau81f5d942013-12-09 20:51:51 +010011443 parameter. Warning though, it is not a good idea to stop an agent after it
11444 reports "down", since only an agent reporting "up" will be able to turn the
11445 server up again. Note that the CLI on the Unix stats socket is also able to
Willy Tarreau989222a2016-01-15 10:26:26 +010011446 force an agent's result in order to work around a bogus agent if needed.
Simon Horman2f1f9552013-11-25 10:46:37 +090011447
Willy Tarreau81f5d942013-12-09 20:51:51 +010011448 Requires the "agent-port" parameter to be set. See also the "agent-inter"
Frédéric Lécailled2376272017-03-21 18:52:12 +010011449 and "no-agent-check" parameters.
Simon Hormand60d6912013-11-25 10:46:36 +090011450
James Brown55f9ff12015-10-21 18:19:05 -070011451agent-send <string>
11452 If this option is specified, haproxy will send the given string (verbatim)
11453 to the agent server upon connection. You could, for example, encode
11454 the backend name into this string, which would enable your agent to send
11455 different responses based on the backend. Make sure to include a '\n' if
11456 you want to terminate your request with a newline.
11457
Simon Hormand60d6912013-11-25 10:46:36 +090011458agent-inter <delay>
11459 The "agent-inter" parameter sets the interval between two agent checks
11460 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
11461
11462 Just as with every other time-based parameter, it may be entered in any
11463 other explicit unit among { us, ms, s, m, h, d }. The "agent-inter"
11464 parameter also serves as a timeout for agent checks "timeout check" is
11465 not set. In order to reduce "resonance" effects when multiple servers are
11466 hosted on the same hardware, the agent and health checks of all servers
11467 are started with a small time offset between them. It is also possible to
11468 add some random noise in the agent and health checks interval using the
11469 global "spread-checks" keyword. This makes sense for instance when a lot
11470 of backends use the same servers.
11471
11472 See also the "agent-check" and "agent-port" parameters.
11473
Misiek768d8602017-01-09 09:52:43 +010011474agent-addr <addr>
11475 The "agent-addr" parameter sets address for agent check.
11476
11477 You can offload agent-check to another target, so you can make single place
11478 managing status and weights of servers defined in haproxy in case you can't
11479 make self-aware and self-managing services. You can specify both IP or
11480 hostname, it will be resolved.
11481
Simon Hormand60d6912013-11-25 10:46:36 +090011482agent-port <port>
11483 The "agent-port" parameter sets the TCP port used for agent checks.
11484
11485 See also the "agent-check" and "agent-inter" parameters.
11486
Olivier Houchard8cb2d2e2019-05-06 18:58:48 +020011487allow-0rtt
11488 Allow sending early data to the server when using TLS 1.3.
Olivier Houchard22c9b442019-05-06 19:01:04 +020011489 Note that early data will be sent only if the client used early data, or
11490 if the backend uses "retry-on" with the "0rtt-rejected" keyword.
Olivier Houchard8cb2d2e2019-05-06 18:58:48 +020011491
Olivier Houchardc7566002018-11-20 23:33:50 +010011492alpn <protocols>
11493 This enables the TLS ALPN extension and advertises the specified protocol
11494 list as supported on top of ALPN. The protocol list consists in a comma-
11495 delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
John Roeslerfb2fce12019-07-10 15:45:51 -050011496 quotes). This requires that the SSL library is built with support for TLS
Olivier Houchardc7566002018-11-20 23:33:50 +010011497 extensions enabled (check with haproxy -vv). The ALPN extension replaces the
11498 initial NPN extension. ALPN is required to connect to HTTP/2 servers.
11499 Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the
11500 now obsolete NPN extension.
11501 If both HTTP/2 and HTTP/1.1 are expected to be supported, both versions can
11502 be advertised, in order of preference, like below :
11503
11504 server 127.0.0.1:443 ssl crt pub.pem alpn h2,http/1.1
11505
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011506backup
11507 When "backup" is present on a server line, the server is only used in load
11508 balancing when all other non-backup servers are unavailable. Requests coming
11509 with a persistence cookie referencing the server will always be served
11510 though. By default, only the first operational backup server is used, unless
Frédéric Lécailled2376272017-03-21 18:52:12 +010011511 the "allbackups" option is set in the backend. See also the "no-backup" and
11512 "allbackups" options.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011513
Emeric Brunef42d922012-10-11 16:11:36 +020011514ca-file <cafile>
11515 This setting is only available when support for OpenSSL was built in. It
11516 designates a PEM file from which to load CA certificates used to verify
11517 server's certificate.
11518
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011519check
11520 This option enables health checks on the server. By default, a server is
Patrick Mézardb7aeec62012-01-22 16:01:22 +010011521 always considered available. If "check" is set, the server is available when
11522 accepting periodic TCP connections, to ensure that it is really able to serve
11523 requests. The default address and port to send the tests to are those of the
11524 server, and the default source is the same as the one defined in the
11525 backend. It is possible to change the address using the "addr" parameter, the
11526 port using the "port" parameter, the source address using the "source"
11527 address, and the interval and timers using the "inter", "rise" and "fall"
Simon Hormanafc47ee2013-11-25 10:46:35 +090011528 parameters. The request method is define in the backend using the "httpchk",
11529 "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please
Frédéric Lécailled2376272017-03-21 18:52:12 +010011530 refer to those options and parameters for more information. See also
11531 "no-check" option.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011532
Willy Tarreau6c16adc2012-10-05 00:04:16 +020011533check-send-proxy
11534 This option forces emission of a PROXY protocol line with outgoing health
11535 checks, regardless of whether the server uses send-proxy or not for the
11536 normal traffic. By default, the PROXY protocol is enabled for health checks
11537 if it is already enabled for normal traffic and if no "port" nor "addr"
11538 directive is present. However, if such a directive is present, the
11539 "check-send-proxy" option needs to be used to force the use of the
11540 protocol. See also the "send-proxy" option for more information.
11541
Olivier Houchard92150142018-12-21 19:47:01 +010011542check-alpn <protocols>
11543 Defines which protocols to advertise with ALPN. The protocol list consists in
11544 a comma-delimited list of protocol names, for instance: "http/1.1,http/1.0"
11545 (without quotes). If it is not set, the server ALPN is used.
11546
Jérôme Magninae9bb762018-12-09 16:08:26 +010011547check-sni <sni>
Olivier Houchard9130a962017-10-17 17:33:43 +020011548 This option allows you to specify the SNI to be used when doing health checks
Jérôme Magninae9bb762018-12-09 16:08:26 +010011549 over SSL. It is only possible to use a string to set <sni>. If you want to
11550 set a SNI for proxied traffic, see "sni".
Olivier Houchard9130a962017-10-17 17:33:43 +020011551
Willy Tarreau763a95b2012-10-04 23:15:39 +020011552check-ssl
11553 This option forces encryption of all health checks over SSL, regardless of
11554 whether the server uses SSL or not for the normal traffic. This is generally
11555 used when an explicit "port" or "addr" directive is specified and SSL health
11556 checks are not inherited. It is important to understand that this option
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011557 inserts an SSL transport layer below the checks, so that a simple TCP connect
Willy Tarreau763a95b2012-10-04 23:15:39 +020011558 check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
11559 common use is to send HTTPS checks by combining "httpchk" with SSL checks.
Davor Ocelice9ed2812017-12-25 17:49:28 +010011560 All SSL settings are common to health checks and traffic (e.g. ciphers).
Frédéric Lécailled2376272017-03-21 18:52:12 +010011561 See the "ssl" option for more information and "no-check-ssl" to disable
11562 this option.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011563
Alexander Liu2a54bb72019-05-22 19:44:48 +080011564check-via-socks4
John Roeslerfb2fce12019-07-10 15:45:51 -050011565 This option enables outgoing health checks using upstream socks4 proxy. By
Alexander Liu2a54bb72019-05-22 19:44:48 +080011566 default, the health checks won't go through socks tunnel even it was enabled
11567 for normal traffic.
11568
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011569ciphers <ciphers>
Dirkjan Bussink415150f2018-09-14 11:14:21 +020011570 This setting is only available when support for OpenSSL was built in. This
11571 option sets the string describing the list of cipher algorithms that is
11572 negotiated during the SSL/TLS handshake with the server. The format of the
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000011573 string is defined in "man 1 ciphers" from OpenSSL man pages. For background
11574 information and recommendations see e.g.
11575 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
11576 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
11577 cipher configuration, please check the "ciphersuites" keyword.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011578
Dirkjan Bussink415150f2018-09-14 11:14:21 +020011579ciphersuites <ciphersuites>
11580 This setting is only available when support for OpenSSL was built in and
11581 OpenSSL 1.1.1 or later was used to build HAProxy. This option sets the string
11582 describing the list of cipher algorithms that is negotiated during the TLS
11583 1.3 handshake with the server. The format of the string is defined in
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000011584 "man 1 ciphers" from OpenSSL man pages under the "ciphersuites" section.
11585 For cipher configuration for TLSv1.2 and earlier, please check the "ciphers"
11586 keyword.
Dirkjan Bussink415150f2018-09-14 11:14:21 +020011587
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011588cookie <value>
11589 The "cookie" parameter sets the cookie value assigned to the server to
11590 <value>. This value will be checked in incoming requests, and the first
11591 operational server possessing the same value will be selected. In return, in
11592 cookie insertion or rewrite modes, this value will be assigned to the cookie
11593 sent to the client. There is nothing wrong in having several servers sharing
11594 the same cookie value, and it is in fact somewhat common between normal and
11595 backup servers. See also the "cookie" keyword in backend section.
11596
Emeric Brunef42d922012-10-11 16:11:36 +020011597crl-file <crlfile>
11598 This setting is only available when support for OpenSSL was built in. It
11599 designates a PEM file from which to load certificate revocation list used
11600 to verify server's certificate.
11601
Emeric Bruna7aa3092012-10-26 12:58:00 +020011602crt <cert>
11603 This setting is only available when support for OpenSSL was built in.
11604 It designates a PEM file from which to load both a certificate and the
11605 associated private key. This file can be built by concatenating both PEM
11606 files into one. This certificate will be sent if the server send a client
11607 certificate request.
11608
Willy Tarreau96839092010-03-29 10:02:24 +020011609disabled
11610 The "disabled" keyword starts the server in the "disabled" state. That means
11611 that it is marked down in maintenance mode, and no connection other than the
11612 ones allowed by persist mode will reach it. It is very well suited to setup
11613 new servers, because normal traffic will never reach them, while it is still
11614 possible to test the service by making use of the force-persist mechanism.
Frédéric Lécailled2376272017-03-21 18:52:12 +010011615 See also "enabled" setting.
Willy Tarreau96839092010-03-29 10:02:24 +020011616
Frédéric Lécailled2376272017-03-21 18:52:12 +010011617enabled
11618 This option may be used as 'server' setting to reset any 'disabled'
11619 setting which would have been inherited from 'default-server' directive as
11620 default value.
11621 It may also be used as 'default-server' setting to reset any previous
11622 'default-server' 'disabled' setting.
Willy Tarreau96839092010-03-29 10:02:24 +020011623
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011624error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +010011625 If health observing is enabled, the "error-limit" parameter specifies the
11626 number of consecutive errors that triggers event selected by the "on-error"
11627 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011628
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011629 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011630
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011631fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011632 The "fall" parameter states that a server will be considered as dead after
11633 <count> consecutive unsuccessful health checks. This value defaults to 3 if
11634 unspecified. See also the "check", "inter" and "rise" parameters.
11635
Emeric Brun8694b9a2012-10-05 14:39:07 +020011636force-sslv3
11637 This option enforces use of SSLv3 only when SSL is used to communicate with
11638 the server. SSLv3 is generally less expensive than the TLS counterparts for
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011639 high connection rates. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011640 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020011641
11642force-tlsv10
11643 This option enforces use of TLSv1.0 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011644 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011645 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020011646
11647force-tlsv11
11648 This option enforces use of TLSv1.1 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011649 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011650 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020011651
11652force-tlsv12
11653 This option enforces use of TLSv1.2 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011654 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011655 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020011656
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011657force-tlsv13
11658 This option enforces use of TLSv1.3 only when SSL is used to communicate with
11659 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011660 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011661
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011662id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +020011663 Set a persistent ID for the server. This ID must be positive and unique for
11664 the proxy. An unused ID will automatically be assigned if unset. The first
11665 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011666
Willy Tarreau6a031d12016-11-07 19:42:35 +010011667init-addr {last | libc | none | <ip>},[...]*
11668 Indicate in what order the server's address should be resolved upon startup
11669 if it uses an FQDN. Attempts are made to resolve the address by applying in
Davor Ocelice9ed2812017-12-25 17:49:28 +010011670 turn each of the methods mentioned in the comma-delimited list. The first
Willy Tarreau6a031d12016-11-07 19:42:35 +010011671 method which succeeds is used. If the end of the list is reached without
11672 finding a working method, an error is thrown. Method "last" suggests to pick
11673 the address which appears in the state file (see "server-state-file"). Method
11674 "libc" uses the libc's internal resolver (gethostbyname() or getaddrinfo()
11675 depending on the operating system and build options). Method "none"
11676 specifically indicates that the server should start without any valid IP
11677 address in a down state. It can be useful to ignore some DNS issues upon
11678 startup, waiting for the situation to get fixed later. Finally, an IP address
11679 (IPv4 or IPv6) may be provided. It can be the currently known address of the
Davor Ocelice9ed2812017-12-25 17:49:28 +010011680 server (e.g. filled by a configuration generator), or the address of a dummy
Willy Tarreau6a031d12016-11-07 19:42:35 +010011681 server used to catch old sessions and present them with a decent error
11682 message for example. When the "first" load balancing algorithm is used, this
11683 IP address could point to a fake server used to trigger the creation of new
11684 instances on the fly. This option defaults to "last,libc" indicating that the
11685 previous address found in the state file (if any) is used first, otherwise
11686 the libc's resolver is used. This ensures continued compatibility with the
Davor Ocelice9ed2812017-12-25 17:49:28 +010011687 historic behavior.
Willy Tarreau6a031d12016-11-07 19:42:35 +010011688
11689 Example:
11690 defaults
11691 # never fail on address resolution
11692 default-server init-addr last,libc,none
11693
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011694inter <delay>
11695fastinter <delay>
11696downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011697 The "inter" parameter sets the interval between two consecutive health checks
11698 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
11699 It is also possible to use "fastinter" and "downinter" to optimize delays
11700 between checks depending on the server state :
11701
Pieter Baauw44fc9df2015-09-17 21:30:46 +020011702 Server state | Interval used
11703 ----------------------------------------+----------------------------------
11704 UP 100% (non-transitional) | "inter"
11705 ----------------------------------------+----------------------------------
11706 Transitionally UP (going down "fall"), | "fastinter" if set,
11707 Transitionally DOWN (going up "rise"), | "inter" otherwise.
11708 or yet unchecked. |
11709 ----------------------------------------+----------------------------------
11710 DOWN 100% (non-transitional) | "downinter" if set,
11711 | "inter" otherwise.
11712 ----------------------------------------+----------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +010011713
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011714 Just as with every other time-based parameter, they can be entered in any
11715 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
11716 serves as a timeout for health checks sent to servers if "timeout check" is
11717 not set. In order to reduce "resonance" effects when multiple servers are
Simon Hormand60d6912013-11-25 10:46:36 +090011718 hosted on the same hardware, the agent and health checks of all servers
11719 are started with a small time offset between them. It is also possible to
11720 add some random noise in the agent and health checks interval using the
11721 global "spread-checks" keyword. This makes sense for instance when a lot
11722 of backends use the same servers.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011723
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011724maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011725 The "maxconn" parameter specifies the maximal number of concurrent
11726 connections that will be sent to this server. If the number of incoming
Tim Duesterhuscefbbd92019-11-27 22:35:27 +010011727 concurrent connections goes higher than this value, they will be queued,
11728 waiting for a slot to be released. This parameter is very important as it can
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011729 save fragile servers from going down under extreme loads. If a "minconn"
11730 parameter is specified, the limit becomes dynamic. The default value is "0"
11731 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
11732 the backend's "fullconn" keyword.
11733
Tim Duesterhuscefbbd92019-11-27 22:35:27 +010011734 In HTTP mode this parameter limits the number of concurrent requests instead
11735 of the number of connections. Multiple requests might be multiplexed over a
11736 single TCP connection to the server. As an example if you specify a maxconn
11737 of 50 you might see between 1 and 50 actual server connections, but no more
11738 than 50 concurrent requests.
11739
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011740maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011741 The "maxqueue" parameter specifies the maximal number of connections which
11742 will wait in the queue for this server. If this limit is reached, next
11743 requests will be redispatched to other servers instead of indefinitely
11744 waiting to be served. This will break persistence but may allow people to
11745 quickly re-log in when the server they try to connect to is dying. The
11746 default value is "0" which means the queue is unlimited. See also the
11747 "maxconn" and "minconn" parameters.
11748
Willy Tarreau9c538e02019-01-23 10:21:49 +010011749max-reuse <count>
11750 The "max-reuse" argument indicates the HTTP connection processors that they
11751 should not reuse a server connection more than this number of times to send
11752 new requests. Permitted values are -1 (the default), which disables this
11753 limit, or any positive value. Value zero will effectively disable keep-alive.
11754 This is only used to work around certain server bugs which cause them to leak
11755 resources over time. The argument is not necessarily respected by the lower
11756 layers as there might be technical limitations making it impossible to
11757 enforce. At least HTTP/2 connections to servers will respect it.
11758
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011759minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011760 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
11761 limit following the backend's load. The server will always accept at least
11762 <minconn> connections, never more than <maxconn>, and the limit will be on
11763 the ramp between both values when the backend has less than <fullconn>
11764 concurrent connections. This makes it possible to limit the load on the
11765 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011766 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011767 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011768
Willy Tarreaud72f0f32015-10-13 14:50:22 +020011769namespace <name>
11770 On Linux, it is possible to specify which network namespace a socket will
11771 belong to. This directive makes it possible to explicitly bind a server to
11772 a namespace different from the default one. Please refer to your operating
11773 system's documentation to find more details about network namespaces.
11774
Frédéric Lécailled2376272017-03-21 18:52:12 +010011775no-agent-check
11776 This option may be used as "server" setting to reset any "agent-check"
11777 setting which would have been inherited from "default-server" directive as
11778 default value.
11779 It may also be used as "default-server" setting to reset any previous
11780 "default-server" "agent-check" setting.
11781
11782no-backup
11783 This option may be used as "server" setting to reset any "backup"
11784 setting which would have been inherited from "default-server" directive as
11785 default value.
11786 It may also be used as "default-server" setting to reset any previous
11787 "default-server" "backup" setting.
11788
11789no-check
11790 This option may be used as "server" setting to reset any "check"
11791 setting which would have been inherited from "default-server" directive as
11792 default value.
11793 It may also be used as "default-server" setting to reset any previous
11794 "default-server" "check" setting.
11795
11796no-check-ssl
11797 This option may be used as "server" setting to reset any "check-ssl"
11798 setting which would have been inherited from "default-server" directive as
11799 default value.
11800 It may also be used as "default-server" setting to reset any previous
11801 "default-server" "check-ssl" setting.
11802
Frédéric Lécailled2376272017-03-21 18:52:12 +010011803no-send-proxy
11804 This option may be used as "server" setting to reset any "send-proxy"
11805 setting which would have been inherited from "default-server" directive as
11806 default value.
11807 It may also be used as "default-server" setting to reset any previous
11808 "default-server" "send-proxy" setting.
11809
11810no-send-proxy-v2
11811 This option may be used as "server" setting to reset any "send-proxy-v2"
11812 setting which would have been inherited from "default-server" directive as
11813 default value.
11814 It may also be used as "default-server" setting to reset any previous
11815 "default-server" "send-proxy-v2" setting.
11816
11817no-send-proxy-v2-ssl
11818 This option may be used as "server" setting to reset any "send-proxy-v2-ssl"
11819 setting which would have been inherited from "default-server" directive as
11820 default value.
11821 It may also be used as "default-server" setting to reset any previous
11822 "default-server" "send-proxy-v2-ssl" setting.
11823
11824no-send-proxy-v2-ssl-cn
11825 This option may be used as "server" setting to reset any "send-proxy-v2-ssl-cn"
11826 setting which would have been inherited from "default-server" directive as
11827 default value.
11828 It may also be used as "default-server" setting to reset any previous
11829 "default-server" "send-proxy-v2-ssl-cn" setting.
11830
11831no-ssl
11832 This option may be used as "server" setting to reset any "ssl"
11833 setting which would have been inherited from "default-server" directive as
11834 default value.
11835 It may also be used as "default-server" setting to reset any previous
11836 "default-server" "ssl" setting.
11837
Willy Tarreau2a3fb1c2015-02-05 16:47:07 +010011838no-ssl-reuse
11839 This option disables SSL session reuse when SSL is used to communicate with
11840 the server. It will force the server to perform a full handshake for every
11841 new connection. It's probably only useful for benchmarking, troubleshooting,
11842 and for paranoid users.
11843
Emeric Brun9b3009b2012-10-05 11:55:06 +020011844no-sslv3
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011845 This option disables support for SSLv3 when SSL is used to communicate with
11846 the server. Note that SSLv2 is disabled in the code and cannot be enabled
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011847 using any configuration option. Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011848
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020011849 Supported in default-server: No
11850
Emeric Brunf9c5c472012-10-11 15:28:34 +020011851no-tls-tickets
11852 This setting is only available when support for OpenSSL was built in. It
11853 disables the stateless session resumption (RFC 5077 TLS Ticket
11854 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011855 session resumption is more expensive in CPU usage for servers. This option
11856 is also available on global statement "ssl-default-server-options".
Frédéric Lécailled2376272017-03-21 18:52:12 +010011857 See also "tls-tickets".
Emeric Brunf9c5c472012-10-11 15:28:34 +020011858
Emeric Brun9b3009b2012-10-05 11:55:06 +020011859no-tlsv10
Emeric Brun8694b9a2012-10-05 14:39:07 +020011860 This option disables support for TLSv1.0 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020011861 the server. Note that SSLv2 is disabled in the code and cannot be enabled
11862 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011863 often makes sense to disable it when communicating with local servers. This
11864 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011865 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011866
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020011867 Supported in default-server: No
11868
Emeric Brun9b3009b2012-10-05 11:55:06 +020011869no-tlsv11
Emeric Brun8694b9a2012-10-05 14:39:07 +020011870 This option disables support for TLSv1.1 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020011871 the server. Note that SSLv2 is disabled in the code and cannot be enabled
11872 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011873 often makes sense to disable it when communicating with local servers. This
11874 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011875 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011876
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020011877 Supported in default-server: No
11878
Emeric Brun9b3009b2012-10-05 11:55:06 +020011879no-tlsv12
Emeric Brun8694b9a2012-10-05 14:39:07 +020011880 This option disables support for TLSv1.2 when SSL is used to communicate with
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011881 the server. Note that SSLv2 is disabled in the code and cannot be enabled
11882 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011883 often makes sense to disable it when communicating with local servers. This
11884 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011885 Use "ssl-min-ver" and "ssl-max-ver" instead.
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011886
11887 Supported in default-server: No
11888
11889no-tlsv13
11890 This option disables support for TLSv1.3 when SSL is used to communicate with
11891 the server. Note that SSLv2 is disabled in the code and cannot be enabled
11892 using any configuration option. TLSv1 is more expensive than SSLv3 so it
11893 often makes sense to disable it when communicating with local servers. This
11894 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011895 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011896
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020011897 Supported in default-server: No
11898
Frédéric Lécailled2376272017-03-21 18:52:12 +010011899no-verifyhost
11900 This option may be used as "server" setting to reset any "verifyhost"
11901 setting which would have been inherited from "default-server" directive as
11902 default value.
11903 It may also be used as "default-server" setting to reset any previous
11904 "default-server" "verifyhost" setting.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011905
Frédéric Lécaille1b9423d2019-07-04 14:19:06 +020011906no-tfo
11907 This option may be used as "server" setting to reset any "tfo"
11908 setting which would have been inherited from "default-server" directive as
11909 default value.
11910 It may also be used as "default-server" setting to reset any previous
11911 "default-server" "tfo" setting.
11912
Simon Hormanfa461682011-06-25 09:39:49 +090011913non-stick
11914 Never add connections allocated to this sever to a stick-table.
11915 This may be used in conjunction with backup to ensure that
11916 stick-table persistence is disabled for backup servers.
11917
Olivier Houchardc7566002018-11-20 23:33:50 +010011918npn <protocols>
11919 This enables the NPN TLS extension and advertises the specified protocol list
11920 as supported on top of NPN. The protocol list consists in a comma-delimited
11921 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
John Roeslerfb2fce12019-07-10 15:45:51 -050011922 This requires that the SSL library is built with support for TLS extensions
Olivier Houchardc7566002018-11-20 23:33:50 +010011923 enabled (check with haproxy -vv). Note that the NPN extension has been
11924 replaced with the ALPN extension (see the "alpn" keyword), though this one is
11925 only available starting with OpenSSL 1.0.2.
11926
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011927observe <mode>
11928 This option enables health adjusting based on observing communication with
11929 the server. By default this functionality is disabled and enabling it also
11930 requires to enable health checks. There are two supported modes: "layer4" and
11931 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
11932 significant. In layer7, which is only allowed for http proxies, responses
11933 received from server are verified, like valid/wrong http code, unparsable
Willy Tarreau150d1462012-03-10 08:19:02 +010011934 headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011935
11936 See also the "check", "on-error" and "error-limit".
11937
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011938on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011939 Select what should happen when enough consecutive errors are detected.
11940 Currently, four modes are available:
11941 - fastinter: force fastinter
11942 - fail-check: simulate a failed check, also forces fastinter (default)
11943 - sudden-death: simulate a pre-fatal failed health check, one more failed
11944 check will mark a server down, forces fastinter
11945 - mark-down: mark the server immediately down and force fastinter
11946
11947 See also the "check", "observe" and "error-limit".
11948
Simon Hormane0d1bfb2011-06-21 14:34:58 +090011949on-marked-down <action>
11950 Modify what occurs when a server is marked down.
11951 Currently one action is available:
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070011952 - shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
11953 all connections to the server are immediately terminated when the server
11954 goes down. It might be used if the health check detects more complex cases
11955 than a simple connection status, and long timeouts would cause the service
11956 to remain unresponsive for too long a time. For instance, a health check
11957 might detect that a database is stuck and that there's no chance to reuse
11958 existing connections anymore. Connections killed this way are logged with
11959 a 'D' termination code (for "Down").
Simon Hormane0d1bfb2011-06-21 14:34:58 +090011960
11961 Actions are disabled by default
11962
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070011963on-marked-up <action>
11964 Modify what occurs when a server is marked up.
11965 Currently one action is available:
11966 - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
11967 done only if the server is not in backup state and if it is not disabled
11968 (it must have an effective weight > 0). This can be used sometimes to force
11969 an active server to take all the traffic back after recovery when dealing
Davor Ocelice9ed2812017-12-25 17:49:28 +010011970 with long sessions (e.g. LDAP, SQL, ...). Doing this can cause more trouble
11971 than it tries to solve (e.g. incomplete transactions), so use this feature
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070011972 with extreme care. Sessions killed because a server comes up are logged
11973 with an 'U' termination code (for "Up").
11974
11975 Actions are disabled by default
11976
Olivier Houchard006e3102018-12-10 18:30:32 +010011977pool-max-conn <max>
11978 Set the maximum number of idling connections for a server. -1 means unlimited
11979 connections, 0 means no idle connections. The default is -1. When idle
11980 connections are enabled, orphaned idle connections which do not belong to any
11981 client session anymore are moved to a dedicated pool so that they remain
11982 usable by future clients. This only applies to connections that can be shared
11983 according to the same principles as those applying to "http-reuse".
11984
Olivier Houchardb7b3faa2018-12-14 18:15:36 +010011985pool-purge-delay <delay>
11986 Sets the delay to start purging idle connections. Each <delay> interval, half
Olivier Houcharda56eebf2019-03-19 16:44:02 +010011987 of the idle connections are closed. 0 means we don't keep any idle connection.
Willy Tarreaufb553652019-06-04 14:06:31 +020011988 The default is 5s.
Olivier Houchardb7b3faa2018-12-14 18:15:36 +010011989
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011990port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011991 Using the "port" parameter, it becomes possible to use a different port to
11992 send health-checks. On some servers, it may be desirable to dedicate a port
11993 to a specific component able to perform complex tests which are more suitable
11994 to health-checks than the application. It is common to run a simple script in
11995 inetd for instance. This parameter is ignored if the "check" parameter is not
11996 set. See also the "addr" parameter.
11997
Christopher Faulet8ed0a3e2018-04-10 14:45:45 +020011998proto <name>
11999
12000 Forces the multiplexer's protocol to use for the outgoing connections to this
12001 server. It must be compatible with the mode of the backend (TCP or HTTP). It
12002 must also be usable on the backend side. The list of available protocols is
12003 reported in haproxy -vv.
12004 Idea behind this optipon is to bypass the selection of the best multiplexer's
12005 protocol for all connections established to this server.
12006
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012007redir <prefix>
12008 The "redir" parameter enables the redirection mode for all GET and HEAD
12009 requests addressing this server. This means that instead of having HAProxy
12010 forward the request to the server, it will send an "HTTP 302" response with
12011 the "Location" header composed of this prefix immediately followed by the
12012 requested URI beginning at the leading '/' of the path component. That means
12013 that no trailing slash should be used after <prefix>. All invalid requests
12014 will be rejected, and all non-GET or HEAD requests will be normally served by
12015 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012016 mangling nor cookie insertion is possible in the response. However, cookies in
Davor Ocelice9ed2812017-12-25 17:49:28 +010012017 requests are still analyzed, making this solution completely usable to direct
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012018 users to a remote location in case of local disaster. Main use consists in
12019 increasing bandwidth for static servers by having the clients directly
12020 connect to them. Note: never use a relative location here, it would cause a
12021 loop between the client and HAProxy!
12022
12023 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
12024
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012025rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012026 The "rise" parameter states that a server will be considered as operational
12027 after <count> consecutive successful health checks. This value defaults to 2
12028 if unspecified. See also the "check", "inter" and "fall" parameters.
12029
Baptiste Assmann8e2d9432018-06-22 15:04:43 +020012030resolve-opts <option>,<option>,...
12031 Comma separated list of options to apply to DNS resolution linked to this
12032 server.
12033
12034 Available options:
12035
12036 * allow-dup-ip
12037 By default, HAProxy prevents IP address duplication in a backend when DNS
12038 resolution at runtime is in operation.
12039 That said, for some cases, it makes sense that two servers (in the same
12040 backend, being resolved by the same FQDN) have the same IP address.
12041 For such case, simply enable this option.
12042 This is the opposite of prevent-dup-ip.
12043
Daniel Corbettf8716912019-11-17 09:48:56 -050012044 * ignore-weight
12045 Ignore any weight that is set within an SRV record. This is useful when
12046 you would like to control the weights using an alternate method, such as
12047 using an "agent-check" or through the runtime api.
12048
Baptiste Assmann8e2d9432018-06-22 15:04:43 +020012049 * prevent-dup-ip
12050 Ensure HAProxy's default behavior is enforced on a server: prevent re-using
12051 an IP address already set to a server in the same backend and sharing the
12052 same fqdn.
12053 This is the opposite of allow-dup-ip.
12054
12055 Example:
12056 backend b_myapp
12057 default-server init-addr none resolvers dns
12058 server s1 myapp.example.com:80 check resolve-opts allow-dup-ip
12059 server s2 myapp.example.com:81 check resolve-opts allow-dup-ip
12060
12061 With the option allow-dup-ip set:
12062 * if the nameserver returns a single IP address, then both servers will use
12063 it
12064 * If the nameserver returns 2 IP addresses, then each server will pick up a
12065 different address
12066
12067 Default value: not set
12068
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012069resolve-prefer <family>
12070 When DNS resolution is enabled for a server and multiple IP addresses from
12071 different families are returned, HAProxy will prefer using an IP address
12072 from the family mentioned in the "resolve-prefer" parameter.
12073 Available families: "ipv4" and "ipv6"
12074
Baptiste Assmannc4aabae2015-08-04 22:43:06 +020012075 Default value: ipv6
12076
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020012077 Example:
12078
12079 server s1 app1.domain.com:80 resolvers mydns resolve-prefer ipv6
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012080
Thierry Fournierac88cfe2016-02-17 22:05:30 +010012081resolve-net <network>[,<network[,...]]
John Roeslerfb2fce12019-07-10 15:45:51 -050012082 This option prioritizes the choice of an ip address matching a network. This is
Thierry Fournierac88cfe2016-02-17 22:05:30 +010012083 useful with clouds to prefer a local ip. In some cases, a cloud high
Tim Düsterhus4896c442016-11-29 02:15:19 +010012084 availability service can be announced with many ip addresses on many
Davor Ocelice9ed2812017-12-25 17:49:28 +010012085 different datacenters. The latency between datacenter is not negligible, so
12086 this patch permits to prefer a local datacenter. If no address matches the
Thierry Fournierac88cfe2016-02-17 22:05:30 +010012087 configured network, another address is selected.
12088
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020012089 Example:
12090
12091 server s1 app1.domain.com:80 resolvers mydns resolve-net 10.0.0.0/8
Thierry Fournierac88cfe2016-02-17 22:05:30 +010012092
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012093resolvers <id>
12094 Points to an existing "resolvers" section to resolve current server's
12095 hostname.
12096
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020012097 Example:
12098
12099 server s1 app1.domain.com:80 check resolvers mydns
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012100
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020012101 See also section 5.3
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012102
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010012103send-proxy
12104 The "send-proxy" parameter enforces use of the PROXY protocol over any
12105 connection established to this server. The PROXY protocol informs the other
12106 end about the layer 3/4 addresses of the incoming connection, so that it can
12107 know the client's address or the public address it accessed to, whatever the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010012108 upper layer protocol. For connections accepted by an "accept-proxy" or
12109 "accept-netscaler-cip" listener, the advertised address will be used. Only
12110 TCPv4 and TCPv6 address families are supported. Other families such as
12111 Unix sockets, will report an UNKNOWN family. Servers using this option can
12112 fully be chained to another instance of haproxy listening with an
12113 "accept-proxy" setting. This setting must not be used if the server isn't
12114 aware of the protocol. When health checks are sent to the server, the PROXY
12115 protocol is automatically used when this option is set, unless there is an
12116 explicit "port" or "addr" directive, in which case an explicit
12117 "check-send-proxy" directive would also be needed to use the PROXY protocol.
Frédéric Lécailled2376272017-03-21 18:52:12 +010012118 See also the "no-send-proxy" option of this section and "accept-proxy" and
12119 "accept-netscaler-cip" option of the "bind" keyword.
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010012120
David Safb76832014-05-08 23:42:08 -040012121send-proxy-v2
12122 The "send-proxy-v2" parameter enforces use of the PROXY protocol version 2
12123 over any connection established to this server. The PROXY protocol informs
12124 the other end about the layer 3/4 addresses of the incoming connection, so
12125 that it can know the client's address or the public address it accessed to,
Emmanuel Hocdet404d9782017-10-24 10:55:14 +020012126 whatever the upper layer protocol. It also send ALPN information if an alpn
12127 have been negotiated. This setting must not be used if the server isn't aware
12128 of this version of the protocol. See also the "no-send-proxy-v2" option of
12129 this section and send-proxy" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040012130
Emmanuel Hocdetf643b802018-02-01 15:20:32 +010012131proxy-v2-options <option>[,<option>]*
12132 The "proxy-v2-options" parameter add option to send in PROXY protocol version
12133 2 when "send-proxy-v2" is used. Options available are "ssl" (see also
Emmanuel Hocdetfa8d0f12018-02-01 15:53:52 +010012134 send-proxy-v2-ssl), "cert-cn" (see also "send-proxy-v2-ssl-cn"), "ssl-cipher":
12135 name of the used cipher, "cert-sig": signature algorithm of the used
Emmanuel Hocdet253c3b72018-02-01 18:29:59 +010012136 certificate, "cert-key": key algorithm of the used certificate), "authority":
12137 host name value passed by the client (only sni from a tls connection is
Emmanuel Hocdet4399c752018-02-05 15:26:43 +010012138 supported), "crc32c": checksum of the proxy protocol v2 header.
Emmanuel Hocdetf643b802018-02-01 15:20:32 +010012139
David Safb76832014-05-08 23:42:08 -040012140send-proxy-v2-ssl
12141 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
12142 2 over any connection established to this server. The PROXY protocol informs
12143 the other end about the layer 3/4 addresses of the incoming connection, so
12144 that it can know the client's address or the public address it accessed to,
12145 whatever the upper layer protocol. In addition, the SSL information extension
12146 of the PROXY protocol is added to the PROXY protocol header. This setting
12147 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 +010012148 See also the "no-send-proxy-v2-ssl" option of this section and the
12149 "send-proxy-v2" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040012150
12151send-proxy-v2-ssl-cn
12152 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
12153 2 over any connection established to this server. The PROXY protocol informs
12154 the other end about the layer 3/4 addresses of the incoming connection, so
12155 that it can know the client's address or the public address it accessed to,
12156 whatever the upper layer protocol. In addition, the SSL information extension
12157 of the PROXY protocol, along along with the Common Name from the subject of
12158 the client certificate (if any), is added to the PROXY protocol header. This
12159 setting must not be used if the server isn't aware of this version of the
Davor Ocelice9ed2812017-12-25 17:49:28 +010012160 protocol. See also the "no-send-proxy-v2-ssl-cn" option of this section and
12161 the "send-proxy-v2" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040012162
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012163slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012164 The "slowstart" parameter for a server accepts a value in milliseconds which
12165 indicates after how long a server which has just come back up will run at
12166 full speed. Just as with every other time-based parameter, it can be entered
12167 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
12168 linearly from 0 to 100% during this time. The limitation applies to two
12169 parameters :
12170
12171 - maxconn: the number of connections accepted by the server will grow from 1
12172 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
12173
12174 - weight: when the backend uses a dynamic weighted algorithm, the weight
12175 grows linearly from 1 to 100%. In this case, the weight is updated at every
12176 health-check. For this reason, it is important that the "inter" parameter
12177 is smaller than the "slowstart", in order to maximize the number of steps.
12178
12179 The slowstart never applies when haproxy starts, otherwise it would cause
12180 trouble to running servers. It only applies when a server has been previously
12181 seen as failed.
12182
Willy Tarreau732eac42015-07-09 11:40:25 +020012183sni <expression>
12184 The "sni" parameter evaluates the sample fetch expression, converts it to a
12185 string and uses the result as the host name sent in the SNI TLS extension to
12186 the server. A typical use case is to send the SNI received from the client in
12187 a bridged HTTPS scenario, using the "ssl_fc_sni" sample fetch for the
Willy Tarreau2ab88672017-07-05 18:23:03 +020012188 expression, though alternatives such as req.hdr(host) can also make sense. If
12189 "verify required" is set (which is the recommended setting), the resulting
Willy Tarreauad92a9a2017-07-28 11:38:41 +020012190 name will also be matched against the server certificate's names. See the
Jérôme Magninb36a6d22018-12-09 16:03:40 +010012191 "verify" directive for more details. If you want to set a SNI for health
12192 checks, see the "check-sni" directive for more details.
Willy Tarreau732eac42015-07-09 11:40:25 +020012193
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020012194source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +020012195source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020012196source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012197 The "source" parameter sets the source address which will be used when
12198 connecting to the server. It follows the exact same parameters and principle
12199 as the backend "source" keyword, except that it only applies to the server
12200 referencing it. Please consult the "source" keyword for details.
12201
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020012202 Additionally, the "source" statement on a server line allows one to specify a
12203 source port range by indicating the lower and higher bounds delimited by a
12204 dash ('-'). Some operating systems might require a valid IP address when a
12205 source port range is specified. It is permitted to have the same IP/range for
12206 several servers. Doing so makes it possible to bypass the maximum of 64k
12207 total concurrent connections. The limit will then reach 64k connections per
12208 server.
12209
Lukas Tribus7d56c6d2016-09-13 09:51:15 +000012210 Since Linux 4.2/libc 2.23 IP_BIND_ADDRESS_NO_PORT is set for connections
12211 specifying the source address without port(s).
12212
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020012213ssl
Willy Tarreau44f65392013-06-25 07:56:20 +020012214 This option enables SSL ciphering on outgoing connections to the server. It
12215 is critical to verify server certificates using "verify" when using SSL to
12216 connect to servers, otherwise the communication is prone to trivial man in
12217 the-middle attacks rendering SSL useless. When this option is used, health
12218 checks are automatically sent in SSL too unless there is a "port" or an
12219 "addr" directive indicating the check should be sent to a different location.
Frédéric Lécailled2376272017-03-21 18:52:12 +010012220 See the "no-ssl" to disable "ssl" option and "check-ssl" option to force
12221 SSL health checks.
Willy Tarreau763a95b2012-10-04 23:15:39 +020012222
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012223ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
12224 This option enforces use of <version> or lower when SSL is used to communicate
12225 with the server. This option is also available on global statement
12226 "ssl-default-server-options". See also "ssl-min-ver".
12227
12228ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
12229 This option enforces use of <version> or upper when SSL is used to communicate
12230 with the server. This option is also available on global statement
12231 "ssl-default-server-options". See also "ssl-max-ver".
12232
Frédéric Lécailled2376272017-03-21 18:52:12 +010012233ssl-reuse
12234 This option may be used as "server" setting to reset any "no-ssl-reuse"
12235 setting which would have been inherited from "default-server" directive as
12236 default value.
12237 It may also be used as "default-server" setting to reset any previous
12238 "default-server" "no-ssl-reuse" setting.
12239
12240stick
12241 This option may be used as "server" setting to reset any "non-stick"
12242 setting which would have been inherited from "default-server" directive as
12243 default value.
12244 It may also be used as "default-server" setting to reset any previous
12245 "default-server" "non-stick" setting.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020012246
Alexander Liu2a54bb72019-05-22 19:44:48 +080012247socks4 <addr>:<port>
John Roeslerfb2fce12019-07-10 15:45:51 -050012248 This option enables upstream socks4 tunnel for outgoing connections to the
Alexander Liu2a54bb72019-05-22 19:44:48 +080012249 server. Using this option won't force the health check to go via socks4 by
12250 default. You will have to use the keyword "check-via-socks4" to enable it.
12251
Willy Tarreau163d4622015-10-13 16:16:41 +020012252tcp-ut <delay>
12253 Sets the TCP User Timeout for all outgoing connections to this server. This
12254 option is available on Linux since version 2.6.37. It allows haproxy to
12255 configure a timeout for sockets which contain data not receiving an
Davor Ocelice9ed2812017-12-25 17:49:28 +010012256 acknowledgment for the configured delay. This is especially useful on
Willy Tarreau163d4622015-10-13 16:16:41 +020012257 long-lived connections experiencing long idle periods such as remote
12258 terminals or database connection pools, where the client and server timeouts
12259 must remain high to allow a long period of idle, but where it is important to
12260 detect that the server has disappeared in order to release all resources
12261 associated with its connection (and the client's session). One typical use
12262 case is also to force dead server connections to die when health checks are
12263 too slow or during a soft reload since health checks are then disabled. The
12264 argument is a delay expressed in milliseconds by default. This only works for
12265 regular TCP connections, and is ignored for other protocols.
12266
Willy Tarreau034c88c2017-01-23 23:36:45 +010012267tfo
12268 This option enables using TCP fast open when connecting to servers, on
12269 systems that support it (currently only the Linux kernel >= 4.11).
12270 See the "tfo" bind option for more information about TCP fast open.
12271 Please note that when using tfo, you should also use the "conn-failure",
12272 "empty-response" and "response-timeout" keywords for "retry-on", or haproxy
Frédéric Lécaille1b9423d2019-07-04 14:19:06 +020012273 won't be able to retry the connection on failure. See also "no-tfo".
Willy Tarreau034c88c2017-01-23 23:36:45 +010012274
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012275track [<proxy>/]<server>
Willy Tarreau32091232014-05-16 13:52:00 +020012276 This option enables ability to set the current state of the server by tracking
12277 another one. It is possible to track a server which itself tracks another
12278 server, provided that at the end of the chain, a server has health checks
12279 enabled. If <proxy> is omitted the current one is used. If disable-on-404 is
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012280 used, it has to be enabled on both proxies.
12281
Frédéric Lécailled2376272017-03-21 18:52:12 +010012282tls-tickets
12283 This option may be used as "server" setting to reset any "no-tls-tickets"
12284 setting which would have been inherited from "default-server" directive as
12285 default value.
12286 It may also be used as "default-server" setting to reset any previous
12287 "default-server" "no-tlsv-tickets" setting.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012288
Emeric Brunef42d922012-10-11 16:11:36 +020012289verify [none|required]
12290 This setting is only available when support for OpenSSL was built in. If set
Emeric Brun850efd52014-01-29 12:24:34 +010012291 to 'none', server certificate is not verified. In the other case, The
Willy Tarreauad92a9a2017-07-28 11:38:41 +020012292 certificate provided by the server is verified using CAs from 'ca-file' and
12293 optional CRLs from 'crl-file' after having checked that the names provided in
Davor Ocelice9ed2812017-12-25 17:49:28 +010012294 the certificate's subject and subjectAlternateNames attributes match either
Willy Tarreauad92a9a2017-07-28 11:38:41 +020012295 the name passed using the "sni" directive, or if not provided, the static
12296 host name passed using the "verifyhost" directive. When no name is found, the
12297 certificate's names are ignored. For this reason, without SNI it's important
12298 to use "verifyhost". On verification failure the handshake is aborted. It is
12299 critically important to verify server certificates when using SSL to connect
12300 to servers, otherwise the communication is prone to trivial man-in-the-middle
12301 attacks rendering SSL totally useless. Unless "ssl_server_verify" appears in
12302 the global section, "verify" is set to "required" by default.
Emeric Brunef42d922012-10-11 16:11:36 +020012303
Evan Broderbe554312013-06-27 00:05:25 -070012304verifyhost <hostname>
12305 This setting is only available when support for OpenSSL was built in, and
Willy Tarreauad92a9a2017-07-28 11:38:41 +020012306 only takes effect if 'verify required' is also specified. This directive sets
12307 a default static hostname to check the server's certificate against when no
12308 SNI was used to connect to the server. If SNI is not used, this is the only
12309 way to enable hostname verification. This static hostname, when set, will
12310 also be used for health checks (which cannot provide an SNI value). If none
12311 of the hostnames in the certificate match the specified hostname, the
12312 handshake is aborted. The hostnames in the server-provided certificate may
12313 include wildcards. See also "verify", "sni" and "no-verifyhost" options.
Evan Broderbe554312013-06-27 00:05:25 -070012314
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012315weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012316 The "weight" parameter is used to adjust the server's weight relative to
12317 other servers. All servers will receive a load proportional to their weight
12318 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +020012319 load. The default weight is 1, and the maximal value is 256. A value of 0
12320 means the server will not participate in load-balancing but will still accept
12321 persistent connections. If this parameter is used to distribute the load
12322 according to server's capacity, it is recommended to start with values which
12323 can both grow and shrink, for instance between 10 and 100 to leave enough
12324 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012325
12326
Cyril Bonté46175dd2015-07-02 22:45:32 +0200123275.3. Server IP address resolution using DNS
12328-------------------------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012329
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012330HAProxy allows using a host name on the server line to retrieve its IP address
12331using name servers. By default, HAProxy resolves the name when parsing the
12332configuration file, at startup and cache the result for the process' life.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012333This is not sufficient in some cases, such as in Amazon where a server's IP
12334can change after a reboot or an ELB Virtual IP can change based on current
12335workload.
12336This chapter describes how HAProxy can be configured to process server's name
12337resolution at run time.
12338Whether run time server name resolution has been enable or not, HAProxy will
12339carry on doing the first resolution when parsing the configuration.
12340
12341
Cyril Bonté46175dd2015-07-02 22:45:32 +0200123425.3.1. Global overview
12343----------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012344
12345As we've seen in introduction, name resolution in HAProxy occurs at two
12346different steps of the process life:
12347
12348 1. when starting up, HAProxy parses the server line definition and matches a
12349 host name. It uses libc functions to get the host name resolved. This
12350 resolution relies on /etc/resolv.conf file.
12351
Christopher Faulet67957bd2017-09-27 11:00:59 +020012352 2. at run time, HAProxy performs periodically name resolutions for servers
12353 requiring DNS resolutions.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012354
12355A few other events can trigger a name resolution at run time:
12356 - when a server's health check ends up in a connection timeout: this may be
12357 because the server has a new IP address. So we need to trigger a name
12358 resolution to know this new IP.
12359
Christopher Faulet67957bd2017-09-27 11:00:59 +020012360When using resolvers, the server name can either be a hostname, or a SRV label.
Davor Ocelice9ed2812017-12-25 17:49:28 +010012361HAProxy considers anything that starts with an underscore as a SRV label. If a
Christopher Faulet67957bd2017-09-27 11:00:59 +020012362SRV label is specified, then the corresponding SRV records will be retrieved
12363from the DNS server, and the provided hostnames will be used. The SRV label
12364will be checked periodically, and if any server are added or removed, haproxy
12365will automatically do the same.
Olivier Houchardecfa18d2017-08-07 17:30:03 +020012366
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012367A few things important to notice:
John Roeslerfb2fce12019-07-10 15:45:51 -050012368 - all the name servers are queried in the meantime. HAProxy will process the
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012369 first valid response.
12370
12371 - a resolution is considered as invalid (NX, timeout, refused), when all the
12372 servers return an error.
12373
12374
Cyril Bonté46175dd2015-07-02 22:45:32 +0200123755.3.2. The resolvers section
12376----------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012377
12378This section is dedicated to host information related to name resolution in
Christopher Faulet67957bd2017-09-27 11:00:59 +020012379HAProxy. There can be as many as resolvers section as needed. Each section can
12380contain many name servers.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012381
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012382When multiple name servers are configured in a resolvers section, then HAProxy
12383uses the first valid response. In case of invalid responses, only the last one
12384is treated. Purpose is to give the chance to a slow server to deliver a valid
12385answer after a fast faulty or outdated server.
12386
12387When each server returns a different error type, then only the last error is
Christopher Faulet67957bd2017-09-27 11:00:59 +020012388used by HAProxy. The following processing is applied on this error:
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012389
Christopher Faulet67957bd2017-09-27 11:00:59 +020012390 1. HAProxy retries the same DNS query with a new query type. The A queries are
12391 switch to AAAA or the opposite. SRV queries are not concerned here. Timeout
12392 errors are also excluded.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012393
Christopher Faulet67957bd2017-09-27 11:00:59 +020012394 2. When the fallback on the query type was done (or not applicable), HAProxy
12395 retries the original DNS query, with the preferred query type.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012396
Christopher Faulet67957bd2017-09-27 11:00:59 +020012397 3. HAProxy retries previous steps <resolve_retires> times. If no valid
12398 response is received after that, it stops the DNS resolution and reports
12399 the error.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012400
Christopher Faulet67957bd2017-09-27 11:00:59 +020012401For example, with 2 name servers configured in a resolvers section, the
12402following scenarios are possible:
12403
12404 - First response is valid and is applied directly, second response is
12405 ignored
12406
12407 - First response is invalid and second one is valid, then second response is
12408 applied
12409
12410 - First response is a NX domain and second one a truncated response, then
12411 HAProxy retries the query with a new type
12412
12413 - First response is a NX domain and second one is a timeout, then HAProxy
12414 retries the query with a new type
12415
12416 - Query timed out for both name servers, then HAProxy retries it with the
12417 same query type
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012418
Olivier Houcharda8c6db82017-07-06 18:46:47 +020012419As a DNS server may not answer all the IPs in one DNS request, haproxy keeps
12420a cache of previous answers, an answer will be considered obsolete after
Christopher Faulet67957bd2017-09-27 11:00:59 +020012421<hold obsolete> seconds without the IP returned.
Olivier Houcharda8c6db82017-07-06 18:46:47 +020012422
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012423
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012424resolvers <resolvers id>
Davor Ocelice9ed2812017-12-25 17:49:28 +010012425 Creates a new name server list labeled <resolvers id>
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012426
12427A resolvers section accept the following parameters:
12428
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020012429accepted_payload_size <nb>
Davor Ocelice9ed2812017-12-25 17:49:28 +010012430 Defines the maximum payload size accepted by HAProxy and announced to all the
Christopher Faulet67957bd2017-09-27 11:00:59 +020012431 name servers configured in this resolvers section.
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020012432 <nb> is in bytes. If not set, HAProxy announces 512. (minimal value defined
12433 by RFC 6891)
12434
Baptiste Assmann9d8dbbc2017-08-18 23:35:08 +020012435 Note: the maximum allowed value is 8192.
12436
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012437nameserver <id> <ip>:<port>
12438 DNS server description:
12439 <id> : label of the server, should be unique
12440 <ip> : IP address of the server
12441 <port> : port where the DNS service actually runs
12442
Ben Draut44e609b2018-05-29 15:40:08 -060012443parse-resolv-conf
12444 Adds all nameservers found in /etc/resolv.conf to this resolvers nameservers
12445 list. Ordered as if each nameserver in /etc/resolv.conf was individually
12446 placed in the resolvers section in place of this directive.
12447
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012448hold <status> <period>
12449 Defines <period> during which the last name resolution should be kept based
12450 on last resolution <status>
Baptiste Assmann987e16d2016-11-02 22:23:31 +010012451 <status> : last name resolution status. Acceptable values are "nx",
Olivier Houcharda8c6db82017-07-06 18:46:47 +020012452 "other", "refused", "timeout", "valid", "obsolete".
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012453 <period> : interval between two successive name resolution when the last
12454 answer was in <status>. It follows the HAProxy time format.
12455 <period> is in milliseconds by default.
12456
Baptiste Assmann686408b2017-08-18 10:15:42 +020012457 Default value is 10s for "valid", 0s for "obsolete" and 30s for others.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012458
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012459resolve_retries <nb>
12460 Defines the number <nb> of queries to send to resolve a server name before
12461 giving up.
12462 Default value: 3
12463
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012464 A retry occurs on name server timeout or when the full sequence of DNS query
12465 type failover is over and we need to start up from the default ANY query
12466 type.
12467
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012468timeout <event> <time>
12469 Defines timeouts related to name resolution
12470 <event> : the event on which the <time> timeout period applies to.
12471 events available are:
Frédéric Lécaille93d33162019-03-06 09:35:59 +010012472 - resolve : default time to trigger name resolutions when no
12473 other time applied.
Christopher Faulet67957bd2017-09-27 11:00:59 +020012474 Default value: 1s
12475 - retry : time between two DNS queries, when no valid response
Frédéric Lécaille93d33162019-03-06 09:35:59 +010012476 have been received.
Christopher Faulet67957bd2017-09-27 11:00:59 +020012477 Default value: 1s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012478 <time> : time related to the event. It follows the HAProxy time format.
12479 <time> is expressed in milliseconds.
12480
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020012481 Example:
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012482
12483 resolvers mydns
12484 nameserver dns1 10.0.0.1:53
12485 nameserver dns2 10.0.0.2:53
Ben Draut44e609b2018-05-29 15:40:08 -060012486 parse-resolv-conf
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012487 resolve_retries 3
Christopher Faulet67957bd2017-09-27 11:00:59 +020012488 timeout resolve 1s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012489 timeout retry 1s
Baptiste Assmann987e16d2016-11-02 22:23:31 +010012490 hold other 30s
12491 hold refused 30s
12492 hold nx 30s
12493 hold timeout 30s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012494 hold valid 10s
Olivier Houcharda8c6db82017-07-06 18:46:47 +020012495 hold obsolete 30s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012496
12497
Christopher Faulet87f1f3d2019-07-18 14:51:20 +0200124986. Cache
12499---------
12500
12501HAProxy provides a cache, which was designed to perform cache on small objects
12502(favicon, css...). This is a minimalist low-maintenance cache which runs in
12503RAM.
12504
12505The cache is based on a memory which is shared between processes and threads,
12506this memory is split in blocks of 1k.
12507
12508If an object is not used anymore, it can be deleted to store a new object
12509independently of its expiration date. The oldest objects are deleted first
12510when we try to allocate a new one.
12511
12512The cache uses a hash of the host header and the URI as the key.
12513
12514It's possible to view the status of a cache using the Unix socket command
12515"show cache" consult section 9.3 "Unix Socket commands" of Management Guide
12516for more details.
12517
12518When an object is delivered from the cache, the server name in the log is
12519replaced by "<CACHE>".
12520
12521
125226.1. Limitation
12523----------------
12524
12525The cache won't store and won't deliver objects in these cases:
12526
12527- If the response is not a 200
12528- If the response contains a Vary header
12529- If the Content-Length + the headers size is greater than "max-object-size"
12530- If the response is not cacheable
12531
12532- If the request is not a GET
12533- If the HTTP version of the request is smaller than 1.1
12534- If the request contains an Authorization header
12535
12536
125376.2. Setup
12538-----------
12539
12540To setup a cache, you must define a cache section and use it in a proxy with
12541the corresponding http-request and response actions.
12542
12543
125446.2.1. Cache section
12545---------------------
12546
12547cache <name>
12548 Declare a cache section, allocate a shared cache memory named <name>, the
12549 size of cache is mandatory.
12550
12551total-max-size <megabytes>
12552 Define the size in RAM of the cache in megabytes. This size is split in
12553 blocks of 1kB which are used by the cache entries. Its maximum value is 4095.
12554
12555max-object-size <bytes>
12556 Define the maximum size of the objects to be cached. Must not be greater than
12557 an half of "total-max-size". If not set, it equals to a 256th of the cache size.
12558 All objects with sizes larger than "max-object-size" will not be cached.
12559
12560max-age <seconds>
12561 Define the maximum expiration duration. The expiration is set has the lowest
12562 value between the s-maxage or max-age (in this order) directive in the
12563 Cache-Control response header and this value. The default value is 60
12564 seconds, which means that you can't cache an object more than 60 seconds by
12565 default.
12566
12567
125686.2.2. Proxy section
12569---------------------
12570
12571http-request cache-use <name> [ { if | unless } <condition> ]
12572 Try to deliver a cached object from the cache <name>. This directive is also
12573 mandatory to store the cache as it calculates the cache hash. If you want to
12574 use a condition for both storage and delivering that's a good idea to put it
12575 after this one.
12576
12577http-response cache-store <name> [ { if | unless } <condition> ]
12578 Store an http-response within the cache. The storage of the response headers
12579 is done at this step, which means you can use others http-response actions
12580 to modify headers before or after the storage of the response. This action
12581 is responsible for the setup of the cache storage filter.
12582
12583
12584Example:
12585
12586 backend bck1
12587 mode http
12588
12589 http-request cache-use foobar
12590 http-response cache-store foobar
12591 server srv1 127.0.0.1:80
12592
12593 cache foobar
12594 total-max-size 4
12595 max-age 240
12596
12597
Willy Tarreau74ca5042013-06-11 23:12:07 +0200125987. Using ACLs and fetching samples
12599----------------------------------
12600
Davor Ocelice9ed2812017-12-25 17:49:28 +010012601HAProxy is capable of extracting data from request or response streams, from
Willy Tarreau74ca5042013-06-11 23:12:07 +020012602client or server information, from tables, environmental information etc...
12603The action of extracting such data is called fetching a sample. Once retrieved,
12604these samples may be used for various purposes such as a key to a stick-table,
12605but most common usages consist in matching them against predefined constant
12606data called patterns.
12607
12608
126097.1. ACL basics
12610---------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012611
12612The use of Access Control Lists (ACL) provides a flexible solution to perform
12613content switching and generally to take decisions based on content extracted
12614from the request, the response or any environmental status. The principle is
12615simple :
12616
Willy Tarreau74ca5042013-06-11 23:12:07 +020012617 - extract a data sample from a stream, table or the environment
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012618 - optionally apply some format conversion to the extracted sample
Willy Tarreau74ca5042013-06-11 23:12:07 +020012619 - apply one or multiple pattern matching methods on this sample
12620 - perform actions only when a pattern matches the sample
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012621
Willy Tarreau74ca5042013-06-11 23:12:07 +020012622The actions generally consist in blocking a request, selecting a backend, or
12623adding a header.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012624
12625In order to define a test, the "acl" keyword is used. The syntax is :
12626
Willy Tarreau74ca5042013-06-11 23:12:07 +020012627 acl <aclname> <criterion> [flags] [operator] [<value>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012628
12629This creates a new ACL <aclname> or completes an existing one with new tests.
12630Those tests apply to the portion of request/response specified in <criterion>
12631and may be adjusted with optional flags [flags]. Some criteria also support
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012632an operator which may be specified before the set of values. Optionally some
12633conversion operators may be applied to the sample, and they will be specified
12634as a comma-delimited list of keywords just after the first keyword. The values
12635are of the type supported by the criterion, and are separated by spaces.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012636
12637ACL names must be formed from upper and lower case letters, digits, '-' (dash),
12638'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
12639which means that "my_acl" and "My_Acl" are two different ACLs.
12640
12641There is no enforced limit to the number of ACLs. The unused ones do not affect
12642performance, they just consume a small amount of memory.
12643
Willy Tarreau74ca5042013-06-11 23:12:07 +020012644The criterion generally is the name of a sample fetch method, or one of its ACL
12645specific declinations. The default test method is implied by the output type of
12646this sample fetch method. The ACL declinations can describe alternate matching
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012647methods of a same sample fetch method. The sample fetch methods are the only
12648ones supporting a conversion.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012649
12650Sample fetch methods return data which can be of the following types :
12651 - boolean
12652 - integer (signed or unsigned)
12653 - IPv4 or IPv6 address
12654 - string
12655 - data block
12656
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012657Converters transform any of these data into any of these. For example, some
12658converters might convert a string to a lower-case string while other ones
12659would turn a string to an IPv4 address, or apply a netmask to an IP address.
12660The resulting sample is of the type of the last converter applied to the list,
12661which defaults to the type of the sample fetch method.
12662
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012663Each sample or converter returns data of a specific type, specified with its
12664keyword in this documentation. When an ACL is declared using a standard sample
12665fetch method, certain types automatically involved a default matching method
12666which are summarized in the table below :
12667
12668 +---------------------+-----------------+
12669 | Sample or converter | Default |
12670 | output type | matching method |
12671 +---------------------+-----------------+
12672 | boolean | bool |
12673 +---------------------+-----------------+
12674 | integer | int |
12675 +---------------------+-----------------+
12676 | ip | ip |
12677 +---------------------+-----------------+
12678 | string | str |
12679 +---------------------+-----------------+
12680 | binary | none, use "-m" |
12681 +---------------------+-----------------+
12682
12683Note that in order to match a binary samples, it is mandatory to specify a
12684matching method, see below.
12685
Willy Tarreau74ca5042013-06-11 23:12:07 +020012686The ACL engine can match these types against patterns of the following types :
12687 - boolean
12688 - integer or integer range
12689 - IP address / network
12690 - string (exact, substring, suffix, prefix, subdir, domain)
12691 - regular expression
12692 - hex block
12693
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012694The following ACL flags are currently supported :
12695
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012696 -i : ignore case during matching of all subsequent patterns.
12697 -f : load patterns from a file.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012698 -m : use a specific pattern matching method
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010012699 -n : forbid the DNS resolutions
Thierry FOURNIER9860c412014-01-29 14:23:29 +010012700 -M : load the file pointed by -f like a map file.
Thierry FOURNIER3534d882014-01-20 17:01:44 +010012701 -u : force the unique id of the ACL
Willy Tarreau6a06a402007-07-15 20:15:28 +020012702 -- : force end of flags. Useful when a string looks like one of the flags.
12703
Willy Tarreau74ca5042013-06-11 23:12:07 +020012704The "-f" flag is followed by the name of a file from which all lines will be
12705read as individual values. It is even possible to pass multiple "-f" arguments
12706if the patterns are to be loaded from multiple files. Empty lines as well as
12707lines beginning with a sharp ('#') will be ignored. All leading spaces and tabs
12708will be stripped. If it is absolutely necessary to insert a valid pattern
12709beginning with a sharp, just prefix it with a space so that it is not taken for
12710a comment. Depending on the data type and match method, haproxy may load the
12711lines into a binary tree, allowing very fast lookups. This is true for IPv4 and
12712exact string matching. In this case, duplicates will automatically be removed.
12713
Thierry FOURNIER9860c412014-01-29 14:23:29 +010012714The "-M" flag allows an ACL to use a map file. If this flag is set, the file is
12715parsed as two column file. The first column contains the patterns used by the
12716ACL, and the second column contain the samples. The sample can be used later by
12717a map. This can be useful in some rare cases where an ACL would just be used to
12718check for the existence of a pattern in a map before a mapping is applied.
12719
Thierry FOURNIER3534d882014-01-20 17:01:44 +010012720The "-u" flag forces the unique id of the ACL. This unique id is used with the
12721socket interface to identify ACL and dynamically change its values. Note that a
12722file is always identified by its name even if an id is set.
12723
Willy Tarreau74ca5042013-06-11 23:12:07 +020012724Also, note that the "-i" flag applies to subsequent entries and not to entries
12725loaded from files preceding it. For instance :
12726
12727 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
12728
12729In this example, each line of "exact-ua.lst" will be exactly matched against
12730the "user-agent" header of the request. Then each line of "generic-ua" will be
12731case-insensitively matched. Then the word "test" will be insensitively matched
12732as well.
12733
12734The "-m" flag is used to select a specific pattern matching method on the input
12735sample. All ACL-specific criteria imply a pattern matching method and generally
12736do not need this flag. However, this flag is useful with generic sample fetch
12737methods to describe how they're going to be matched against the patterns. This
12738is required for sample fetches which return data type for which there is no
Davor Ocelice9ed2812017-12-25 17:49:28 +010012739obvious matching method (e.g. string or binary). When "-m" is specified and
Willy Tarreau74ca5042013-06-11 23:12:07 +020012740followed by a pattern matching method name, this method is used instead of the
12741default one for the criterion. This makes it possible to match contents in ways
12742that were not initially planned, or with sample fetch methods which return a
12743string. The matching method also affects the way the patterns are parsed.
12744
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010012745The "-n" flag forbids the dns resolutions. It is used with the load of ip files.
12746By default, if the parser cannot parse ip address it considers that the parsed
12747string is maybe a domain name and try dns resolution. The flag "-n" disable this
12748resolution. It is useful for detecting malformed ip lists. Note that if the DNS
12749server is not reachable, the haproxy configuration parsing may last many minutes
John Roeslerfb2fce12019-07-10 15:45:51 -050012750waiting for the timeout. During this time no error messages are displayed. The
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010012751flag "-n" disable this behavior. Note also that during the runtime, this
12752function is disabled for the dynamic acl modifications.
12753
Willy Tarreau74ca5042013-06-11 23:12:07 +020012754There are some restrictions however. Not all methods can be used with all
12755sample fetch methods. Also, if "-m" is used in conjunction with "-f", it must
12756be placed first. The pattern matching method must be one of the following :
Willy Tarreau5adeda12013-03-31 22:13:34 +020012757
12758 - "found" : only check if the requested sample could be found in the stream,
12759 but do not compare it against any pattern. It is recommended not
Willy Tarreau74ca5042013-06-11 23:12:07 +020012760 to pass any pattern to avoid confusion. This matching method is
12761 particularly useful to detect presence of certain contents such
12762 as headers, cookies, etc... even if they are empty and without
12763 comparing them to anything nor counting them.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012764
12765 - "bool" : check the value as a boolean. It can only be applied to fetches
12766 which return a boolean or integer value, and takes no pattern.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012767 Value zero or false does not match, all other values do match.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012768
12769 - "int" : match the value as an integer. It can be used with integer and
Willy Tarreau74ca5042013-06-11 23:12:07 +020012770 boolean samples. Boolean false is integer 0, true is integer 1.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012771
12772 - "ip" : match the value as an IPv4 or IPv6 address. It is compatible
Willy Tarreau74ca5042013-06-11 23:12:07 +020012773 with IP address samples only, so it is implied and never needed.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012774
Davor Ocelice9ed2812017-12-25 17:49:28 +010012775 - "bin" : match the contents against a hexadecimal string representing a
Willy Tarreau5adeda12013-03-31 22:13:34 +020012776 binary sequence. This may be used with binary or string samples.
12777
12778 - "len" : match the sample's length as an integer. This may be used with
12779 binary or string samples.
12780
Willy Tarreau74ca5042013-06-11 23:12:07 +020012781 - "str" : exact match : match the contents against a string. This may be
12782 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012783
Willy Tarreau74ca5042013-06-11 23:12:07 +020012784 - "sub" : substring match : check that the contents contain at least one of
12785 the provided string patterns. This may be used with binary or
12786 string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012787
Willy Tarreau74ca5042013-06-11 23:12:07 +020012788 - "reg" : regex match : match the contents against a list of regular
12789 expressions. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012790
Willy Tarreau74ca5042013-06-11 23:12:07 +020012791 - "beg" : prefix match : check that the contents begin like the provided
12792 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012793
Willy Tarreau74ca5042013-06-11 23:12:07 +020012794 - "end" : suffix match : check that the contents end like the provided
12795 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012796
Willy Tarreau74ca5042013-06-11 23:12:07 +020012797 - "dir" : subdir match : check that a slash-delimited portion of the
12798 contents exactly matches one of the provided string patterns.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012799 This may be used with binary or string samples.
12800
Willy Tarreau74ca5042013-06-11 23:12:07 +020012801 - "dom" : domain match : check that a dot-delimited portion of the contents
12802 exactly match one of the provided string patterns. This may be
12803 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012804
12805For example, to quickly detect the presence of cookie "JSESSIONID" in an HTTP
12806request, it is possible to do :
12807
12808 acl jsess_present cook(JSESSIONID) -m found
12809
12810In order to apply a regular expression on the 500 first bytes of data in the
12811buffer, one would use the following acl :
12812
12813 acl script_tag payload(0,500) -m reg -i <script>
12814
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012815On systems where the regex library is much slower when using "-i", it is
12816possible to convert the sample to lowercase before matching, like this :
12817
12818 acl script_tag payload(0,500),lower -m reg <script>
12819
Willy Tarreau74ca5042013-06-11 23:12:07 +020012820All ACL-specific criteria imply a default matching method. Most often, these
12821criteria are composed by concatenating the name of the original sample fetch
12822method and the matching method. For example, "hdr_beg" applies the "beg" match
12823to samples retrieved using the "hdr" fetch method. Since all ACL-specific
12824criteria rely on a sample fetch method, it is always possible instead to use
12825the original sample fetch method and the explicit matching method using "-m".
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012826
Willy Tarreau74ca5042013-06-11 23:12:07 +020012827If an alternate match is specified using "-m" on an ACL-specific criterion,
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012828the matching method is simply applied to the underlying sample fetch method.
12829For example, all ACLs below are exact equivalent :
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012830
Willy Tarreau74ca5042013-06-11 23:12:07 +020012831 acl short_form hdr_beg(host) www.
12832 acl alternate1 hdr_beg(host) -m beg www.
12833 acl alternate2 hdr_dom(host) -m beg www.
12834 acl alternate3 hdr(host) -m beg www.
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012835
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012836
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012837The table below summarizes the compatibility matrix between sample or converter
12838types and the pattern types to fetch against. It indicates for each compatible
12839combination the name of the matching method to be used, surrounded with angle
12840brackets ">" and "<" when the method is the default one and will work by
12841default without "-m".
Willy Tarreau0ba27502007-12-24 16:55:16 +010012842
Willy Tarreau74ca5042013-06-11 23:12:07 +020012843 +-------------------------------------------------+
12844 | Input sample type |
12845 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012846 | pattern type | boolean | integer | ip | string | binary |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012847 +----------------------+---------+---------+---------+---------+---------+
12848 | none (presence only) | found | found | found | found | found |
12849 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012850 | none (boolean value) |> bool <| bool | | bool | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012851 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012852 | integer (value) | int |> int <| int | int | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012853 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012854 | integer (length) | len | len | len | len | len |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012855 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012856 | IP address | | |> ip <| ip | ip |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012857 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012858 | exact string | str | str | str |> str <| str |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012859 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012860 | prefix | beg | beg | beg | beg | beg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012861 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012862 | suffix | end | end | end | end | end |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012863 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012864 | substring | sub | sub | sub | sub | sub |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012865 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012866 | subdir | dir | dir | dir | dir | dir |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012867 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012868 | domain | dom | dom | dom | dom | dom |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012869 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012870 | regex | reg | reg | reg | reg | reg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012871 +----------------------+---------+---------+---------+---------+---------+
12872 | hex block | | | | bin | bin |
12873 +----------------------+---------+---------+---------+---------+---------+
Willy Tarreau6a06a402007-07-15 20:15:28 +020012874
12875
Willy Tarreau74ca5042013-06-11 23:12:07 +0200128767.1.1. Matching booleans
12877------------------------
12878
12879In order to match a boolean, no value is needed and all values are ignored.
12880Boolean matching is used by default for all fetch methods of type "boolean".
12881When boolean matching is used, the fetched value is returned as-is, which means
12882that a boolean "true" will always match and a boolean "false" will never match.
12883
12884Boolean matching may also be enforced using "-m bool" on fetch methods which
12885return an integer value. Then, integer value 0 is converted to the boolean
12886"false" and all other values are converted to "true".
12887
Willy Tarreau6a06a402007-07-15 20:15:28 +020012888
Willy Tarreau74ca5042013-06-11 23:12:07 +0200128897.1.2. Matching integers
12890------------------------
12891
12892Integer matching applies by default to integer fetch methods. It can also be
12893enforced on boolean fetches using "-m int". In this case, "false" is converted
12894to the integer 0, and "true" is converted to the integer 1.
12895
12896Integer matching also supports integer ranges and operators. Note that integer
12897matching only applies to positive values. A range is a value expressed with a
12898lower and an upper bound separated with a colon, both of which may be omitted.
Willy Tarreau6a06a402007-07-15 20:15:28 +020012899
12900For instance, "1024:65535" is a valid range to represent a range of
12901unprivileged ports, and "1024:" would also work. "0:1023" is a valid
12902representation of privileged ports, and ":1023" would also work.
12903
Willy Tarreau62644772008-07-16 18:36:06 +020012904As a special case, some ACL functions support decimal numbers which are in fact
12905two integers separated by a dot. This is used with some version checks for
12906instance. All integer properties apply to those decimal numbers, including
12907ranges and operators.
12908
Willy Tarreau6a06a402007-07-15 20:15:28 +020012909For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +010012910operators with ranges does not make much sense and is strongly discouraged.
12911Similarly, it does not make much sense to perform order comparisons with a set
12912of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +020012913
Willy Tarreau0ba27502007-12-24 16:55:16 +010012914Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +020012915
12916 eq : true if the tested value equals at least one value
12917 ge : true if the tested value is greater than or equal to at least one value
12918 gt : true if the tested value is greater than at least one value
12919 le : true if the tested value is less than or equal to at least one value
12920 lt : true if the tested value is less than at least one value
12921
Willy Tarreau0ba27502007-12-24 16:55:16 +010012922For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +020012923
12924 acl negative-length hdr_val(content-length) lt 0
12925
Willy Tarreau62644772008-07-16 18:36:06 +020012926This one matches SSL versions between 3.0 and 3.1 (inclusive) :
12927
12928 acl sslv3 req_ssl_ver 3:3.1
12929
Willy Tarreau6a06a402007-07-15 20:15:28 +020012930
Willy Tarreau74ca5042013-06-11 23:12:07 +0200129317.1.3. Matching strings
12932-----------------------
12933
12934String matching applies to string or binary fetch methods, and exists in 6
12935different forms :
12936
12937 - exact match (-m str) : the extracted string must exactly match the
Davor Ocelice9ed2812017-12-25 17:49:28 +010012938 patterns;
Willy Tarreau74ca5042013-06-11 23:12:07 +020012939
12940 - substring match (-m sub) : the patterns are looked up inside the
Davor Ocelice9ed2812017-12-25 17:49:28 +010012941 extracted string, and the ACL matches if any of them is found inside;
Willy Tarreau74ca5042013-06-11 23:12:07 +020012942
12943 - prefix match (-m beg) : the patterns are compared with the beginning of
12944 the extracted string, and the ACL matches if any of them matches.
12945
12946 - suffix match (-m end) : the patterns are compared with the end of the
12947 extracted string, and the ACL matches if any of them matches.
12948
Baptiste Assmann33db6002016-03-06 23:32:10 +010012949 - subdir match (-m dir) : the patterns are looked up inside the extracted
Willy Tarreau74ca5042013-06-11 23:12:07 +020012950 string, delimited with slashes ("/"), and the ACL matches if any of them
12951 matches.
12952
12953 - domain match (-m dom) : the patterns are looked up inside the extracted
12954 string, delimited with dots ("."), and the ACL matches if any of them
12955 matches.
Willy Tarreau6a06a402007-07-15 20:15:28 +020012956
12957String matching applies to verbatim strings as they are passed, with the
12958exception of the backslash ("\") which makes it possible to escape some
12959characters such as the space. If the "-i" flag is passed before the first
12960string, then the matching will be performed ignoring the case. In order
12961to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +010012962before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020012963
Mathias Weiersmuellercb250fc2019-12-02 09:43:40 +010012964Do not use string matches for binary fetches which might contain null bytes
12965(0x00), as the comparison stops at the occurrence of the first null byte.
12966Instead, convert the binary fetch to a hex string with the hex converter first.
12967
12968Example:
12969 # matches if the string <tag> is present in the binary sample
12970 acl tag_found req.payload(0,0),hex -m sub 3C7461673E
12971
Willy Tarreau6a06a402007-07-15 20:15:28 +020012972
Willy Tarreau74ca5042013-06-11 23:12:07 +0200129737.1.4. Matching regular expressions (regexes)
12974---------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020012975
12976Just like with string matching, regex matching applies to verbatim strings as
12977they are passed, with the exception of the backslash ("\") which makes it
12978possible to escape some characters such as the space. If the "-i" flag is
12979passed before the first regex, then the matching will be performed ignoring
12980the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +010012981the "--" flag before the first string. Same principle applies of course to
12982match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020012983
12984
Willy Tarreau74ca5042013-06-11 23:12:07 +0200129857.1.5. Matching arbitrary data blocks
12986-------------------------------------
12987
12988It is possible to match some extracted samples against a binary block which may
12989not safely be represented as a string. For this, the patterns must be passed as
12990a series of hexadecimal digits in an even number, when the match method is set
12991to binary. Each sequence of two digits will represent a byte. The hexadecimal
12992digits may be used upper or lower case.
12993
12994Example :
12995 # match "Hello\n" in the input stream (\x48 \x65 \x6c \x6c \x6f \x0a)
12996 acl hello payload(0,6) -m bin 48656c6c6f0a
12997
12998
129997.1.6. Matching IPv4 and IPv6 addresses
13000---------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020013001
13002IPv4 addresses values can be specified either as plain addresses or with a
13003netmask appended, in which case the IPv4 address matches whenever it is
13004within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010013005host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +010013006difficult to read and debug configurations. If hostnames are used, you should
13007at least ensure that they are present in /etc/hosts so that the configuration
13008does not depend on any random DNS match at the moment the configuration is
13009parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013010
Daniel Schnellereba56342016-04-13 00:26:52 +020013011The dotted IPv4 address notation is supported in both regular as well as the
13012abbreviated form with all-0-octets omitted:
13013
13014 +------------------+------------------+------------------+
13015 | Example 1 | Example 2 | Example 3 |
13016 +------------------+------------------+------------------+
13017 | 192.168.0.1 | 10.0.0.12 | 127.0.0.1 |
13018 | 192.168.1 | 10.12 | 127.1 |
13019 | 192.168.0.1/22 | 10.0.0.12/8 | 127.0.0.1/8 |
13020 | 192.168.1/22 | 10.12/8 | 127.1/8 |
13021 +------------------+------------------+------------------+
13022
13023Notice that this is different from RFC 4632 CIDR address notation in which
13024192.168.42/24 would be equivalent to 192.168.42.0/24.
13025
Willy Tarreauceb4ac92012-04-28 00:41:46 +020013026IPv6 may be entered in their usual form, with or without a netmask appended.
13027Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of
13028trouble with randomly resolved IP addresses, host names are never allowed in
13029IPv6 patterns.
13030
13031HAProxy is also able to match IPv4 addresses with IPv6 addresses in the
13032following situations :
13033 - tested address is IPv4, pattern address is IPv4, the match applies
13034 in IPv4 using the supplied mask if any.
13035 - tested address is IPv6, pattern address is IPv6, the match applies
13036 in IPv6 using the supplied mask if any.
13037 - tested address is IPv6, pattern address is IPv4, the match applies in IPv4
13038 using the pattern's mask if the IPv6 address matches with 2002:IPV4::,
13039 ::IPV4 or ::ffff:IPV4, otherwise it fails.
13040 - tested address is IPv4, pattern address is IPv6, the IPv4 address is first
13041 converted to IPv6 by prefixing ::ffff: in front of it, then the match is
13042 applied in IPv6 using the supplied IPv6 mask.
13043
Willy Tarreau74ca5042013-06-11 23:12:07 +020013044
130457.2. Using ACLs to form conditions
13046----------------------------------
13047
13048Some actions are only performed upon a valid condition. A condition is a
13049combination of ACLs with operators. 3 operators are supported :
13050
13051 - AND (implicit)
13052 - OR (explicit with the "or" keyword or the "||" operator)
13053 - Negation with the exclamation mark ("!")
Willy Tarreau6a06a402007-07-15 20:15:28 +020013054
Willy Tarreau74ca5042013-06-11 23:12:07 +020013055A condition is formed as a disjunctive form:
Willy Tarreau6a06a402007-07-15 20:15:28 +020013056
Willy Tarreau74ca5042013-06-11 23:12:07 +020013057 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreaubef91e72013-03-31 23:14:46 +020013058
Willy Tarreau74ca5042013-06-11 23:12:07 +020013059Such conditions are generally used after an "if" or "unless" statement,
13060indicating when the condition will trigger the action.
Willy Tarreaubef91e72013-03-31 23:14:46 +020013061
Willy Tarreau74ca5042013-06-11 23:12:07 +020013062For instance, to block HTTP requests to the "*" URL with methods other than
13063"OPTIONS", as well as POST requests without content-length, and GET or HEAD
13064requests with a content-length greater than 0, and finally every request which
13065is not either GET/HEAD/POST/OPTIONS !
13066
13067 acl missing_cl hdr_cnt(Content-length) eq 0
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030013068 http-request deny if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
13069 http-request deny if METH_GET HTTP_CONTENT
13070 http-request deny unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreau74ca5042013-06-11 23:12:07 +020013071
13072To select a different backend for requests to static contents on the "www" site
13073and to every request on the "img", "video", "download" and "ftp" hosts :
13074
13075 acl url_static path_beg /static /images /img /css
13076 acl url_static path_end .gif .png .jpg .css .js
13077 acl host_www hdr_beg(host) -i www
13078 acl host_static hdr_beg(host) -i img. video. download. ftp.
13079
Davor Ocelice9ed2812017-12-25 17:49:28 +010013080 # now use backend "static" for all static-only hosts, and for static URLs
Willy Tarreau74ca5042013-06-11 23:12:07 +020013081 # of host "www". Use backend "www" for the rest.
13082 use_backend static if host_static or host_www url_static
13083 use_backend www if host_www
13084
13085It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
13086expressions that are built on the fly without needing to be declared. They must
13087be enclosed between braces, with a space before and after each brace (because
13088the braces must be seen as independent words). Example :
13089
13090 The following rule :
13091
13092 acl missing_cl hdr_cnt(Content-length) eq 0
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030013093 http-request deny if METH_POST missing_cl
Willy Tarreau74ca5042013-06-11 23:12:07 +020013094
13095 Can also be written that way :
13096
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030013097 http-request deny if METH_POST { hdr_cnt(Content-length) eq 0 }
Willy Tarreau74ca5042013-06-11 23:12:07 +020013098
13099It is generally not recommended to use this construct because it's a lot easier
13100to leave errors in the configuration when written that way. However, for very
13101simple rules matching only one source IP address for instance, it can make more
13102sense to use them than to declare ACLs with random names. Another example of
13103good use is the following :
13104
13105 With named ACLs :
13106
13107 acl site_dead nbsrv(dynamic) lt 2
13108 acl site_dead nbsrv(static) lt 2
13109 monitor fail if site_dead
13110
13111 With anonymous ACLs :
13112
13113 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
13114
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030013115See section 4.2 for detailed help on the "http-request deny" and "use_backend"
13116keywords.
Willy Tarreau74ca5042013-06-11 23:12:07 +020013117
13118
131197.3. Fetching samples
13120---------------------
13121
13122Historically, sample fetch methods were only used to retrieve data to match
13123against patterns using ACLs. With the arrival of stick-tables, a new class of
13124sample fetch methods was created, most often sharing the same syntax as their
13125ACL counterpart. These sample fetch methods are also known as "fetches". As
13126of now, ACLs and fetches have converged. All ACL fetch methods have been made
13127available as fetch methods, and ACLs may use any sample fetch method as well.
13128
13129This section details all available sample fetch methods and their output type.
13130Some sample fetch methods have deprecated aliases that are used to maintain
13131compatibility with existing configurations. They are then explicitly marked as
13132deprecated and should not be used in new setups.
13133
13134The ACL derivatives are also indicated when available, with their respective
13135matching methods. These ones all have a well defined default pattern matching
13136method, so it is never necessary (though allowed) to pass the "-m" option to
13137indicate how the sample will be matched using ACLs.
13138
13139As indicated in the sample type versus matching compatibility matrix above,
13140when using a generic sample fetch method in an ACL, the "-m" option is
13141mandatory unless the sample type is one of boolean, integer, IPv4 or IPv6. When
13142the same keyword exists as an ACL keyword and as a standard fetch method, the
13143ACL engine will automatically pick the ACL-only one by default.
13144
13145Some of these keywords support one or multiple mandatory arguments, and one or
13146multiple optional arguments. These arguments are strongly typed and are checked
13147when the configuration is parsed so that there is no risk of running with an
Davor Ocelice9ed2812017-12-25 17:49:28 +010013148incorrect argument (e.g. an unresolved backend name). Fetch function arguments
13149are passed between parenthesis and are delimited by commas. When an argument
Willy Tarreau74ca5042013-06-11 23:12:07 +020013150is optional, it will be indicated below between square brackets ('[ ]'). When
13151all arguments are optional, the parenthesis may be omitted.
13152
13153Thus, the syntax of a standard sample fetch method is one of the following :
13154 - name
13155 - name(arg1)
13156 - name(arg1,arg2)
13157
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013158
131597.3.1. Converters
13160-----------------
13161
Willy Tarreaue6b11e42013-11-26 19:02:32 +010013162Sample fetch methods may be combined with transformations to be applied on top
13163of the fetched sample (also called "converters"). These combinations form what
13164is called "sample expressions" and the result is a "sample". Initially this
13165was only supported by "stick on" and "stick store-request" directives but this
Davor Ocelice9ed2812017-12-25 17:49:28 +010013166has now be extended to all places where samples may be used (ACLs, log-format,
Willy Tarreaue6b11e42013-11-26 19:02:32 +010013167unique-id-format, add-header, ...).
13168
13169These transformations are enumerated as a series of specific keywords after the
13170sample fetch method. These keywords may equally be appended immediately after
13171the fetch keyword's argument, delimited by a comma. These keywords can also
Davor Ocelice9ed2812017-12-25 17:49:28 +010013172support some arguments (e.g. a netmask) which must be passed in parenthesis.
Willy Tarreau0ba27502007-12-24 16:55:16 +010013173
Willy Tarreau97707872015-01-27 15:12:13 +010013174A certain category of converters are bitwise and arithmetic operators which
13175support performing basic operations on integers. Some bitwise operations are
13176supported (and, or, xor, cpl) and some arithmetic operations are supported
13177(add, sub, mul, div, mod, neg). Some comparators are provided (odd, even, not,
13178bool) which make it possible to report a match without having to write an ACL.
13179
Willy Tarreau74ca5042013-06-11 23:12:07 +020013180The currently available list of transformation keywords include :
Willy Tarreau0ba27502007-12-24 16:55:16 +010013181
Ben Shillitof25e8e52016-12-02 14:25:37 +00001318251d.single(<prop>[,<prop>*])
13183 Returns values for the properties requested as a string, where values are
13184 separated by the delimiter specified with "51degrees-property-separator".
13185 The device is identified using the User-Agent header passed to the
13186 converter. The function can be passed up to five property names, and if a
13187 property name can't be found, the value "NoData" is returned.
13188
13189 Example :
Davor Ocelice9ed2812017-12-25 17:49:28 +010013190 # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request,
13191 # containing values for the three properties requested by using the
Ben Shillitof25e8e52016-12-02 14:25:37 +000013192 # User-Agent passed to the converter.
13193 frontend http-in
13194 bind *:8081
13195 default_backend servers
13196 http-request set-header X-51D-DeviceTypeMobileTablet \
13197 %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)]
13198
Willy Tarreau97707872015-01-27 15:12:13 +010013199add(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013200 Adds <value> to the input value of type signed integer, and returns the
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013201 result as a signed integer. <value> can be a numeric value or a variable
Daniel Schneller0b547052016-03-21 20:46:57 +010013202 name. The name of the variable starts with an indication about its scope. The
13203 scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013204 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013205 "sess" : the variable is shared with the whole session
13206 "txn" : the variable is shared with the transaction (request and response)
13207 "req" : the variable is shared only during request processing
13208 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013209 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013210 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013211
Nenad Merdanovicc31499d2019-03-23 11:00:32 +010013212aes_gcm_dec(<bits>,<nonce>,<key>,<aead_tag>)
13213 Decrypts the raw byte input using the AES128-GCM, AES192-GCM or
13214 AES256-GCM algorithm, depending on the <bits> parameter. All other parameters
13215 need to be base64 encoded and the returned result is in raw byte format.
13216 If the <aead_tag> validation fails, the converter doesn't return any data.
13217 The <nonce>, <key> and <aead_tag> can either be strings or variables. This
13218 converter requires at least OpenSSL 1.0.1.
13219
13220 Example:
13221 http-response set-header X-Decrypted-Text %[var(txn.enc),\
13222 aes_gcm_dec(128,txn.nonce,Zm9vb2Zvb29mb29wZm9vbw==,txn.aead_tag)]
13223
Willy Tarreau97707872015-01-27 15:12:13 +010013224and(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013225 Performs a bitwise "AND" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013226 integer, and returns the result as an signed integer. <value> can be a
Daniel Schneller0b547052016-03-21 20:46:57 +010013227 numeric value or a variable name. The name of the variable starts with an
13228 indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013229 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013230 "sess" : the variable is shared with the whole session
13231 "txn" : the variable is shared with the transaction (request and response)
13232 "req" : the variable is shared only during request processing
13233 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013234 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013235 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013236
Holger Just1bfc24b2017-05-06 00:56:53 +020013237b64dec
13238 Converts (decodes) a base64 encoded input string to its binary
13239 representation. It performs the inverse operation of base64().
13240
Emeric Brun53d1a982014-04-30 18:21:37 +020013241base64
13242 Converts a binary input sample to a base64 string. It is used to log or
Davor Ocelice9ed2812017-12-25 17:49:28 +010013243 transfer binary content in a way that can be reliably transferred (e.g.
Emeric Brun53d1a982014-04-30 18:21:37 +020013244 an SSL ID can be copied in a header).
13245
Willy Tarreau97707872015-01-27 15:12:13 +010013246bool
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013247 Returns a boolean TRUE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010013248 non-null, otherwise returns FALSE. Used in conjunction with and(), it can be
Davor Ocelice9ed2812017-12-25 17:49:28 +010013249 used to report true/false for bit testing on input values (e.g. verify the
Willy Tarreau97707872015-01-27 15:12:13 +010013250 presence of a flag).
13251
Emeric Brun54c4ac82014-11-03 15:32:43 +010013252bytes(<offset>[,<length>])
13253 Extracts some bytes from an input binary sample. The result is a binary
13254 sample starting at an offset (in bytes) of the original sample and
Tim Düsterhus4896c442016-11-29 02:15:19 +010013255 optionally truncated at the given length.
Emeric Brun54c4ac82014-11-03 15:32:43 +010013256
Willy Tarreau280f42b2018-02-19 15:34:12 +010013257concat([<start>],[<var>],[<end>])
13258 Concatenates up to 3 fields after the current sample which is then turned to
13259 a string. The first one, <start>, is a constant string, that will be appended
13260 immediately after the existing sample. It may be omitted if not used. The
13261 second one, <var>, is a variable name. The variable will be looked up, its
13262 contents converted to a string, and it will be appended immediately after the
13263 <first> part. If the variable is not found, nothing is appended. It may be
13264 omitted as well. The third field, <end> is a constant string that will be
13265 appended after the variable. It may also be omitted. Together, these elements
13266 allow to concatenate variables with delimiters to an existing set of
13267 variables. This can be used to build new variables made of a succession of
John Roeslerfb2fce12019-07-10 15:45:51 -050013268 other variables, such as colon-delimited values. Note that due to the config
Willy Tarreau280f42b2018-02-19 15:34:12 +010013269 parser, it is not possible to use a comma nor a closing parenthesis as
John Roeslerfb2fce12019-07-10 15:45:51 -050013270 delimiters.
Willy Tarreau280f42b2018-02-19 15:34:12 +010013271
13272 Example:
13273 tcp-request session set-var(sess.src) src
13274 tcp-request session set-var(sess.dn) ssl_c_s_dn
13275 tcp-request session set-var(txn.sig) str(),concat(<ip=,sess.ip,>),concat(<dn=,sess.dn,>)
13276 http-request set-header x-hap-sig %[var(txn.sig)]
13277
Willy Tarreau97707872015-01-27 15:12:13 +010013278cpl
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013279 Takes the input value of type signed integer, applies a ones-complement
13280 (flips all bits) and returns the result as an signed integer.
Willy Tarreau97707872015-01-27 15:12:13 +010013281
Willy Tarreau80599772015-01-20 19:35:24 +010013282crc32([<avalanche>])
13283 Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32
13284 hash function. Optionally, it is possible to apply a full avalanche hash
13285 function to the output if the optional <avalanche> argument equals 1. This
13286 converter uses the same functions as used by the various hash-based load
13287 balancing algorithms, so it will provide exactly the same results. It is
13288 provided for compatibility with other software which want a CRC32 to be
13289 computed on some input keys, so it follows the most common implementation as
13290 found in Ethernet, Gzip, PNG, etc... It is slower than the other algorithms
13291 but may provide a better or at least less predictable distribution. It must
13292 not be used for security purposes as a 32-bit hash is trivial to break. See
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010013293 also "djb2", "sdbm", "wt6", "crc32c" and the "hash-type" directive.
13294
13295crc32c([<avalanche>])
13296 Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32C
13297 hash function. Optionally, it is possible to apply a full avalanche hash
13298 function to the output if the optional <avalanche> argument equals 1. This
13299 converter uses the same functions as described in RFC4960, Appendix B [8].
13300 It is provided for compatibility with other software which want a CRC32C to be
13301 computed on some input keys. It is slower than the other algorithms and it must
13302 not be used for security purposes as a 32-bit hash is trivial to break. See
13303 also "djb2", "sdbm", "wt6", "crc32" and the "hash-type" directive.
Willy Tarreau80599772015-01-20 19:35:24 +010013304
David Carlier29b3ca32015-09-25 14:09:21 +010013305da-csv-conv(<prop>[,<prop>*])
David Carlier4542b102015-06-01 13:54:29 +020013306 Asks the DeviceAtlas converter to identify the User Agent string passed on
13307 input, and to emit a string made of the concatenation of the properties
13308 enumerated in argument, delimited by the separator defined by the global
13309 keyword "deviceatlas-property-separator", or by default the pipe character
David Carlier840b0242016-03-16 10:09:55 +000013310 ('|'). There's a limit of 12 different properties imposed by the haproxy
David Carlier4542b102015-06-01 13:54:29 +020013311 configuration language.
13312
13313 Example:
13314 frontend www
Cyril Bonté307ee1e2015-09-28 23:16:06 +020013315 bind *:8881
13316 default_backend servers
David Carlier840b0242016-03-16 10:09:55 +000013317 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 +020013318
Willy Tarreau0851fd52019-12-17 10:07:25 +010013319debug([<prefix][,<destination>])
13320 This converter is used as debug tool. It takes a capture of the input sample
13321 and sends it to event sink <destination>, which may designate a ring buffer
13322 such as "buf0", as well as "stdout", or "stderr". Available sinks may be
13323 checked at run time by issuing "show events" on the CLI. When not specified,
13324 the output will be "buf0", which may be consulted via the CLI's "show events"
13325 command. An optional prefix <prefix> may be passed to help distinguish
13326 outputs from multiple expressions. It will then appear before the colon in
13327 the output message. The input sample is passed as-is on the output, so that
13328 it is safe to insert the debug converter anywhere in a chain, even with non-
13329 printable sample types.
13330
13331 Example:
13332 tcp-request connection track-sc0 src,debug(track-sc)
Thierry FOURNIER9687c772015-05-07 15:46:29 +020013333
Willy Tarreau97707872015-01-27 15:12:13 +010013334div(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013335 Divides the input value of type signed integer by <value>, and returns the
13336 result as an signed integer. If <value> is null, the largest unsigned
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013337 integer is returned (typically 2^63-1). <value> can be a numeric value or a
Daniel Schneller0b547052016-03-21 20:46:57 +010013338 variable name. The name of the variable starts with an indication about its
13339 scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013340 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013341 "sess" : the variable is shared with the whole session
13342 "txn" : the variable is shared with the transaction (request and response)
13343 "req" : the variable is shared only during request processing
13344 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013345 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013346 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013347
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013348djb2([<avalanche>])
13349 Hashes a binary input sample into an unsigned 32-bit quantity using the DJB2
13350 hash function. Optionally, it is possible to apply a full avalanche hash
13351 function to the output if the optional <avalanche> argument equals 1. This
13352 converter uses the same functions as used by the various hash-based load
13353 balancing algorithms, so it will provide exactly the same results. It is
13354 mostly intended for debugging, but can be used as a stick-table entry to
13355 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010013356 32-bit hash is trivial to break. See also "crc32", "sdbm", "wt6", "crc32c",
13357 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013358
Willy Tarreau97707872015-01-27 15:12:13 +010013359even
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013360 Returns a boolean TRUE if the input value of type signed integer is even
Willy Tarreau97707872015-01-27 15:12:13 +010013361 otherwise returns FALSE. It is functionally equivalent to "not,and(1),bool".
13362
Marcin Deranek9631a282018-04-16 14:30:46 +020013363field(<index>,<delimiters>[,<count>])
13364 Extracts the substring at the given index counting from the beginning
13365 (positive index) or from the end (negative index) considering given delimiters
13366 from an input string. Indexes start at 1 or -1 and delimiters are a string
13367 formatted list of chars. Optionally you can specify <count> of fields to
13368 extract (default: 1). Value of 0 indicates extraction of all remaining
13369 fields.
13370
13371 Example :
13372 str(f1_f2_f3__f5),field(5,_) # f5
13373 str(f1_f2_f3__f5),field(2,_,0) # f2_f3__f5
13374 str(f1_f2_f3__f5),field(2,_,2) # f2_f3
13375 str(f1_f2_f3__f5),field(-2,_,3) # f2_f3_
13376 str(f1_f2_f3__f5),field(-3,_,0) # f1_f2_f3
Emeric Brunf399b0d2014-11-03 17:07:03 +010013377
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013378hex
Davor Ocelice9ed2812017-12-25 17:49:28 +010013379 Converts a binary input sample to a hex string containing two hex digits per
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013380 input byte. It is used to log or transfer hex dumps of some binary input data
Davor Ocelice9ed2812017-12-25 17:49:28 +010013381 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 +020013382 header).
Thierry FOURNIER2f49d6d2014-03-12 15:01:52 +010013383
Dragan Dosen3f957b22017-10-24 09:27:34 +020013384hex2i
13385 Converts a hex string containing two hex digits per input byte to an
John Roeslerfb2fce12019-07-10 15:45:51 -050013386 integer. If the input value cannot be converted, then zero is returned.
Dragan Dosen3f957b22017-10-24 09:27:34 +020013387
Cyril Bonté6bcd1822019-11-05 23:13:59 +010013388http_date([<offset],[<unit>])
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013389 Converts an integer supposed to contain a date since epoch to a string
13390 representing this date in a format suitable for use in HTTP header fields. If
Damien Claisseae6f1252019-10-30 15:57:28 +000013391 an offset value is specified, then it is added to the date before the
13392 conversion is operated. This is particularly useful to emit Date header fields,
13393 Expires values in responses when combined with a positive offset, or
13394 Last-Modified values when the offset is negative.
13395 If a unit value is specified, then consider the timestamp as either
13396 "s" for seconds (default behavior), "ms" for milliseconds, or "us" for
13397 microseconds since epoch. Offset is assumed to have the same unit as
13398 input timestamp.
Willy Tarreau74ca5042013-06-11 23:12:07 +020013399
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013400in_table(<table>)
13401 Uses the string representation of the input sample to perform a look up in
13402 the specified table. If the key is not found in the table, a boolean false
13403 is returned. Otherwise a boolean true is returned. This can be used to verify
Davor Ocelice9ed2812017-12-25 17:49:28 +010013404 the presence of a certain key in a table tracking some elements (e.g. whether
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013405 or not a source IP address or an Authorization header was already seen).
13406
Tim Duesterhus1478aa72018-01-25 16:24:51 +010013407ipmask(<mask4>, [<mask6>])
13408 Apply a mask to an IP address, and use the result for lookups and storage.
Willy Tarreauffcb2e42014-07-10 16:29:08 +020013409 This can be used to make all hosts within a certain mask to share the same
Tim Duesterhus1478aa72018-01-25 16:24:51 +010013410 table entries and as such use the same server. The mask4 can be passed in
13411 dotted form (e.g. 255.255.255.0) or in CIDR form (e.g. 24). The mask6 can
13412 be passed in quadruplet form (e.g. ffff:ffff::) or in CIDR form (e.g. 64).
13413 If no mask6 is given IPv6 addresses will fail to convert for backwards
13414 compatibility reasons.
Willy Tarreauffcb2e42014-07-10 16:29:08 +020013415
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013416json([<input-code>])
Davor Ocelice9ed2812017-12-25 17:49:28 +010013417 Escapes the input string and produces an ASCII output string ready to use as a
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013418 JSON string. The converter tries to decode the input string according to the
Herve COMMOWICK8dfe8632016-08-05 12:01:20 +020013419 <input-code> parameter. It can be "ascii", "utf8", "utf8s", "utf8p" or
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013420 "utf8ps". The "ascii" decoder never fails. The "utf8" decoder detects 3 types
13421 of errors:
13422 - bad UTF-8 sequence (lone continuation byte, bad number of continuation
13423 bytes, ...)
13424 - invalid range (the decoded value is within a UTF-8 prohibited range),
13425 - code overlong (the value is encoded with more bytes than necessary).
13426
13427 The UTF-8 JSON encoding can produce a "too long value" error when the UTF-8
13428 character is greater than 0xffff because the JSON string escape specification
13429 only authorizes 4 hex digits for the value encoding. The UTF-8 decoder exists
13430 in 4 variants designated by a combination of two suffix letters : "p" for
13431 "permissive" and "s" for "silently ignore". The behaviors of the decoders
13432 are :
Davor Ocelice9ed2812017-12-25 17:49:28 +010013433 - "ascii" : never fails;
13434 - "utf8" : fails on any detected errors;
13435 - "utf8s" : never fails, but removes characters corresponding to errors;
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013436 - "utf8p" : accepts and fixes the overlong errors, but fails on any other
Davor Ocelice9ed2812017-12-25 17:49:28 +010013437 error;
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013438 - "utf8ps" : never fails, accepts and fixes the overlong errors, but removes
13439 characters corresponding to the other errors.
13440
13441 This converter is particularly useful for building properly escaped JSON for
Davor Ocelice9ed2812017-12-25 17:49:28 +010013442 logging to servers which consume JSON-formatted traffic logs.
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013443
13444 Example:
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013445 capture request header Host len 15
Herve COMMOWICK8dfe8632016-08-05 12:01:20 +020013446 capture request header user-agent len 150
13447 log-format '{"ip":"%[src]","user-agent":"%[capture.req.hdr(1),json(utf8s)]"}'
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020013448
13449 Input request from client 127.0.0.1:
13450 GET / HTTP/1.0
13451 User-Agent: Very "Ugly" UA 1/2
13452
13453 Output log:
13454 {"ip":"127.0.0.1","user-agent":"Very \"Ugly\" UA 1\/2"}
13455
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013456language(<value>[,<default>])
13457 Returns the value with the highest q-factor from a list as extracted from the
13458 "accept-language" header using "req.fhdr". Values with no q-factor have a
13459 q-factor of 1. Values with a q-factor of 0 are dropped. Only values which
13460 belong to the list of semi-colon delimited <values> will be considered. The
13461 argument <value> syntax is "lang[;lang[;lang[;...]]]". If no value matches the
13462 given list and a default value is provided, it is returned. Note that language
13463 names may have a variant after a dash ('-'). If this variant is present in the
13464 list, it will be matched, but if it is not, only the base language is checked.
13465 The match is case-sensitive, and the output string is always one of those
Davor Ocelice9ed2812017-12-25 17:49:28 +010013466 provided in arguments. The ordering of arguments is meaningless, only the
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013467 ordering of the values in the request counts, as the first value among
13468 multiple sharing the same q-factor is used.
Thierry FOURNIERad903512014-04-11 17:51:01 +020013469
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013470 Example :
Thierry FOURNIERad903512014-04-11 17:51:01 +020013471
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013472 # this configuration switches to the backend matching a
13473 # given language based on the request :
Thierry FOURNIERad903512014-04-11 17:51:01 +020013474
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013475 acl es req.fhdr(accept-language),language(es;fr;en) -m str es
13476 acl fr req.fhdr(accept-language),language(es;fr;en) -m str fr
13477 acl en req.fhdr(accept-language),language(es;fr;en) -m str en
13478 use_backend spanish if es
13479 use_backend french if fr
13480 use_backend english if en
13481 default_backend choose_your_language
Thierry FOURNIERad903512014-04-11 17:51:01 +020013482
Willy Tarreau60a2ee72017-12-15 07:13:48 +010013483length
Etienne Carriereed0d24e2017-12-13 13:41:34 +010013484 Get the length of the string. This can only be placed after a string
13485 sample fetch function or after a transformation keyword returning a string
13486 type. The result is of type integer.
13487
Willy Tarreauffcb2e42014-07-10 16:29:08 +020013488lower
13489 Convert a string sample to lower case. This can only be placed after a string
13490 sample fetch function or after a transformation keyword returning a string
13491 type. The result is of type string.
13492
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020013493ltime(<format>[,<offset>])
13494 Converts an integer supposed to contain a date since epoch to a string
13495 representing this date in local time using a format defined by the <format>
13496 string using strftime(3). The purpose is to allow any date format to be used
13497 in logs. An optional <offset> in seconds may be applied to the input date
13498 (positive or negative). See the strftime() man page for the format supported
13499 by your operating system. See also the utime converter.
13500
13501 Example :
13502
13503 # Emit two colons, one with the local time and another with ip:port
Davor Ocelice9ed2812017-12-25 17:49:28 +010013504 # e.g. 20140710162350 127.0.0.1:57325
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020013505 log-format %[date,ltime(%Y%m%d%H%M%S)]\ %ci:%cp
13506
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013507map(<map_file>[,<default_value>])
13508map_<match_type>(<map_file>[,<default_value>])
13509map_<match_type>_<output_type>(<map_file>[,<default_value>])
13510 Search the input value from <map_file> using the <match_type> matching method,
13511 and return the associated value converted to the type <output_type>. If the
13512 input value cannot be found in the <map_file>, the converter returns the
13513 <default_value>. If the <default_value> is not set, the converter fails and
13514 acts as if no input value could be fetched. If the <match_type> is not set, it
13515 defaults to "str". Likewise, if the <output_type> is not set, it defaults to
13516 "str". For convenience, the "map" keyword is an alias for "map_str" and maps a
13517 string to another string.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013518
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013519 It is important to avoid overlapping between the keys : IP addresses and
13520 strings are stored in trees, so the first of the finest match will be used.
13521 Other keys are stored in lists, so the first matching occurrence will be used.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013522
Tim Düsterhus4896c442016-11-29 02:15:19 +010013523 The following array contains the list of all map functions available sorted by
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013524 input type, match type and output type.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013525
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013526 input type | match method | output type str | output type int | output type ip
13527 -----------+--------------+-----------------+-----------------+---------------
13528 str | str | map_str | map_str_int | map_str_ip
13529 -----------+--------------+-----------------+-----------------+---------------
Willy Tarreau787a4c02014-05-10 07:55:30 +020013530 str | beg | map_beg | map_beg_int | map_end_ip
13531 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013532 str | sub | map_sub | map_sub_int | map_sub_ip
13533 -----------+--------------+-----------------+-----------------+---------------
13534 str | dir | map_dir | map_dir_int | map_dir_ip
13535 -----------+--------------+-----------------+-----------------+---------------
13536 str | dom | map_dom | map_dom_int | map_dom_ip
13537 -----------+--------------+-----------------+-----------------+---------------
13538 str | end | map_end | map_end_int | map_end_ip
13539 -----------+--------------+-----------------+-----------------+---------------
Ruoshan Huang3c5e3742016-12-02 16:25:31 +080013540 str | reg | map_reg | map_reg_int | map_reg_ip
13541 -----------+--------------+-----------------+-----------------+---------------
13542 str | reg | map_regm | map_reg_int | map_reg_ip
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013543 -----------+--------------+-----------------+-----------------+---------------
13544 int | int | map_int | map_int_int | map_int_ip
13545 -----------+--------------+-----------------+-----------------+---------------
13546 ip | ip | map_ip | map_ip_int | map_ip_ip
13547 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013548
Thierry Fournier8feaa662016-02-10 22:55:20 +010013549 The special map called "map_regm" expect matching zone in the regular
13550 expression and modify the output replacing back reference (like "\1") by
13551 the corresponding match text.
13552
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013553 The file contains one key + value per line. Lines which start with '#' are
13554 ignored, just like empty lines. Leading tabs and spaces are stripped. The key
13555 is then the first "word" (series of non-space/tabs characters), and the value
13556 is what follows this series of space/tab till the end of the line excluding
13557 trailing spaces/tabs.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013558
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013559 Example :
13560
13561 # this is a comment and is ignored
13562 2.22.246.0/23 United Kingdom \n
13563 <-><-----------><--><------------><---->
13564 | | | | `- trailing spaces ignored
13565 | | | `---------- value
13566 | | `-------------------- middle spaces ignored
13567 | `---------------------------- key
13568 `------------------------------------ leading spaces ignored
13569
Willy Tarreau97707872015-01-27 15:12:13 +010013570mod(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013571 Divides the input value of type signed integer by <value>, and returns the
13572 remainder as an signed integer. If <value> is null, then zero is returned.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013573 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010013574 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013575 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013576 "sess" : the variable is shared with the whole session
13577 "txn" : the variable is shared with the transaction (request and response)
13578 "req" : the variable is shared only during request processing
13579 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013580 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013581 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013582
13583mul(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013584 Multiplies the input value of type signed integer by <value>, and returns
Thierry FOURNIER00c005c2015-07-08 01:10:21 +020013585 the product as an signed integer. In case of overflow, the largest possible
13586 value for the sign is returned so that the operation doesn't wrap around.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013587 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010013588 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013589 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013590 "sess" : the variable is shared with the whole session
13591 "txn" : the variable is shared with the transaction (request and response)
13592 "req" : the variable is shared only during request processing
13593 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013594 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013595 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013596
Nenad Merdanovicb7e7c472017-03-12 21:56:55 +010013597nbsrv
13598 Takes an input value of type string, interprets it as a backend name and
13599 returns the number of usable servers in that backend. Can be used in places
13600 where we want to look up a backend from a dynamic name, like a result of a
13601 map lookup.
13602
Willy Tarreau97707872015-01-27 15:12:13 +010013603neg
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013604 Takes the input value of type signed integer, computes the opposite value,
13605 and returns the remainder as an signed integer. 0 is identity. This operator
13606 is provided for reversed subtracts : in order to subtract the input from a
13607 constant, simply perform a "neg,add(value)".
Willy Tarreau97707872015-01-27 15:12:13 +010013608
13609not
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013610 Returns a boolean FALSE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010013611 non-null, otherwise returns TRUE. Used in conjunction with and(), it can be
Davor Ocelice9ed2812017-12-25 17:49:28 +010013612 used to report true/false for bit testing on input values (e.g. verify the
Willy Tarreau97707872015-01-27 15:12:13 +010013613 absence of a flag).
13614
13615odd
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013616 Returns a boolean TRUE if the input value of type signed integer is odd
Willy Tarreau97707872015-01-27 15:12:13 +010013617 otherwise returns FALSE. It is functionally equivalent to "and(1),bool".
13618
13619or(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013620 Performs a bitwise "OR" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013621 integer, and returns the result as an signed integer. <value> can be a
Daniel Schneller0b547052016-03-21 20:46:57 +010013622 numeric value or a variable name. The name of the variable starts with an
13623 indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013624 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013625 "sess" : the variable is shared with the whole session
13626 "txn" : the variable is shared with the transaction (request and response)
13627 "req" : the variable is shared only during request processing
13628 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013629 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013630 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013631
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010013632protobuf(<field_number>,[<field_type>])
13633 This extracts the protocol buffers message field in raw mode of an input binary
13634 sample representation of a protocol buffer message with <field_number> as field
13635 number (dotted notation) if <field_type> is not present, or as an integer sample
13636 if this field is present (see also "ungrpc" below).
13637 The list of the authorized types is the following one: "int32", "int64", "uint32",
13638 "uint64", "sint32", "sint64", "bool", "enum" for the "varint" wire type 0
13639 "fixed64", "sfixed64", "double" for the 64bit wire type 1, "fixed32", "sfixed32",
13640 "float" for the wire type 5. Note that "string" is considered as a length-delimited
13641 type, so it does not require any <field_type> argument to be extracted.
13642 More information may be found here about the protocol buffers message field types:
13643 https://developers.google.com/protocol-buffers/docs/encoding
13644
Willy Tarreauc4dc3502015-01-23 20:39:28 +010013645regsub(<regex>,<subst>[,<flags>])
Willy Tarreau7eda8492015-01-20 19:47:06 +010013646 Applies a regex-based substitution to the input string. It does the same
13647 operation as the well-known "sed" utility with "s/<regex>/<subst>/". By
13648 default it will replace in the input string the first occurrence of the
13649 largest part matching the regular expression <regex> with the substitution
13650 string <subst>. It is possible to replace all occurrences instead by adding
13651 the flag "g" in the third argument <flags>. It is also possible to make the
13652 regex case insensitive by adding the flag "i" in <flags>. Since <flags> is a
13653 string, it is made up from the concatenation of all desired flags. Thus if
13654 both "i" and "g" are desired, using "gi" or "ig" will have the same effect.
13655 It is important to note that due to the current limitations of the
Baptiste Assmann66025d82016-03-06 23:36:48 +010013656 configuration parser, some characters such as closing parenthesis, closing
13657 square brackets or comma are not possible to use in the arguments. The first
13658 use of this converter is to replace certain characters or sequence of
13659 characters with other ones.
Willy Tarreau7eda8492015-01-20 19:47:06 +010013660
13661 Example :
13662
13663 # de-duplicate "/" in header "x-path".
13664 # input: x-path: /////a///b/c/xzxyz/
13665 # output: x-path: /a/b/c/xzxyz/
13666 http-request set-header x-path %[hdr(x-path),regsub(/+,/,g)]
13667
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020013668capture-req(<id>)
13669 Capture the string entry in the request slot <id> and returns the entry as
13670 is. If the slot doesn't exist, the capture fails silently.
13671
13672 See also: "declare capture", "http-request capture",
Baptiste Assmann5ac425c2015-10-21 23:13:46 +020013673 "http-response capture", "capture.req.hdr" and
13674 "capture.res.hdr" (sample fetches).
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020013675
13676capture-res(<id>)
13677 Capture the string entry in the response slot <id> and returns the entry as
13678 is. If the slot doesn't exist, the capture fails silently.
13679
13680 See also: "declare capture", "http-request capture",
Baptiste Assmann5ac425c2015-10-21 23:13:46 +020013681 "http-response capture", "capture.req.hdr" and
13682 "capture.res.hdr" (sample fetches).
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020013683
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013684sdbm([<avalanche>])
13685 Hashes a binary input sample into an unsigned 32-bit quantity using the SDBM
13686 hash function. Optionally, it is possible to apply a full avalanche hash
13687 function to the output if the optional <avalanche> argument equals 1. This
13688 converter uses the same functions as used by the various hash-based load
13689 balancing algorithms, so it will provide exactly the same results. It is
13690 mostly intended for debugging, but can be used as a stick-table entry to
13691 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010013692 32-bit hash is trivial to break. See also "crc32", "djb2", "wt6", "crc32c",
13693 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013694
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013695set-var(<var name>)
Davor Ocelice9ed2812017-12-25 17:49:28 +010013696 Sets a variable with the input content and returns the content on the output
13697 as-is. The variable keeps the value and the associated input type. The name of
13698 the variable starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013699 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013700 "sess" : the variable is shared with the whole session
13701 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013702 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010013703 "req" : the variable is shared only during request processing,
13704 "res" : the variable is shared only during response processing.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013705 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013706 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013707
Dragan Dosen6e5a9ca2017-10-24 09:18:23 +020013708sha1
Tim Duesterhusd4376302019-06-17 12:41:44 +020013709 Converts a binary input sample to a SHA-1 digest. The result is a binary
Dragan Dosen6e5a9ca2017-10-24 09:18:23 +020013710 sample with length of 20 bytes.
13711
Tim Duesterhusd4376302019-06-17 12:41:44 +020013712sha2([<bits>])
13713 Converts a binary input sample to a digest in the SHA-2 family. The result
13714 is a binary sample with length of <bits>/8 bytes.
13715
13716 Valid values for <bits> are 224, 256, 384, 512, each corresponding to
13717 SHA-<bits>. The default value is 256.
13718
13719 Please note that this converter is only available when haproxy has been
13720 compiled with USE_OPENSSL.
13721
Nenad Merdanovic177adc92019-08-27 01:58:13 +020013722srv_queue
13723 Takes an input value of type string, either a server name or <backend>/<server>
13724 format and returns the number of queued sessions on that server. Can be used
13725 in places where we want to look up queued sessions from a dynamic name, like a
13726 cookie value (e.g. req.cook(SRVID),srv_queue) and then make a decision to break
13727 persistence or direct a request elsewhere.
13728
Tim Duesterhusca097c12018-04-27 21:18:45 +020013729strcmp(<var>)
13730 Compares the contents of <var> with the input value of type string. Returns
13731 the result as a signed integer compatible with strcmp(3): 0 if both strings
13732 are identical. A value less than 0 if the left string is lexicographically
13733 smaller than the right string or if the left string is shorter. A value greater
13734 than 0 otherwise (right string greater than left string or the right string is
13735 shorter).
13736
13737 Example :
13738
13739 http-request set-var(txn.host) hdr(host)
13740 # Check whether the client is attempting domain fronting.
13741 acl ssl_sni_http_host_match ssl_fc_sni,strcmp(txn.host) eq 0
13742
13743
Willy Tarreau97707872015-01-27 15:12:13 +010013744sub(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013745 Subtracts <value> from the input value of type signed integer, and returns
13746 the result as an signed integer. Note: in order to subtract the input from
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013747 a constant, simply perform a "neg,add(value)". <value> can be a numeric value
Daniel Schneller0b547052016-03-21 20:46:57 +010013748 or a variable name. The name of the variable starts with an indication about
13749 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013750 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013751 "sess" : the variable is shared with the whole session
13752 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013753 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010013754 "req" : the variable is shared only during request processing,
13755 "res" : the variable is shared only during response processing.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013756 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013757 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013758
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013759table_bytes_in_rate(<table>)
13760 Uses the string representation of the input sample to perform a look up in
13761 the specified table. If the key is not found in the table, integer value zero
13762 is returned. Otherwise the converter returns the average client-to-server
13763 bytes rate associated with the input sample in the designated table, measured
13764 in amount of bytes over the period configured in the table. See also the
13765 sc_bytes_in_rate sample fetch keyword.
13766
13767
13768table_bytes_out_rate(<table>)
13769 Uses the string representation of the input sample to perform a look up in
13770 the specified table. If the key is not found in the table, integer value zero
13771 is returned. Otherwise the converter returns the average server-to-client
13772 bytes rate associated with the input sample in the designated table, measured
13773 in amount of bytes over the period configured in the table. See also the
13774 sc_bytes_out_rate sample fetch keyword.
13775
13776table_conn_cnt(<table>)
13777 Uses the string representation of the input sample to perform a look up in
13778 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010013779 is returned. Otherwise the converter returns the cumulative number of incoming
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013780 connections associated with the input sample in the designated table. See
13781 also the sc_conn_cnt sample fetch keyword.
13782
13783table_conn_cur(<table>)
13784 Uses the string representation of the input sample to perform a look up in
13785 the specified table. If the key is not found in the table, integer value zero
13786 is returned. Otherwise the converter returns the current amount of concurrent
13787 tracked connections associated with the input sample in the designated table.
13788 See also the sc_conn_cur sample fetch keyword.
13789
13790table_conn_rate(<table>)
13791 Uses the string representation of the input sample to perform a look up in
13792 the specified table. If the key is not found in the table, integer value zero
13793 is returned. Otherwise the converter returns the average incoming connection
13794 rate associated with the input sample in the designated table. See also the
13795 sc_conn_rate sample fetch keyword.
13796
Thierry FOURNIER236657b2015-08-19 08:25:14 +020013797table_gpt0(<table>)
13798 Uses the string representation of the input sample to perform a look up in
13799 the specified table. If the key is not found in the table, boolean value zero
13800 is returned. Otherwise the converter returns the current value of the first
13801 general purpose tag associated with the input sample in the designated table.
13802 See also the sc_get_gpt0 sample fetch keyword.
13803
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013804table_gpc0(<table>)
13805 Uses the string representation of the input sample to perform a look up in
13806 the specified table. If the key is not found in the table, integer value zero
13807 is returned. Otherwise the converter returns the current value of the first
13808 general purpose counter associated with the input sample in the designated
13809 table. See also the sc_get_gpc0 sample fetch keyword.
13810
13811table_gpc0_rate(<table>)
13812 Uses the string representation of the input sample to perform a look up in
13813 the specified table. If the key is not found in the table, integer value zero
13814 is returned. Otherwise the converter returns the frequency which the gpc0
13815 counter was incremented over the configured period in the table, associated
13816 with the input sample in the designated table. See also the sc_get_gpc0_rate
13817 sample fetch keyword.
13818
Frédéric Lécaille6778b272018-01-29 15:22:53 +010013819table_gpc1(<table>)
13820 Uses the string representation of the input sample to perform a look up in
13821 the specified table. If the key is not found in the table, integer value zero
13822 is returned. Otherwise the converter returns the current value of the second
13823 general purpose counter associated with the input sample in the designated
13824 table. See also the sc_get_gpc1 sample fetch keyword.
13825
13826table_gpc1_rate(<table>)
13827 Uses the string representation of the input sample to perform a look up in
13828 the specified table. If the key is not found in the table, integer value zero
13829 is returned. Otherwise the converter returns the frequency which the gpc1
13830 counter was incremented over the configured period in the table, associated
13831 with the input sample in the designated table. See also the sc_get_gpc1_rate
13832 sample fetch keyword.
13833
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013834table_http_err_cnt(<table>)
13835 Uses the string representation of the input sample to perform a look up in
13836 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010013837 is returned. Otherwise the converter returns the cumulative number of HTTP
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013838 errors associated with the input sample in the designated table. See also the
13839 sc_http_err_cnt sample fetch keyword.
13840
13841table_http_err_rate(<table>)
13842 Uses the string representation of the input sample to perform a look up in
13843 the specified table. If the key is not found in the table, integer value zero
13844 is returned. Otherwise the average rate of HTTP errors associated with the
13845 input sample in the designated table, measured in amount of errors over the
13846 period configured in the table. See also the sc_http_err_rate sample fetch
13847 keyword.
13848
13849table_http_req_cnt(<table>)
13850 Uses the string representation of the input sample to perform a look up in
13851 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010013852 is returned. Otherwise the converter returns the cumulative number of HTTP
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013853 requests associated with the input sample in the designated table. See also
13854 the sc_http_req_cnt sample fetch keyword.
13855
13856table_http_req_rate(<table>)
13857 Uses the string representation of the input sample to perform a look up in
13858 the specified table. If the key is not found in the table, integer value zero
13859 is returned. Otherwise the average rate of HTTP requests associated with the
13860 input sample in the designated table, measured in amount of requests over the
13861 period configured in the table. See also the sc_http_req_rate sample fetch
13862 keyword.
13863
13864table_kbytes_in(<table>)
13865 Uses the string representation of the input sample to perform a look up in
13866 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010013867 is returned. Otherwise the converter returns the cumulative number of client-
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013868 to-server data associated with the input sample in the designated table,
13869 measured in kilobytes. The test is currently performed on 32-bit integers,
13870 which limits values to 4 terabytes. See also the sc_kbytes_in sample fetch
13871 keyword.
13872
13873table_kbytes_out(<table>)
13874 Uses the string representation of the input sample to perform a look up in
13875 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010013876 is returned. Otherwise the converter returns the cumulative number of server-
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013877 to-client data associated with the input sample in the designated table,
13878 measured in kilobytes. The test is currently performed on 32-bit integers,
13879 which limits values to 4 terabytes. See also the sc_kbytes_out sample fetch
13880 keyword.
13881
13882table_server_id(<table>)
13883 Uses the string representation of the input sample to perform a look up in
13884 the specified table. If the key is not found in the table, integer value zero
13885 is returned. Otherwise the converter returns the server ID associated with
13886 the input sample in the designated table. A server ID is associated to a
13887 sample by a "stick" rule when a connection to a server succeeds. A server ID
13888 zero means that no server is associated with this key.
13889
13890table_sess_cnt(<table>)
13891 Uses the string representation of the input sample to perform a look up in
13892 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010013893 is returned. Otherwise the converter returns the cumulative number of incoming
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013894 sessions associated with the input sample in the designated table. Note that
13895 a session here refers to an incoming connection being accepted by the
13896 "tcp-request connection" rulesets. See also the sc_sess_cnt sample fetch
13897 keyword.
13898
13899table_sess_rate(<table>)
13900 Uses the string representation of the input sample to perform a look up in
13901 the specified table. If the key is not found in the table, integer value zero
13902 is returned. Otherwise the converter returns the average incoming session
13903 rate associated with the input sample in the designated table. Note that a
13904 session here refers to an incoming connection being accepted by the
13905 "tcp-request connection" rulesets. See also the sc_sess_rate sample fetch
13906 keyword.
13907
13908table_trackers(<table>)
13909 Uses the string representation of the input sample to perform a look up in
13910 the specified table. If the key is not found in the table, integer value zero
13911 is returned. Otherwise the converter returns the current amount of concurrent
13912 connections tracking the same key as the input sample in the designated
13913 table. It differs from table_conn_cur in that it does not rely on any stored
13914 information but on the table's reference count (the "use" value which is
13915 returned by "show table" on the CLI). This may sometimes be more suited for
13916 layer7 tracking. It can be used to tell a server how many concurrent
13917 connections there are from a given address for example. See also the
13918 sc_trackers sample fetch keyword.
13919
Willy Tarreauffcb2e42014-07-10 16:29:08 +020013920upper
13921 Convert a string sample to upper case. This can only be placed after a string
13922 sample fetch function or after a transformation keyword returning a string
13923 type. The result is of type string.
13924
Thierry FOURNIER82ff3c92015-05-07 15:46:20 +020013925url_dec
13926 Takes an url-encoded string provided as input and returns the decoded
13927 version as output. The input and the output are of type string.
13928
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010013929ungrpc(<field_number>,[<field_type>])
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010013930 This extracts the protocol buffers message field in raw mode of an input binary
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010013931 sample representation of a gRPC message with <field_number> as field number
13932 (dotted notation) if <field_type> is not present, or as an integer sample if this
13933 field is present.
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010013934 The list of the authorized types is the following one: "int32", "int64", "uint32",
13935 "uint64", "sint32", "sint64", "bool", "enum" for the "varint" wire type 0
13936 "fixed64", "sfixed64", "double" for the 64bit wire type 1, "fixed32", "sfixed32",
13937 "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 +010013938 type, so it does not require any <field_type> argument to be extracted.
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010013939 More information may be found here about the protocol buffers message field types:
13940 https://developers.google.com/protocol-buffers/docs/encoding
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010013941
13942 Example:
13943 // with such a protocol buffer .proto file content adapted from
13944 // https://github.com/grpc/grpc/blob/master/examples/protos/route_guide.proto
13945
13946 message Point {
13947 int32 latitude = 1;
13948 int32 longitude = 2;
13949 }
13950
13951 message PPoint {
13952 Point point = 59;
13953 }
13954
13955 message Rectangle {
13956 // One corner of the rectangle.
13957 PPoint lo = 48;
13958 // The other corner of the rectangle.
13959 PPoint hi = 49;
13960 }
13961
13962 let's say a body request is made of a "Rectangle" object value (two PPoint
13963 protocol buffers messages), the four protocol buffers fields could be
13964 extracted with these "ungrpc" directives:
13965
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010013966 req.body,ungrpc(48.59.1,int32) # "latitude" of "lo" first PPoint
13967 req.body,ungrpc(48.59.2,int32) # "longitude" of "lo" first PPoint
John Roeslerfb2fce12019-07-10 15:45:51 -050013968 req.body,ungrpc(49.59.1,int32) # "latitude" of "hi" second PPoint
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010013969 req.body,ungrpc(49.59.2,int32) # "longitude" of "hi" second PPoint
13970
Frédéric Lécaille93d33162019-03-06 09:35:59 +010013971 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 +010013972
Frédéric Lécaille93d33162019-03-06 09:35:59 +010013973 req.body,ungrpc(48.59)
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010013974
John Roeslerfb2fce12019-07-10 15:45:51 -050013975 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 +010013976 messages, in the previous example the "latitude" of "lo" first PPoint
13977 could be extracted with these equivalent directives:
13978
13979 req.body,ungrpc(48.59),protobuf(1,int32)
13980 req.body,ungrpc(48),protobuf(59.1,int32)
13981 req.body,ungrpc(48),protobuf(59),protobuf(1,int32)
13982
13983 Note that the first convert must be "ungrpc", the remaining ones must be
13984 "protobuf" and only the last one may have or not a second argument to
13985 interpret the previous binary sample.
13986
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010013987
Christopher Faulet85d79c92016-11-09 16:54:56 +010013988unset-var(<var name>)
13989 Unsets a variable if the input content is defined. The name of the variable
13990 starts with an indication about its scope. The scopes allowed are:
13991 "proc" : the variable is shared with the whole process
13992 "sess" : the variable is shared with the whole session
13993 "txn" : the variable is shared with the transaction (request and
13994 response),
13995 "req" : the variable is shared only during request processing,
13996 "res" : the variable is shared only during response processing.
13997 This prefix is followed by a name. The separator is a '.'. The name may only
13998 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
13999
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020014000utime(<format>[,<offset>])
14001 Converts an integer supposed to contain a date since epoch to a string
14002 representing this date in UTC time using a format defined by the <format>
14003 string using strftime(3). The purpose is to allow any date format to be used
14004 in logs. An optional <offset> in seconds may be applied to the input date
14005 (positive or negative). See the strftime() man page for the format supported
14006 by your operating system. See also the ltime converter.
14007
14008 Example :
14009
14010 # Emit two colons, one with the UTC time and another with ip:port
Davor Ocelice9ed2812017-12-25 17:49:28 +010014011 # e.g. 20140710162350 127.0.0.1:57325
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020014012 log-format %[date,utime(%Y%m%d%H%M%S)]\ %ci:%cp
14013
Marcin Deranek9631a282018-04-16 14:30:46 +020014014word(<index>,<delimiters>[,<count>])
14015 Extracts the nth word counting from the beginning (positive index) or from
14016 the end (negative index) considering given delimiters from an input string.
14017 Indexes start at 1 or -1 and delimiters are a string formatted list of chars.
14018 Optionally you can specify <count> of words to extract (default: 1).
14019 Value of 0 indicates extraction of all remaining words.
14020
14021 Example :
14022 str(f1_f2_f3__f5),word(4,_) # f5
14023 str(f1_f2_f3__f5),word(2,_,0) # f2_f3__f5
14024 str(f1_f2_f3__f5),word(3,_,2) # f3__f5
14025 str(f1_f2_f3__f5),word(-2,_,3) # f1_f2_f3
14026 str(f1_f2_f3__f5),word(-3,_,0) # f1_f2
Emeric Brunc9a0f6d2014-11-25 14:09:01 +010014027
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020014028wt6([<avalanche>])
14029 Hashes a binary input sample into an unsigned 32-bit quantity using the WT6
14030 hash function. Optionally, it is possible to apply a full avalanche hash
14031 function to the output if the optional <avalanche> argument equals 1. This
14032 converter uses the same functions as used by the various hash-based load
14033 balancing algorithms, so it will provide exactly the same results. It is
14034 mostly intended for debugging, but can be used as a stick-table entry to
14035 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010014036 32-bit hash is trivial to break. See also "crc32", "djb2", "sdbm", "crc32c",
14037 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020014038
Willy Tarreau97707872015-01-27 15:12:13 +010014039xor(<value>)
14040 Performs a bitwise "XOR" (exclusive OR) between <value> and the input value
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014041 of type signed integer, and returns the result as an signed integer.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014042 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010014043 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010014044 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010014045 "sess" : the variable is shared with the whole session
14046 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014047 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010014048 "req" : the variable is shared only during request processing,
14049 "res" : the variable is shared only during response processing.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014050 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010014051 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010014052
Thierry FOURNIER01e09742016-12-26 11:46:11 +010014053xxh32([<seed>])
14054 Hashes a binary input sample into an unsigned 32-bit quantity using the 32-bit
14055 variant of the XXHash hash function. This hash supports a seed which defaults
14056 to zero but a different value maybe passed as the <seed> argument. This hash
14057 is known to be very good and very fast so it can be used to hash URLs and/or
14058 URL parameters for use as stick-table keys to collect statistics with a low
14059 collision rate, though care must be taken as the algorithm is not considered
14060 as cryptographically secure.
14061
14062xxh64([<seed>])
14063 Hashes a binary input sample into a signed 64-bit quantity using the 64-bit
14064 variant of the XXHash hash function. This hash supports a seed which defaults
14065 to zero but a different value maybe passed as the <seed> argument. This hash
14066 is known to be very good and very fast so it can be used to hash URLs and/or
14067 URL parameters for use as stick-table keys to collect statistics with a low
14068 collision rate, though care must be taken as the algorithm is not considered
14069 as cryptographically secure.
14070
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010014071
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200140727.3.2. Fetching samples from internal states
Willy Tarreau74ca5042013-06-11 23:12:07 +020014073--------------------------------------------
14074
14075A first set of sample fetch methods applies to internal information which does
14076not even relate to any client information. These ones are sometimes used with
14077"monitor-fail" directives to report an internal status to external watchers.
14078The sample fetch methods described in this section are usable anywhere.
14079
14080always_false : boolean
14081 Always returns the boolean "false" value. It may be used with ACLs as a
14082 temporary replacement for another one when adjusting configurations.
14083
14084always_true : boolean
14085 Always returns the boolean "true" value. It may be used with ACLs as a
14086 temporary replacement for another one when adjusting configurations.
14087
14088avg_queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010014089 Returns the total number of queued connections of the designated backend
Willy Tarreau74ca5042013-06-11 23:12:07 +020014090 divided by the number of active servers. The current backend is used if no
14091 backend is specified. This is very similar to "queue" except that the size of
14092 the farm is considered, in order to give a more accurate measurement of the
14093 time it may take for a new connection to be processed. The main usage is with
14094 ACL to return a sorry page to new users when it becomes certain they will get
14095 a degraded service, or to pass to the backend servers in a header so that
14096 they decide to work in degraded mode or to disable some functions to speed up
14097 the processing a bit. Note that in the event there would not be any active
14098 server anymore, twice the number of queued connections would be considered as
14099 the measured value. This is a fair estimate, as we expect one server to get
14100 back soon anyway, but we still prefer to send new traffic to another backend
14101 if in better shape. See also the "queue", "be_conn", and "be_sess_rate"
14102 sample fetches.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +010014103
Willy Tarreau74ca5042013-06-11 23:12:07 +020014104be_conn([<backend>]) : integer
Willy Tarreaua36af912009-10-10 12:02:45 +020014105 Applies to the number of currently established connections on the backend,
14106 possibly including the connection being evaluated. If no backend name is
14107 specified, the current one is used. But it is also possible to check another
14108 backend. It can be used to use a specific farm when the nominal one is full.
Patrick Hemmer4cdf3ab2018-06-14 17:10:27 -040014109 See also the "fe_conn", "queue", "be_conn_free", and "be_sess_rate" criteria.
14110
14111be_conn_free([<backend>]) : integer
14112 Returns an integer value corresponding to the number of available connections
14113 across available servers in the backend. Queue slots are not included. Backup
14114 servers are also not included, unless all other servers are down. If no
14115 backend name is specified, the current one is used. But it is also possible
14116 to check another backend. It can be used to use a specific farm when the
Patrick Hemmer155e93e2018-06-14 18:01:35 -040014117 nominal one is full. See also the "be_conn", "connslots", and "srv_conn_free"
14118 criteria.
Patrick Hemmer4cdf3ab2018-06-14 17:10:27 -040014119
14120 OTHER CAVEATS AND NOTES: if any of the server maxconn, or maxqueue is 0
14121 (meaning unlimited), then this fetch clearly does not make sense, in which
14122 case the value returned will be -1.
Willy Tarreau6a06a402007-07-15 20:15:28 +020014123
Willy Tarreau74ca5042013-06-11 23:12:07 +020014124be_sess_rate([<backend>]) : integer
14125 Returns an integer value corresponding to the sessions creation rate on the
14126 backend, in number of new sessions per second. This is used with ACLs to
14127 switch to an alternate backend when an expensive or fragile one reaches too
Davor Ocelice9ed2812017-12-25 17:49:28 +010014128 high a session rate, or to limit abuse of service (e.g. prevent sucking of an
Willy Tarreau74ca5042013-06-11 23:12:07 +020014129 online dictionary). It can also be useful to add this element to logs using a
14130 log-format directive.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014131
14132 Example :
14133 # Redirect to an error page if the dictionary is requested too often
14134 backend dynamic
14135 mode http
14136 acl being_scanned be_sess_rate gt 100
14137 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +010014138
Davor Ocelice9ed2812017-12-25 17:49:28 +010014139bin(<hex>) : bin
Thierry FOURNIERcc103292015-06-06 19:30:17 +020014140 Returns a binary chain. The input is the hexadecimal representation
14141 of the string.
14142
14143bool(<bool>) : bool
14144 Returns a boolean value. <bool> can be 'true', 'false', '1' or '0'.
14145 'false' and '0' are the same. 'true' and '1' are the same.
14146
Willy Tarreau74ca5042013-06-11 23:12:07 +020014147connslots([<backend>]) : integer
14148 Returns an integer value corresponding to the number of connection slots
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014149 still available in the backend, by totaling the maximum amount of
Willy Tarreau74ca5042013-06-11 23:12:07 +020014150 connections on all servers and the maximum queue size. This is probably only
14151 used with ACLs.
Tait Clarridge7896d522012-12-05 21:39:31 -050014152
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080014153 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +020014154 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080014155 usage; see "use_backend" keyword) can be redirected to a different backend.
14156
Willy Tarreau55165fe2009-05-10 12:02:55 +020014157 'connslots' = number of available server connection slots, + number of
14158 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080014159
Willy Tarreaua36af912009-10-10 12:02:45 +020014160 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +020014161 useful when you have a case of traffic going to one single ip, splitting into
Willy Tarreau74ca5042013-06-11 23:12:07 +020014162 multiple backends (perhaps using ACLs to do name-based load balancing) and
Willy Tarreau55165fe2009-05-10 12:02:55 +020014163 you want to be able to differentiate between different backends, and their
Davor Ocelice9ed2812017-12-25 17:49:28 +010014164 available "connslots". Also, whereas "nbsrv" only measures servers that are
Willy Tarreau74ca5042013-06-11 23:12:07 +020014165 actually *down*, this fetch is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +020014166 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080014167
Willy Tarreau55165fe2009-05-10 12:02:55 +020014168 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
14169 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
Willy Tarreau74ca5042013-06-11 23:12:07 +020014170 then this fetch clearly does not make sense, in which case the value returned
Willy Tarreau55165fe2009-05-10 12:02:55 +020014171 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080014172
Willy Tarreau70fe9442018-11-22 16:07:39 +010014173cpu_calls : integer
14174 Returns the number of calls to the task processing the stream or current
14175 request since it was allocated. This number is reset for each new request on
14176 the same connections in case of HTTP keep-alive. This value should usually be
14177 low and stable (around 2 calls for a typically simple request) but may become
14178 high if some processing (compression, caching or analysis) is performed. This
14179 is purely for performance monitoring purposes.
14180
14181cpu_ns_avg : integer
14182 Returns the average number of nanoseconds spent in each call to the task
14183 processing the stream or current request. This number is reset for each new
14184 request on the same connections in case of HTTP keep-alive. This value
14185 indicates the overall cost of processing the request or the connection for
14186 each call. There is no good nor bad value but the time spent in a call
14187 automatically causes latency for other processing (see lat_ns_avg below),
14188 and may affect other connection's apparent response time. Certain operations
14189 like compression, complex regex matching or heavy Lua operations may directly
14190 affect this value, and having it in the logs will make it easier to spot the
14191 faulty processing that needs to be fixed to recover decent performance.
14192 Note: this value is exactly cpu_ns_tot divided by cpu_calls.
14193
14194cpu_ns_tot : integer
14195 Returns the total number of nanoseconds spent in each call to the task
14196 processing the stream or current request. This number is reset for each new
14197 request on the same connections in case of HTTP keep-alive. This value
14198 indicates the overall cost of processing the request or the connection for
14199 each call. There is no good nor bad value but the time spent in a call
14200 automatically causes latency for other processing (see lat_ns_avg below),
14201 induces CPU costs on the machine, and may affect other connection's apparent
14202 response time. Certain operations like compression, complex regex matching or
14203 heavy Lua operations may directly affect this value, and having it in the
14204 logs will make it easier to spot the faulty processing that needs to be fixed
14205 to recover decent performance. The value may be artificially high due to a
14206 high cpu_calls count, for example when processing many HTTP chunks, and for
14207 this reason it is often preferred to log cpu_ns_avg instead.
14208
Cyril Bonté6bcd1822019-11-05 23:13:59 +010014209date([<offset>],[<unit>]) : integer
Willy Tarreau6236d3a2013-07-25 14:28:25 +020014210 Returns the current date as the epoch (number of seconds since 01/01/1970).
Damien Claisseae6f1252019-10-30 15:57:28 +000014211
14212 If an offset value is specified, then it is added to the current date before
14213 returning the value. This is particularly useful to compute relative dates,
14214 as both positive and negative offsets are allowed.
Willy Tarreau276fae92013-07-25 14:36:01 +020014215 It is useful combined with the http_date converter.
14216
Damien Claisseae6f1252019-10-30 15:57:28 +000014217 <unit> is facultative, and can be set to "s" for seconds (default behavior),
14218 "ms" for milliseconds or "us" for microseconds.
14219 If unit is set, return value is an integer reflecting either seconds,
14220 milliseconds or microseconds since epoch, plus offset.
14221 It is useful when a time resolution of less than a second is needed.
14222
Willy Tarreau276fae92013-07-25 14:36:01 +020014223 Example :
14224
14225 # set an expires header to now+1 hour in every response
14226 http-response set-header Expires %[date(3600),http_date]
Willy Tarreau6236d3a2013-07-25 14:28:25 +020014227
Damien Claisseae6f1252019-10-30 15:57:28 +000014228 # set an expires header to now+1 hour in every response, with
14229 # millisecond granularity
14230 http-response set-header Expires %[date(3600000,ms),http_date(0,ms)]
14231
Etienne Carrierea792a0a2018-01-17 13:43:24 +010014232date_us : integer
14233 Return the microseconds part of the date (the "second" part is returned by
14234 date sample). This sample is coherent with the date sample as it is comes
14235 from the same timeval structure.
14236
Willy Tarreaud716f9b2017-10-13 11:03:15 +020014237distcc_body(<token>[,<occ>]) : binary
14238 Parses a distcc message and returns the body associated to occurrence #<occ>
14239 of the token <token>. Occurrences start at 1, and when unspecified, any may
14240 match though in practice only the first one is checked for now. This can be
14241 used to extract file names or arguments in files built using distcc through
14242 haproxy. Please refer to distcc's protocol documentation for the complete
14243 list of supported tokens.
14244
14245distcc_param(<token>[,<occ>]) : integer
14246 Parses a distcc message and returns the parameter associated to occurrence
14247 #<occ> of the token <token>. Occurrences start at 1, and when unspecified,
14248 any may match though in practice only the first one is checked for now. This
14249 can be used to extract certain information such as the protocol version, the
14250 file size or the argument in files built using distcc through haproxy.
14251 Another use case consists in waiting for the start of the preprocessed file
14252 contents before connecting to the server to avoid keeping idle connections.
14253 Please refer to distcc's protocol documentation for the complete list of
14254 supported tokens.
14255
14256 Example :
14257 # wait up to 20s for the pre-processed file to be uploaded
14258 tcp-request inspect-delay 20s
14259 tcp-request content accept if { distcc_param(DOTI) -m found }
14260 # send large files to the big farm
14261 use_backend big_farm if { distcc_param(DOTI) gt 1000000 }
14262
Willy Tarreau595ec542013-06-12 21:34:28 +020014263env(<name>) : string
14264 Returns a string containing the value of environment variable <name>. As a
14265 reminder, environment variables are per-process and are sampled when the
14266 process starts. This can be useful to pass some information to a next hop
14267 server, or with ACLs to take specific action when the process is started a
14268 certain way.
14269
14270 Examples :
14271 # Pass the Via header to next hop with the local hostname in it
14272 http-request add-header Via 1.1\ %[env(HOSTNAME)]
14273
14274 # reject cookie-less requests when the STOP environment variable is set
14275 http-request deny if !{ cook(SESSIONID) -m found } { env(STOP) -m found }
14276
Willy Tarreau74ca5042013-06-11 23:12:07 +020014277fe_conn([<frontend>]) : integer
14278 Returns the number of currently established connections on the frontend,
Willy Tarreaud63335a2010-02-26 12:56:52 +010014279 possibly including the connection being evaluated. If no frontend name is
14280 specified, the current one is used. But it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020014281 frontend. It can be used to return a sorry page before hard-blocking, or to
14282 use a specific backend to drain new requests when the farm is considered
Davor Ocelice9ed2812017-12-25 17:49:28 +010014283 full. This is mostly used with ACLs but can also be used to pass some
Willy Tarreau74ca5042013-06-11 23:12:07 +020014284 statistics to servers in HTTP headers. See also the "dst_conn", "be_conn",
14285 "fe_sess_rate" fetches.
Willy Tarreaua36af912009-10-10 12:02:45 +020014286
Nenad Merdanovicad9a7e92016-10-03 04:57:37 +020014287fe_req_rate([<frontend>]) : integer
14288 Returns an integer value corresponding to the number of HTTP requests per
14289 second sent to a frontend. This number can differ from "fe_sess_rate" in
14290 situations where client-side keep-alive is enabled.
14291
Willy Tarreau74ca5042013-06-11 23:12:07 +020014292fe_sess_rate([<frontend>]) : integer
14293 Returns an integer value corresponding to the sessions creation rate on the
14294 frontend, in number of new sessions per second. This is used with ACLs to
14295 limit the incoming session rate to an acceptable range in order to prevent
14296 abuse of service at the earliest moment, for example when combined with other
14297 layer 4 ACLs in order to force the clients to wait a bit for the rate to go
14298 down below the limit. It can also be useful to add this element to logs using
14299 a log-format directive. See also the "rate-limit sessions" directive for use
14300 in frontends.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010014301
14302 Example :
14303 # This frontend limits incoming mails to 10/s with a max of 100
14304 # concurrent connections. We accept any connection below 10/s, and
14305 # force excess clients to wait for 100 ms. Since clients are limited to
14306 # 100 max, there cannot be more than 10 incoming mails per second.
14307 frontend mail
14308 bind :25
14309 mode tcp
14310 maxconn 100
14311 acl too_fast fe_sess_rate ge 10
14312 tcp-request inspect-delay 100ms
14313 tcp-request content accept if ! too_fast
14314 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +010014315
Nenad Merdanovic807a6e72017-03-12 22:00:00 +010014316hostname : string
14317 Returns the system hostname.
14318
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014319int(<integer>) : signed integer
14320 Returns a signed integer.
14321
Thierry FOURNIERcc103292015-06-06 19:30:17 +020014322ipv4(<ipv4>) : ipv4
14323 Returns an ipv4.
14324
14325ipv6(<ipv6>) : ipv6
14326 Returns an ipv6.
14327
Willy Tarreau70fe9442018-11-22 16:07:39 +010014328lat_ns_avg : integer
14329 Returns the average number of nanoseconds spent between the moment the task
14330 handling the stream is woken up and the moment it is effectively called. This
14331 number is reset for each new request on the same connections in case of HTTP
14332 keep-alive. This value indicates the overall latency inflicted to the current
14333 request by all other requests being processed in parallel, and is a direct
14334 indicator of perceived performance due to noisy neighbours. In order to keep
14335 the value low, it is possible to reduce the scheduler's run queue depth using
14336 "tune.runqueue-depth", to reduce the number of concurrent events processed at
14337 once using "tune.maxpollevents", to decrease the stream's nice value using
14338 the "nice" option on the "bind" lines or in the frontend, or to look for
14339 other heavy requests in logs (those exhibiting large values of "cpu_ns_avg"),
14340 whose processing needs to be adjusted or fixed. Compression of large buffers
14341 could be a culprit, like heavy regex or long lists of regex.
14342 Note: this value is exactly lat_ns_tot divided by cpu_calls.
14343
14344lat_ns_tot : integer
14345 Returns the total number of nanoseconds spent between the moment the task
14346 handling the stream is woken up and the moment it is effectively called. This
14347 number is reset for each new request on the same connections in case of HTTP
14348 keep-alive. This value indicates the overall latency inflicted to the current
14349 request by all other requests being processed in parallel, and is a direct
14350 indicator of perceived performance due to noisy neighbours. In order to keep
14351 the value low, it is possible to reduce the scheduler's run queue depth using
14352 "tune.runqueue-depth", to reduce the number of concurrent events processed at
14353 once using "tune.maxpollevents", to decrease the stream's nice value using
14354 the "nice" option on the "bind" lines or in the frontend, or to look for
14355 other heavy requests in logs (those exhibiting large values of "cpu_ns_avg"),
14356 whose processing needs to be adjusted or fixed. Compression of large buffers
14357 could be a culprit, like heavy regex or long lists of regex. Note: while it
14358 may intuitively seem that the total latency adds to a transfer time, it is
14359 almost never true because while a task waits for the CPU, network buffers
14360 continue to fill up and the next call will process more at once. The value
14361 may be artificially high due to a high cpu_calls count, for example when
14362 processing many HTTP chunks, and for this reason it is often preferred to log
14363 lat_ns_avg instead, which is a more relevant performance indicator.
14364
Thierry FOURNIERcc103292015-06-06 19:30:17 +020014365meth(<method>) : method
14366 Returns a method.
14367
Willy Tarreau0f30d262014-11-24 16:02:05 +010014368nbproc : integer
14369 Returns an integer value corresponding to the number of processes that were
14370 started (it equals the global "nbproc" setting). This is useful for logging
14371 and debugging purposes.
14372
Willy Tarreau74ca5042013-06-11 23:12:07 +020014373nbsrv([<backend>]) : integer
14374 Returns an integer value corresponding to the number of usable servers of
14375 either the current backend or the named backend. This is mostly used with
14376 ACLs but can also be useful when added to logs. This is normally used to
Willy Tarreaud63335a2010-02-26 12:56:52 +010014377 switch to an alternate backend when the number of servers is too low to
14378 to handle some load. It is useful to report a failure when combined with
14379 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +010014380
Patrick Hemmerfabb24f2018-08-13 14:07:57 -040014381prio_class : integer
14382 Returns the priority class of the current session for http mode or connection
14383 for tcp mode. The value will be that set by the last call to "http-request
14384 set-priority-class" or "tcp-request content set-priority-class".
14385
14386prio_offset : integer
14387 Returns the priority offset of the current session for http mode or
14388 connection for tcp mode. The value will be that set by the last call to
14389 "http-request set-priority-offset" or "tcp-request content
14390 set-priority-offset".
14391
Willy Tarreau0f30d262014-11-24 16:02:05 +010014392proc : integer
14393 Returns an integer value corresponding to the position of the process calling
14394 the function, between 1 and global.nbproc. This is useful for logging and
14395 debugging purposes.
14396
Willy Tarreau74ca5042013-06-11 23:12:07 +020014397queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010014398 Returns the total number of queued connections of the designated backend,
14399 including all the connections in server queues. If no backend name is
14400 specified, the current one is used, but it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020014401 one. This is useful with ACLs or to pass statistics to backend servers. This
14402 can be used to take actions when queuing goes above a known level, generally
14403 indicating a surge of traffic or a massive slowdown on the servers. One
14404 possible action could be to reject new users but still accept old ones. See
14405 also the "avg_queue", "be_conn", and "be_sess_rate" fetches.
14406
Willy Tarreau84310e22014-02-14 11:59:04 +010014407rand([<range>]) : integer
14408 Returns a random integer value within a range of <range> possible values,
14409 starting at zero. If the range is not specified, it defaults to 2^32, which
14410 gives numbers between 0 and 4294967295. It can be useful to pass some values
14411 needed to take some routing decisions for example, or just for debugging
14412 purposes. This random must not be used for security purposes.
14413
Luca Schimweg8a694b82019-09-10 15:42:52 +020014414uuid([<version>]) : string
14415 Returns a UUID following the RFC4122 standard. If the version is not
14416 specified, a UUID version 4 (fully random) is returned.
14417 Currently, only version 4 is supported.
14418
Willy Tarreau74ca5042013-06-11 23:12:07 +020014419srv_conn([<backend>/]<server>) : integer
14420 Returns an integer value corresponding to the number of currently established
14421 connections on the designated server, possibly including the connection being
14422 evaluated. If <backend> is omitted, then the server is looked up in the
14423 current backend. It can be used to use a specific farm when one server is
14424 full, or to inform the server about our view of the number of active
Patrick Hemmer155e93e2018-06-14 18:01:35 -040014425 connections with it. See also the "fe_conn", "be_conn", "queue", and
14426 "srv_conn_free" fetch methods.
14427
14428srv_conn_free([<backend>/]<server>) : integer
14429 Returns an integer value corresponding to the number of available connections
14430 on the designated server, possibly including the connection being evaluated.
14431 The value does not include queue slots. If <backend> is omitted, then the
14432 server is looked up in the current backend. It can be used to use a specific
14433 farm when one server is full, or to inform the server about our view of the
14434 number of active connections with it. See also the "be_conn_free" and
14435 "srv_conn" fetch methods.
14436
14437 OTHER CAVEATS AND NOTES: If the server maxconn is 0, then this fetch clearly
14438 does not make sense, in which case the value returned will be -1.
Willy Tarreau74ca5042013-06-11 23:12:07 +020014439
14440srv_is_up([<backend>/]<server>) : boolean
14441 Returns true when the designated server is UP, and false when it is either
14442 DOWN or in maintenance mode. If <backend> is omitted, then the server is
14443 looked up in the current backend. It is mainly used to take action based on
Davor Ocelice9ed2812017-12-25 17:49:28 +010014444 an external status reported via a health check (e.g. a geographical site's
Willy Tarreau74ca5042013-06-11 23:12:07 +020014445 availability). Another possible use which is more of a hack consists in
14446 using dummy servers as boolean variables that can be enabled or disabled from
14447 the CLI, so that rules depending on those ACLs can be tweaked in realtime.
14448
Willy Tarreauff2b7af2017-10-13 11:46:26 +020014449srv_queue([<backend>/]<server>) : integer
14450 Returns an integer value corresponding to the number of connections currently
14451 pending in the designated server's queue. If <backend> is omitted, then the
14452 server is looked up in the current backend. It can sometimes be used together
14453 with the "use-server" directive to force to use a known faster server when it
14454 is not much loaded. See also the "srv_conn", "avg_queue" and "queue" sample
14455 fetch methods.
14456
Willy Tarreau74ca5042013-06-11 23:12:07 +020014457srv_sess_rate([<backend>/]<server>) : integer
14458 Returns an integer corresponding to the sessions creation rate on the
14459 designated server, in number of new sessions per second. If <backend> is
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014460 omitted, then the server is looked up in the current backend. This is mostly
Willy Tarreau74ca5042013-06-11 23:12:07 +020014461 used with ACLs but can make sense with logs too. This is used to switch to an
14462 alternate backend when an expensive or fragile one reaches too high a session
Davor Ocelice9ed2812017-12-25 17:49:28 +010014463 rate, or to limit abuse of service (e.g. prevent latent requests from
Willy Tarreau74ca5042013-06-11 23:12:07 +020014464 overloading servers).
14465
14466 Example :
14467 # Redirect to a separate back
14468 acl srv1_full srv_sess_rate(be1/srv1) gt 50
14469 acl srv2_full srv_sess_rate(be1/srv2) gt 50
14470 use_backend be2 if srv1_full or srv2_full
14471
Willy Tarreau0f30d262014-11-24 16:02:05 +010014472stopping : boolean
14473 Returns TRUE if the process calling the function is currently stopping. This
14474 can be useful for logging, or for relaxing certain checks or helping close
14475 certain connections upon graceful shutdown.
14476
Thierry FOURNIERcc103292015-06-06 19:30:17 +020014477str(<string>) : string
14478 Returns a string.
14479
Willy Tarreau74ca5042013-06-11 23:12:07 +020014480table_avl([<table>]) : integer
14481 Returns the total number of available entries in the current proxy's
14482 stick-table or in the designated stick-table. See also table_cnt.
14483
14484table_cnt([<table>]) : integer
14485 Returns the total number of entries currently in use in the current proxy's
14486 stick-table or in the designated stick-table. See also src_conn_cnt and
14487 table_avl for other entry counting methods.
14488
Christopher Faulet34adb2a2017-11-21 21:45:38 +010014489thread : integer
14490 Returns an integer value corresponding to the position of the thread calling
14491 the function, between 0 and (global.nbthread-1). This is useful for logging
14492 and debugging purposes.
14493
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020014494var(<var-name>) : undefined
14495 Returns a variable with the stored type. If the variable is not set, the
Daniel Schneller0b547052016-03-21 20:46:57 +010014496 sample fetch fails. The name of the variable starts with an indication
14497 about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010014498 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010014499 "sess" : the variable is shared with the whole session
14500 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020014501 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010014502 "req" : the variable is shared only during request processing,
14503 "res" : the variable is shared only during response processing.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020014504 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010014505 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020014506
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200145077.3.3. Fetching samples at Layer 4
Willy Tarreau74ca5042013-06-11 23:12:07 +020014508----------------------------------
14509
14510The layer 4 usually describes just the transport layer which in haproxy is
14511closest to the connection, where no content is yet made available. The fetch
14512methods described here are usable as low as the "tcp-request connection" rule
14513sets unless they require some future information. Those generally include
14514TCP/IP addresses and ports, as well as elements from stick-tables related to
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014515the incoming connection. For retrieving a value from a sticky counters, the
14516counter number can be explicitly set as 0, 1, or 2 using the pre-defined
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +020014517"sc0_", "sc1_", or "sc2_" prefix. These three pre-defined prefixes can only be
14518used if MAX_SESS_STKCTR value does not exceed 3, otherwise the counter number
14519can be specified as the first integer argument when using the "sc_" prefix.
14520Starting from "sc_0" to "sc_N" where N is (MAX_SESS_STKCTR-1). An optional
14521table may be specified with the "sc*" form, in which case the currently
14522tracked key will be looked up into this alternate table instead of the table
14523currently being tracked.
Willy Tarreau74ca5042013-06-11 23:12:07 +020014524
Jérôme Magnin35e53a62019-01-16 14:38:37 +010014525bc_http_major : integer
Jérôme Magnin86577422018-12-07 09:03:11 +010014526 Returns the backend connection's HTTP major version encoding, which may be 1
14527 for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire
14528 encoding and not the version present in the request header.
14529
Willy Tarreau74ca5042013-06-11 23:12:07 +020014530be_id : integer
14531 Returns an integer containing the current backend's id. It can be used in
14532 frontends with responses to check which backend processed the request.
14533
Marcin Deranekd2471c22016-12-12 14:08:05 +010014534be_name : string
14535 Returns a string containing the current backend's name. It can be used in
14536 frontends with responses to check which backend processed the request.
14537
Willy Tarreau74ca5042013-06-11 23:12:07 +020014538dst : ip
14539 This is the destination IPv4 address of the connection on the client side,
14540 which is the address the client connected to. It can be useful when running
14541 in transparent mode. It is of type IP and works on both IPv4 and IPv6 tables.
14542 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent, according to
Willy Tarreau64ded3d2019-01-23 10:02:15 +010014543 RFC 4291. When the incoming connection passed through address translation or
14544 redirection involving connection tracking, the original destination address
14545 before the redirection will be reported. On Linux systems, the source and
14546 destination may seldom appear reversed if the nf_conntrack_tcp_loose sysctl
14547 is set, because a late response may reopen a timed out connection and switch
14548 what is believed to be the source and the destination.
Willy Tarreau74ca5042013-06-11 23:12:07 +020014549
14550dst_conn : integer
14551 Returns an integer value corresponding to the number of currently established
14552 connections on the same socket including the one being evaluated. It is
14553 normally used with ACLs but can as well be used to pass the information to
14554 servers in an HTTP header or in logs. It can be used to either return a sorry
14555 page before hard-blocking, or to use a specific backend to drain new requests
14556 when the socket is considered saturated. This offers the ability to assign
14557 different limits to different listening ports or addresses. See also the
14558 "fe_conn" and "be_conn" fetches.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014559
Willy Tarreau16e01562016-08-09 16:46:18 +020014560dst_is_local : boolean
14561 Returns true if the destination address of the incoming connection is local
14562 to the system, or false if the address doesn't exist on the system, meaning
14563 that it was intercepted in transparent mode. It can be useful to apply
14564 certain rules by default to forwarded traffic and other rules to the traffic
Davor Ocelice9ed2812017-12-25 17:49:28 +010014565 targeting the real address of the machine. For example the stats page could
Willy Tarreau16e01562016-08-09 16:46:18 +020014566 be delivered only on this address, or SSH access could be locally redirected.
14567 Please note that the check involves a few system calls, so it's better to do
14568 it only once per connection.
14569
Willy Tarreau74ca5042013-06-11 23:12:07 +020014570dst_port : integer
14571 Returns an integer value corresponding to the destination TCP port of the
14572 connection on the client side, which is the port the client connected to.
14573 This might be used when running in transparent mode, when assigning dynamic
14574 ports to some clients for a whole application session, to stick all users to
14575 a same server, or to pass the destination port information to a server using
14576 an HTTP header.
14577
Willy Tarreau60ca10a2017-08-18 15:26:54 +020014578fc_http_major : integer
14579 Reports the front connection's HTTP major version encoding, which may be 1
14580 for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire
14581 encoding and not on the version present in the request header.
14582
Geoff Simmons7185b782019-08-27 18:31:16 +020014583fc_pp_authority : string
14584 Returns the authority TLV sent by the client in the PROXY protocol header,
14585 if any.
14586
Emeric Brun4f603012017-01-05 15:11:44 +010014587fc_rcvd_proxy : boolean
14588 Returns true if the client initiated the connection with a PROXY protocol
14589 header.
14590
Thierry Fournier / OZON.IO6310bef2016-07-24 20:16:50 +020014591fc_rtt(<unit>) : integer
14592 Returns the Round Trip Time (RTT) measured by the kernel for the client
14593 connection. <unit> is facultative, by default the unit is milliseconds. <unit>
14594 can be set to "ms" for milliseconds or "us" for microseconds. If the server
14595 connection is not established, if the connection is not TCP or if the
14596 operating system does not support TCP_INFO, for example Linux kernels before
14597 2.4, the sample fetch fails.
14598
14599fc_rttvar(<unit>) : integer
14600 Returns the Round Trip Time (RTT) variance measured by the kernel for the
14601 client connection. <unit> is facultative, by default the unit is milliseconds.
14602 <unit> can be set to "ms" for milliseconds or "us" for microseconds. If the
14603 server connection is not established, if the connection is not TCP or if the
14604 operating system does not support TCP_INFO, for example Linux kernels before
14605 2.4, the sample fetch fails.
14606
Christopher Fauletba0c53e2019-10-17 14:40:48 +020014607fc_unacked : integer
Joe Williams30fcd392016-08-10 07:06:44 -070014608 Returns the unacked counter measured by the kernel for the client connection.
14609 If the server connection is not established, if the connection is not TCP or
14610 if the operating system does not support TCP_INFO, for example Linux kernels
14611 before 2.4, the sample fetch fails.
14612
Christopher Fauletba0c53e2019-10-17 14:40:48 +020014613fc_sacked : integer
Joe Williams30fcd392016-08-10 07:06:44 -070014614 Returns the sacked counter measured by the kernel for the client connection.
14615 If the server connection is not established, if the connection is not TCP or
14616 if the operating system does not support TCP_INFO, for example Linux kernels
14617 before 2.4, the sample fetch fails.
14618
Christopher Fauletba0c53e2019-10-17 14:40:48 +020014619fc_retrans : integer
Joe Williams30fcd392016-08-10 07:06:44 -070014620 Returns the retransmits counter measured by the kernel for the client
14621 connection. If the server connection is not established, if the connection is
14622 not TCP or if the operating system does not support TCP_INFO, for example
14623 Linux kernels before 2.4, the sample fetch fails.
14624
Christopher Fauletba0c53e2019-10-17 14:40:48 +020014625fc_fackets : integer
Joe Williams30fcd392016-08-10 07:06:44 -070014626 Returns the fack counter measured by the kernel for the client
14627 connection. If the server connection is not established, if the connection is
14628 not TCP or if the operating system does not support TCP_INFO, for example
14629 Linux kernels before 2.4, the sample fetch fails.
14630
Christopher Fauletba0c53e2019-10-17 14:40:48 +020014631fc_lost : integer
Joe Williams30fcd392016-08-10 07:06:44 -070014632 Returns the lost counter measured by the kernel for the client
14633 connection. If the server connection is not established, if the connection is
14634 not TCP or if the operating system does not support TCP_INFO, for example
14635 Linux kernels before 2.4, the sample fetch fails.
14636
Christopher Fauletba0c53e2019-10-17 14:40:48 +020014637fc_reordering : integer
Joe Williams30fcd392016-08-10 07:06:44 -070014638 Returns the reordering counter measured by the kernel for the client
14639 connection. If the server connection is not established, if the connection is
14640 not TCP or if the operating system does not support TCP_INFO, for example
14641 Linux kernels before 2.4, the sample fetch fails.
14642
Marcin Deranek9a66dfb2018-04-13 14:37:50 +020014643fe_defbe : string
14644 Returns a string containing the frontend's default backend name. It can be
14645 used in frontends to check which backend will handle requests by default.
14646
Willy Tarreau74ca5042013-06-11 23:12:07 +020014647fe_id : integer
14648 Returns an integer containing the current frontend's id. It can be used in
Marcin Deranek6e413ed2016-12-13 12:40:01 +010014649 backends to check from which frontend it was called, or to stick all users
Willy Tarreau74ca5042013-06-11 23:12:07 +020014650 coming via a same frontend to the same server.
14651
Marcin Deranekd2471c22016-12-12 14:08:05 +010014652fe_name : string
14653 Returns a string containing the current frontend's name. It can be used in
14654 backends to check from which frontend it was called, or to stick all users
14655 coming via a same frontend to the same server.
14656
Cyril Bonté62ba8702014-04-22 23:52:25 +020014657sc_bytes_in_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014658sc0_bytes_in_rate([<table>]) : integer
14659sc1_bytes_in_rate([<table>]) : integer
14660sc2_bytes_in_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014661 Returns the average client-to-server bytes rate from the currently tracked
14662 counters, measured in amount of bytes over the period configured in the
14663 table. See also src_bytes_in_rate.
14664
Cyril Bonté62ba8702014-04-22 23:52:25 +020014665sc_bytes_out_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014666sc0_bytes_out_rate([<table>]) : integer
14667sc1_bytes_out_rate([<table>]) : integer
14668sc2_bytes_out_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014669 Returns the average server-to-client bytes rate from the currently tracked
14670 counters, measured in amount of bytes over the period configured in the
14671 table. See also src_bytes_out_rate.
14672
Cyril Bonté62ba8702014-04-22 23:52:25 +020014673sc_clr_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014674sc0_clr_gpc0([<table>]) : integer
14675sc1_clr_gpc0([<table>]) : integer
14676sc2_clr_gpc0([<table>]) : integer
Willy Tarreauf73cd112011-08-13 01:45:16 +020014677 Clears the first General Purpose Counter associated to the currently tracked
14678 counters, and returns its previous value. Before the first invocation, the
Willy Tarreau869948b2013-01-04 14:14:57 +010014679 stored value is zero, so first invocation will always return zero. This is
14680 typically used as a second ACL in an expression in order to mark a connection
14681 when a first ACL was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020014682
Jarno Huuskonen676f6222017-03-30 09:19:45 +030014683 Example:
Willy Tarreauf73cd112011-08-13 01:45:16 +020014684 # block if 5 consecutive requests continue to come faster than 10 sess
14685 # per second, and reset the counter as soon as the traffic slows down.
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020014686 acl abuse sc0_http_req_rate gt 10
14687 acl kill sc0_inc_gpc0 gt 5
14688 acl save sc0_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020014689 tcp-request connection accept if !abuse save
14690 tcp-request connection reject if abuse kill
14691
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014692sc_clr_gpc1(<ctr>[,<table>]) : integer
14693sc0_clr_gpc1([<table>]) : integer
14694sc1_clr_gpc1([<table>]) : integer
14695sc2_clr_gpc1([<table>]) : integer
14696 Clears the second General Purpose Counter associated to the currently tracked
14697 counters, and returns its previous value. Before the first invocation, the
14698 stored value is zero, so first invocation will always return zero. This is
14699 typically used as a second ACL in an expression in order to mark a connection
14700 when a first ACL was verified.
14701
Cyril Bonté62ba8702014-04-22 23:52:25 +020014702sc_conn_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014703sc0_conn_cnt([<table>]) : integer
14704sc1_conn_cnt([<table>]) : integer
14705sc2_conn_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014706 Returns the cumulative number of incoming connections from currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020014707 counters. See also src_conn_cnt.
14708
Cyril Bonté62ba8702014-04-22 23:52:25 +020014709sc_conn_cur(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014710sc0_conn_cur([<table>]) : integer
14711sc1_conn_cur([<table>]) : integer
14712sc2_conn_cur([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014713 Returns the current amount of concurrent connections tracking the same
14714 tracked counters. This number is automatically incremented when tracking
14715 begins and decremented when tracking stops. See also src_conn_cur.
14716
Cyril Bonté62ba8702014-04-22 23:52:25 +020014717sc_conn_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014718sc0_conn_rate([<table>]) : integer
14719sc1_conn_rate([<table>]) : integer
14720sc2_conn_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014721 Returns the average connection rate from the currently tracked counters,
14722 measured in amount of connections over the period configured in the table.
14723 See also src_conn_rate.
14724
Cyril Bonté62ba8702014-04-22 23:52:25 +020014725sc_get_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014726sc0_get_gpc0([<table>]) : integer
14727sc1_get_gpc0([<table>]) : integer
14728sc2_get_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014729 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014730 currently tracked counters. See also src_get_gpc0 and sc/sc0/sc1/sc2_inc_gpc0.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014731
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014732sc_get_gpc1(<ctr>[,<table>]) : integer
14733sc0_get_gpc1([<table>]) : integer
14734sc1_get_gpc1([<table>]) : integer
14735sc2_get_gpc1([<table>]) : integer
14736 Returns the value of the second General Purpose Counter associated to the
14737 currently tracked counters. See also src_get_gpc1 and sc/sc0/sc1/sc2_inc_gpc1.
14738
Thierry FOURNIER236657b2015-08-19 08:25:14 +020014739sc_get_gpt0(<ctr>[,<table>]) : integer
14740sc0_get_gpt0([<table>]) : integer
14741sc1_get_gpt0([<table>]) : integer
14742sc2_get_gpt0([<table>]) : integer
14743 Returns the value of the first General Purpose Tag associated to the
14744 currently tracked counters. See also src_get_gpt0.
14745
Cyril Bonté62ba8702014-04-22 23:52:25 +020014746sc_gpc0_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014747sc0_gpc0_rate([<table>]) : integer
14748sc1_gpc0_rate([<table>]) : integer
14749sc2_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014750 Returns the average increment rate of the first General Purpose Counter
14751 associated to the currently tracked counters. It reports the frequency
14752 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014753 src_gpc0_rate, sc/sc0/sc1/sc2_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
14754 that the "gpc0_rate" counter must be stored in the stick-table for a value to
14755 be returned, as "gpc0" only holds the event count.
Willy Tarreaue9656522010-08-17 15:40:09 +020014756
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014757sc_gpc1_rate(<ctr>[,<table>]) : integer
14758sc0_gpc1_rate([<table>]) : integer
14759sc1_gpc1_rate([<table>]) : integer
14760sc2_gpc1_rate([<table>]) : integer
14761 Returns the average increment rate of the second General Purpose Counter
14762 associated to the currently tracked counters. It reports the frequency
14763 which the gpc1 counter was incremented over the configured period. See also
14764 src_gpcA_rate, sc/sc0/sc1/sc2_get_gpc1, and sc/sc0/sc1/sc2_inc_gpc1. Note
14765 that the "gpc1_rate" counter must be stored in the stick-table for a value to
14766 be returned, as "gpc1" only holds the event count.
14767
Cyril Bonté62ba8702014-04-22 23:52:25 +020014768sc_http_err_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014769sc0_http_err_cnt([<table>]) : integer
14770sc1_http_err_cnt([<table>]) : integer
14771sc2_http_err_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014772 Returns the cumulative number of HTTP errors from the currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020014773 counters. This includes the both request errors and 4xx error responses.
14774 See also src_http_err_cnt.
14775
Cyril Bonté62ba8702014-04-22 23:52:25 +020014776sc_http_err_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014777sc0_http_err_rate([<table>]) : integer
14778sc1_http_err_rate([<table>]) : integer
14779sc2_http_err_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014780 Returns the average rate of HTTP errors from the currently tracked counters,
14781 measured in amount of errors over the period configured in the table. This
14782 includes the both request errors and 4xx error responses. See also
14783 src_http_err_rate.
14784
Cyril Bonté62ba8702014-04-22 23:52:25 +020014785sc_http_req_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014786sc0_http_req_cnt([<table>]) : integer
14787sc1_http_req_cnt([<table>]) : integer
14788sc2_http_req_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014789 Returns the cumulative number of HTTP requests from the currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020014790 counters. This includes every started request, valid or not. See also
14791 src_http_req_cnt.
14792
Cyril Bonté62ba8702014-04-22 23:52:25 +020014793sc_http_req_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014794sc0_http_req_rate([<table>]) : integer
14795sc1_http_req_rate([<table>]) : integer
14796sc2_http_req_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014797 Returns the average rate of HTTP requests from the currently tracked
14798 counters, measured in amount of requests over the period configured in
14799 the table. This includes every started request, valid or not. See also
14800 src_http_req_rate.
14801
Cyril Bonté62ba8702014-04-22 23:52:25 +020014802sc_inc_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014803sc0_inc_gpc0([<table>]) : integer
14804sc1_inc_gpc0([<table>]) : integer
14805sc2_inc_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014806 Increments the first General Purpose Counter associated to the currently
Willy Tarreau869948b2013-01-04 14:14:57 +010014807 tracked counters, and returns its new value. Before the first invocation,
14808 the stored value is zero, so first invocation will increase it to 1 and will
14809 return 1. This is typically used as a second ACL in an expression in order
14810 to mark a connection when a first ACL was verified :
Willy Tarreaue9656522010-08-17 15:40:09 +020014811
Jarno Huuskonen676f6222017-03-30 09:19:45 +030014812 Example:
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020014813 acl abuse sc0_http_req_rate gt 10
14814 acl kill sc0_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020014815 tcp-request connection reject if abuse kill
14816
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014817sc_inc_gpc1(<ctr>[,<table>]) : integer
14818sc0_inc_gpc1([<table>]) : integer
14819sc1_inc_gpc1([<table>]) : integer
14820sc2_inc_gpc1([<table>]) : integer
14821 Increments the second General Purpose Counter associated to the currently
14822 tracked counters, and returns its new value. Before the first invocation,
14823 the stored value is zero, so first invocation will increase it to 1 and will
14824 return 1. This is typically used as a second ACL in an expression in order
14825 to mark a connection when a first ACL was verified.
14826
Cyril Bonté62ba8702014-04-22 23:52:25 +020014827sc_kbytes_in(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014828sc0_kbytes_in([<table>]) : integer
14829sc1_kbytes_in([<table>]) : integer
14830sc2_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020014831 Returns the total amount of client-to-server data from the currently tracked
14832 counters, measured in kilobytes. The test is currently performed on 32-bit
14833 integers, which limits values to 4 terabytes. See also src_kbytes_in.
Willy Tarreaue9656522010-08-17 15:40:09 +020014834
Cyril Bonté62ba8702014-04-22 23:52:25 +020014835sc_kbytes_out(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014836sc0_kbytes_out([<table>]) : integer
14837sc1_kbytes_out([<table>]) : integer
14838sc2_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020014839 Returns the total amount of server-to-client data from the currently tracked
14840 counters, measured in kilobytes. The test is currently performed on 32-bit
14841 integers, which limits values to 4 terabytes. See also src_kbytes_out.
Willy Tarreaue9656522010-08-17 15:40:09 +020014842
Cyril Bonté62ba8702014-04-22 23:52:25 +020014843sc_sess_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014844sc0_sess_cnt([<table>]) : integer
14845sc1_sess_cnt([<table>]) : integer
14846sc2_sess_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014847 Returns the cumulative number of incoming connections that were transformed
Willy Tarreaue9656522010-08-17 15:40:09 +020014848 into sessions, which means that they were accepted by a "tcp-request
14849 connection" rule, from the currently tracked counters. A backend may count
14850 more sessions than connections because each connection could result in many
Jamie Gloudonaaa21002012-08-25 00:18:33 -040014851 backend sessions if some HTTP keep-alive is performed over the connection
Willy Tarreaue9656522010-08-17 15:40:09 +020014852 with the client. See also src_sess_cnt.
14853
Cyril Bonté62ba8702014-04-22 23:52:25 +020014854sc_sess_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014855sc0_sess_rate([<table>]) : integer
14856sc1_sess_rate([<table>]) : integer
14857sc2_sess_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020014858 Returns the average session rate from the currently tracked counters,
14859 measured in amount of sessions over the period configured in the table. A
14860 session is a connection that got past the early "tcp-request connection"
14861 rules. A backend may count more sessions than connections because each
14862 connection could result in many backend sessions if some HTTP keep-alive is
Jamie Gloudonaaa21002012-08-25 00:18:33 -040014863 performed over the connection with the client. See also src_sess_rate.
Willy Tarreaue9656522010-08-17 15:40:09 +020014864
Cyril Bonté62ba8702014-04-22 23:52:25 +020014865sc_tracked(<ctr>[,<table>]) : boolean
Willy Tarreau0f791d42013-07-23 19:56:43 +020014866sc0_tracked([<table>]) : boolean
14867sc1_tracked([<table>]) : boolean
14868sc2_tracked([<table>]) : boolean
Willy Tarreau6f1615f2013-06-03 15:15:22 +020014869 Returns true if the designated session counter is currently being tracked by
14870 the current session. This can be useful when deciding whether or not we want
14871 to set some values in a header passed to the server.
14872
Cyril Bonté62ba8702014-04-22 23:52:25 +020014873sc_trackers(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014874sc0_trackers([<table>]) : integer
14875sc1_trackers([<table>]) : integer
14876sc2_trackers([<table>]) : integer
Willy Tarreau2406db42012-12-09 12:16:43 +010014877 Returns the current amount of concurrent connections tracking the same
14878 tracked counters. This number is automatically incremented when tracking
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020014879 begins and decremented when tracking stops. It differs from sc0_conn_cur in
Willy Tarreau2406db42012-12-09 12:16:43 +010014880 that it does not rely on any stored information but on the table's reference
14881 count (the "use" value which is returned by "show table" on the CLI). This
Willy Tarreau74ca5042013-06-11 23:12:07 +020014882 may sometimes be more suited for layer7 tracking. It can be used to tell a
14883 server how many concurrent connections there are from a given address for
14884 example.
Willy Tarreau2406db42012-12-09 12:16:43 +010014885
Willy Tarreau74ca5042013-06-11 23:12:07 +020014886so_id : integer
14887 Returns an integer containing the current listening socket's id. It is useful
14888 in frontends involving many "bind" lines, or to stick all users coming via a
14889 same socket to the same server.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014890
Willy Tarreau74ca5042013-06-11 23:12:07 +020014891src : ip
Davor Ocelice9ed2812017-12-25 17:49:28 +010014892 This is the source IPv4 address of the client of the session. It is of type
Willy Tarreau74ca5042013-06-11 23:12:07 +020014893 IP and works on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are
14894 mapped to their IPv6 equivalent, according to RFC 4291. Note that it is the
14895 TCP-level source address which is used, and not the address of a client
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010014896 behind a proxy. However if the "accept-proxy" or "accept-netscaler-cip" bind
14897 directive is used, it can be the address of a client behind another
14898 PROXY-protocol compatible component for all rule sets except
Willy Tarreau64ded3d2019-01-23 10:02:15 +010014899 "tcp-request connection" which sees the real address. When the incoming
14900 connection passed through address translation or redirection involving
14901 connection tracking, the original destination address before the redirection
14902 will be reported. On Linux systems, the source and destination may seldom
14903 appear reversed if the nf_conntrack_tcp_loose sysctl is set, because a late
14904 response may reopen a timed out connection and switch what is believed to be
14905 the source and the destination.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014906
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010014907 Example:
14908 # add an HTTP header in requests with the originating address' country
14909 http-request set-header X-Country %[src,map_ip(geoip.lst)]
14910
Willy Tarreau74ca5042013-06-11 23:12:07 +020014911src_bytes_in_rate([<table>]) : integer
14912 Returns the average bytes rate from the incoming connection's source address
14913 in the current proxy's stick-table or in the designated stick-table, measured
14914 in amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014915 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014916
Willy Tarreau74ca5042013-06-11 23:12:07 +020014917src_bytes_out_rate([<table>]) : integer
14918 Returns the average bytes rate to the incoming connection's source address in
14919 the current proxy's stick-table or in the designated stick-table, measured in
Willy Tarreauc9705a12010-07-27 20:05:50 +020014920 amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014921 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014922
Willy Tarreau74ca5042013-06-11 23:12:07 +020014923src_clr_gpc0([<table>]) : integer
14924 Clears the first General Purpose Counter associated to the incoming
14925 connection's source address in the current proxy's stick-table or in the
14926 designated stick-table, and returns its previous value. If the address is not
14927 found, an entry is created and 0 is returned. This is typically used as a
14928 second ACL in an expression in order to mark a connection when a first ACL
14929 was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020014930
Jarno Huuskonen676f6222017-03-30 09:19:45 +030014931 Example:
Willy Tarreauf73cd112011-08-13 01:45:16 +020014932 # block if 5 consecutive requests continue to come faster than 10 sess
14933 # per second, and reset the counter as soon as the traffic slows down.
14934 acl abuse src_http_req_rate gt 10
14935 acl kill src_inc_gpc0 gt 5
Willy Tarreau869948b2013-01-04 14:14:57 +010014936 acl save src_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020014937 tcp-request connection accept if !abuse save
14938 tcp-request connection reject if abuse kill
14939
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014940src_clr_gpc1([<table>]) : integer
14941 Clears the second General Purpose Counter associated to the incoming
14942 connection's source address in the current proxy's stick-table or in the
14943 designated stick-table, and returns its previous value. If the address is not
14944 found, an entry is created and 0 is returned. This is typically used as a
14945 second ACL in an expression in order to mark a connection when a first ACL
14946 was verified.
14947
Willy Tarreau74ca5042013-06-11 23:12:07 +020014948src_conn_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010014949 Returns the cumulative number of connections initiated from the current
Willy Tarreau74ca5042013-06-11 23:12:07 +020014950 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020014951 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014952 See also sc/sc0/sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014953
Willy Tarreau74ca5042013-06-11 23:12:07 +020014954src_conn_cur([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020014955 Returns the current amount of concurrent connections initiated from the
Willy Tarreau74ca5042013-06-11 23:12:07 +020014956 current incoming connection's source address in the current proxy's
14957 stick-table or in the designated stick-table. If the address is not found,
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014958 zero is returned. See also sc/sc0/sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014959
Willy Tarreau74ca5042013-06-11 23:12:07 +020014960src_conn_rate([<table>]) : integer
14961 Returns the average connection rate from the incoming connection's source
14962 address in the current proxy's stick-table or in the designated stick-table,
14963 measured in amount of connections over the period configured in the table. If
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014964 the address is not found, zero is returned. See also sc/sc0/sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014965
Willy Tarreau74ca5042013-06-11 23:12:07 +020014966src_get_gpc0([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020014967 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau74ca5042013-06-11 23:12:07 +020014968 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020014969 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014970 See also sc/sc0/sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014971
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014972src_get_gpc1([<table>]) : integer
14973 Returns the value of the second General Purpose Counter associated to the
14974 incoming connection's source address in the current proxy's stick-table or in
14975 the designated stick-table. If the address is not found, zero is returned.
14976 See also sc/sc0/sc1/sc2_get_gpc1 and src_inc_gpc1.
14977
Thierry FOURNIER236657b2015-08-19 08:25:14 +020014978src_get_gpt0([<table>]) : integer
14979 Returns the value of the first General Purpose Tag associated to the
14980 incoming connection's source address in the current proxy's stick-table or in
14981 the designated stick-table. If the address is not found, zero is returned.
14982 See also sc/sc0/sc1/sc2_get_gpt0.
14983
Willy Tarreau74ca5042013-06-11 23:12:07 +020014984src_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014985 Returns the average increment rate of the first General Purpose Counter
Willy Tarreau74ca5042013-06-11 23:12:07 +020014986 associated to the incoming connection's source address in the current proxy's
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014987 stick-table or in the designated stick-table. It reports the frequency
14988 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014989 sc/sc0/sc1/sc2_gpc0_rate, src_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
14990 that the "gpc0_rate" counter must be stored in the stick-table for a value to
14991 be returned, as "gpc0" only holds the event count.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014992
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014993src_gpc1_rate([<table>]) : integer
14994 Returns the average increment rate of the second General Purpose Counter
14995 associated to the incoming connection's source address in the current proxy's
14996 stick-table or in the designated stick-table. It reports the frequency
14997 which the gpc1 counter was incremented over the configured period. See also
14998 sc/sc0/sc1/sc2_gpc1_rate, src_get_gpc1, and sc/sc0/sc1/sc2_inc_gpc1. Note
14999 that the "gpc1_rate" counter must be stored in the stick-table for a value to
15000 be returned, as "gpc1" only holds the event count.
15001
Willy Tarreau74ca5042013-06-11 23:12:07 +020015002src_http_err_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010015003 Returns the cumulative number of HTTP errors from the incoming connection's
Willy Tarreau74ca5042013-06-11 23:12:07 +020015004 source address in the current proxy's stick-table or in the designated
Willy Tarreauc9705a12010-07-27 20:05:50 +020015005 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015006 See also sc/sc0/sc1/sc2_http_err_cnt. If the address is not found, zero is
Willy Tarreau74ca5042013-06-11 23:12:07 +020015007 returned.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015008
Willy Tarreau74ca5042013-06-11 23:12:07 +020015009src_http_err_rate([<table>]) : integer
15010 Returns the average rate of HTTP errors from the incoming connection's source
15011 address in the current proxy's stick-table or in the designated stick-table,
15012 measured in amount of errors over the period configured in the table. This
15013 includes the both request errors and 4xx error responses. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015014 not found, zero is returned. See also sc/sc0/sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015015
Willy Tarreau74ca5042013-06-11 23:12:07 +020015016src_http_req_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010015017 Returns the cumulative number of HTTP requests from the incoming connection's
Willy Tarreau74ca5042013-06-11 23:12:07 +020015018 source address in the current proxy's stick-table or in the designated stick-
15019 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015020 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015021
Willy Tarreau74ca5042013-06-11 23:12:07 +020015022src_http_req_rate([<table>]) : integer
15023 Returns the average rate of HTTP requests from the incoming connection's
15024 source address in the current proxy's stick-table or in the designated stick-
15025 table, measured in amount of requests over the period configured in the
Willy Tarreauc9705a12010-07-27 20:05:50 +020015026 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015027 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015028
Willy Tarreau74ca5042013-06-11 23:12:07 +020015029src_inc_gpc0([<table>]) : integer
15030 Increments the first General Purpose Counter associated to the incoming
15031 connection's source address in the current proxy's stick-table or in the
15032 designated stick-table, and returns its new value. If the address is not
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020015033 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc0.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015034 This is typically used as a second ACL in an expression in order to mark a
15035 connection when a first ACL was verified :
Willy Tarreauc9705a12010-07-27 20:05:50 +020015036
Jarno Huuskonen676f6222017-03-30 09:19:45 +030015037 Example:
Willy Tarreauc9705a12010-07-27 20:05:50 +020015038 acl abuse src_http_req_rate gt 10
Willy Tarreau869948b2013-01-04 14:14:57 +010015039 acl kill src_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020015040 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +020015041
Frédéric Lécaille6778b272018-01-29 15:22:53 +010015042src_inc_gpc1([<table>]) : integer
15043 Increments the second General Purpose Counter associated to the incoming
15044 connection's source address in the current proxy's stick-table or in the
15045 designated stick-table, and returns its new value. If the address is not
15046 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc1.
15047 This is typically used as a second ACL in an expression in order to mark a
15048 connection when a first ACL was verified.
15049
Willy Tarreau16e01562016-08-09 16:46:18 +020015050src_is_local : boolean
15051 Returns true if the source address of the incoming connection is local to the
15052 system, or false if the address doesn't exist on the system, meaning that it
15053 comes from a remote machine. Note that UNIX addresses are considered local.
15054 It can be useful to apply certain access restrictions based on where the
Davor Ocelice9ed2812017-12-25 17:49:28 +010015055 client comes from (e.g. require auth or https for remote machines). Please
Willy Tarreau16e01562016-08-09 16:46:18 +020015056 note that the check involves a few system calls, so it's better to do it only
15057 once per connection.
15058
Willy Tarreau74ca5042013-06-11 23:12:07 +020015059src_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020015060 Returns the total amount of data received from the incoming connection's
15061 source address in the current proxy's stick-table or in the designated
15062 stick-table, measured in kilobytes. If the address is not found, zero is
15063 returned. The test is currently performed on 32-bit integers, which limits
15064 values to 4 terabytes. See also sc/sc0/sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015065
Willy Tarreau74ca5042013-06-11 23:12:07 +020015066src_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020015067 Returns the total amount of data sent to the incoming connection's source
15068 address in the current proxy's stick-table or in the designated stick-table,
15069 measured in kilobytes. If the address is not found, zero is returned. The
15070 test is currently performed on 32-bit integers, which limits values to 4
15071 terabytes. See also sc/sc0/sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020015072
Willy Tarreau74ca5042013-06-11 23:12:07 +020015073src_port : integer
15074 Returns an integer value corresponding to the TCP source port of the
15075 connection on the client side, which is the port the client connected from.
15076 Usage of this function is very limited as modern protocols do not care much
15077 about source ports nowadays.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010015078
Willy Tarreau74ca5042013-06-11 23:12:07 +020015079src_sess_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010015080 Returns the cumulative number of connections initiated from the incoming
Willy Tarreauc9705a12010-07-27 20:05:50 +020015081 connection's source IPv4 address in the current proxy's stick-table or in the
15082 designated stick-table, that were transformed into sessions, which means that
15083 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015084 is returned. See also sc/sc0/sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015085
Willy Tarreau74ca5042013-06-11 23:12:07 +020015086src_sess_rate([<table>]) : integer
15087 Returns the average session rate from the incoming connection's source
15088 address in the current proxy's stick-table or in the designated stick-table,
15089 measured in amount of sessions over the period configured in the table. A
15090 session is a connection that went past the early "tcp-request" rules. If the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015091 address is not found, zero is returned. See also sc/sc0/sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015092
Willy Tarreau74ca5042013-06-11 23:12:07 +020015093src_updt_conn_cnt([<table>]) : integer
15094 Creates or updates the entry associated to the incoming connection's source
15095 address in the current proxy's stick-table or in the designated stick-table.
15096 This table must be configured to store the "conn_cnt" data type, otherwise
15097 the match will be ignored. The current count is incremented by one, and the
15098 expiration timer refreshed. The updated count is returned, so this match
15099 can't return zero. This was used to reject service abusers based on their
15100 source address. Note: it is recommended to use the more complete "track-sc*"
15101 actions in "tcp-request" rules instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020015102
15103 Example :
15104 # This frontend limits incoming SSH connections to 3 per 10 second for
15105 # each source address, and rejects excess connections until a 10 second
15106 # silence is observed. At most 20 addresses are tracked.
15107 listen ssh
15108 bind :22
15109 mode tcp
15110 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +020015111 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreau74ca5042013-06-11 23:12:07 +020015112 tcp-request content reject if { src_updt_conn_cnt gt 3 }
Willy Tarreaua975b8f2010-06-05 19:13:27 +020015113 server local 127.0.0.1:22
15114
Willy Tarreau74ca5042013-06-11 23:12:07 +020015115srv_id : integer
15116 Returns an integer containing the server's id when processing the response.
15117 While it's almost only used with ACLs, it may be used for logging or
15118 debugging.
Hervé COMMOWICKdaa824e2011-08-05 12:09:44 +020015119
vkill1dfd1652019-10-30 16:58:14 +080015120srv_name : string
15121 Returns a string containing the server's name when processing the response.
15122 While it's almost only used with ACLs, it may be used for logging or
15123 debugging.
15124
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200151257.3.4. Fetching samples at Layer 5
Willy Tarreau74ca5042013-06-11 23:12:07 +020015126----------------------------------
Willy Tarreau0b1cd942010-05-16 22:18:27 +020015127
Willy Tarreau74ca5042013-06-11 23:12:07 +020015128The layer 5 usually describes just the session layer which in haproxy is
15129closest to the session once all the connection handshakes are finished, but
15130when no content is yet made available. The fetch methods described here are
15131usable as low as the "tcp-request content" rule sets unless they require some
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030015132future information. Those generally include the results of SSL negotiations.
Willy Tarreauc735a072011-03-29 00:57:02 +020015133
Ben Shillitof25e8e52016-12-02 14:25:37 +00001513451d.all(<prop>[,<prop>*]) : string
15135 Returns values for the properties requested as a string, where values are
15136 separated by the delimiter specified with "51degrees-property-separator".
15137 The device is identified using all the important HTTP headers from the
15138 request. The function can be passed up to five property names, and if a
15139 property name can't be found, the value "NoData" is returned.
15140
15141 Example :
15142 # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request
15143 # containing the three properties requested using all relevant headers from
15144 # the request.
15145 frontend http-in
15146 bind *:8081
15147 default_backend servers
15148 http-request set-header X-51D-DeviceTypeMobileTablet \
15149 %[51d.all(DeviceType,IsMobile,IsTablet)]
15150
Emeric Brun645ae792014-04-30 14:21:06 +020015151ssl_bc : boolean
15152 Returns true when the back connection was made via an SSL/TLS transport
15153 layer and is locally deciphered. This means the outgoing connection was made
15154 other a server with the "ssl" option.
15155
15156ssl_bc_alg_keysize : integer
15157 Returns the symmetric cipher key size supported in bits when the outgoing
15158 connection was made over an SSL/TLS transport layer.
15159
Olivier Houchard6b77f492018-11-22 18:18:29 +010015160ssl_bc_alpn : string
15161 This extracts the Application Layer Protocol Negotiation field from an
15162 outgoing connection made via a TLS transport layer.
Michael Prokop4438c602019-05-24 10:25:45 +020015163 The result is a string containing the protocol name negotiated with the
Olivier Houchard6b77f492018-11-22 18:18:29 +010015164 server. The SSL library must have been built with support for TLS
15165 extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
15166 not advertised unless the "alpn" keyword on the "server" line specifies a
15167 protocol list. Also, nothing forces the server to pick a protocol from this
15168 list, any other one may be requested. The TLS ALPN extension is meant to
15169 replace the TLS NPN extension. See also "ssl_bc_npn".
15170
Emeric Brun645ae792014-04-30 14:21:06 +020015171ssl_bc_cipher : string
15172 Returns the name of the used cipher when the outgoing connection was made
15173 over an SSL/TLS transport layer.
15174
Patrick Hemmer65674662019-06-04 08:13:03 -040015175ssl_bc_client_random : binary
15176 Returns the client random of the back connection when the incoming connection
15177 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
15178 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
15179
Emeric Brun74f7ffa2018-02-19 16:14:12 +010015180ssl_bc_is_resumed : boolean
15181 Returns true when the back connection was made over an SSL/TLS transport
15182 layer and the newly created SSL session was resumed using a cached
15183 session or a TLS ticket.
15184
Olivier Houchard6b77f492018-11-22 18:18:29 +010015185ssl_bc_npn : string
15186 This extracts the Next Protocol Negotiation field from an outgoing connection
15187 made via a TLS transport layer. The result is a string containing the
Michael Prokop4438c602019-05-24 10:25:45 +020015188 protocol name negotiated with the server . The SSL library must have been
Olivier Houchard6b77f492018-11-22 18:18:29 +010015189 built with support for TLS extensions enabled (check haproxy -vv). Note that
15190 the TLS NPN extension is not advertised unless the "npn" keyword on the
15191 "server" line specifies a protocol list. Also, nothing forces the server to
15192 pick a protocol from this list, any other one may be used. Please note that
15193 the TLS NPN extension was replaced with ALPN.
15194
Emeric Brun645ae792014-04-30 14:21:06 +020015195ssl_bc_protocol : string
15196 Returns the name of the used protocol when the outgoing connection was made
15197 over an SSL/TLS transport layer.
15198
Emeric Brunb73a9b02014-04-30 18:49:19 +020015199ssl_bc_unique_id : binary
Emeric Brun645ae792014-04-30 14:21:06 +020015200 When the outgoing connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020015201 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
15202 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".
Emeric Brun645ae792014-04-30 14:21:06 +020015203
Patrick Hemmer65674662019-06-04 08:13:03 -040015204ssl_bc_server_random : binary
15205 Returns the server random of the back connection when the incoming connection
15206 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
15207 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
15208
Emeric Brun645ae792014-04-30 14:21:06 +020015209ssl_bc_session_id : binary
15210 Returns the SSL ID of the back connection when the outgoing connection was
15211 made over an SSL/TLS transport layer. It is useful to log if we want to know
15212 if session was reused or not.
15213
Patrick Hemmere0275472018-04-28 19:15:51 -040015214ssl_bc_session_key : binary
15215 Returns the SSL session master key of the back connection when the outgoing
15216 connection was made over an SSL/TLS transport layer. It is useful to decrypt
15217 traffic sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or
15218 BoringSSL.
15219
Emeric Brun645ae792014-04-30 14:21:06 +020015220ssl_bc_use_keysize : integer
15221 Returns the symmetric cipher key size used in bits when the outgoing
15222 connection was made over an SSL/TLS transport layer.
15223
Willy Tarreau74ca5042013-06-11 23:12:07 +020015224ssl_c_ca_err : integer
15225 When the incoming connection was made over an SSL/TLS transport layer,
15226 returns the ID of the first error detected during verification of the client
15227 certificate at depth > 0, or 0 if no error was encountered during this
15228 verification process. Please refer to your SSL library's documentation to
15229 find the exhaustive list of error codes.
Willy Tarreauc735a072011-03-29 00:57:02 +020015230
Willy Tarreau74ca5042013-06-11 23:12:07 +020015231ssl_c_ca_err_depth : integer
15232 When the incoming connection was made over an SSL/TLS transport layer,
15233 returns the depth in the CA chain of the first error detected during the
15234 verification of the client certificate. If no error is encountered, 0 is
15235 returned.
Willy Tarreau0ba27502007-12-24 16:55:16 +010015236
Emeric Brun43e79582014-10-29 19:03:26 +010015237ssl_c_der : binary
15238 Returns the DER formatted certificate presented by the client when the
15239 incoming connection was made over an SSL/TLS transport layer. When used for
15240 an ACL, the value(s) to match against can be passed in hexadecimal form.
15241
Willy Tarreau74ca5042013-06-11 23:12:07 +020015242ssl_c_err : integer
15243 When the incoming connection was made over an SSL/TLS transport layer,
15244 returns the ID of the first error detected during verification at depth 0, or
15245 0 if no error was encountered during this verification process. Please refer
15246 to your SSL library's documentation to find the exhaustive list of error
15247 codes.
Willy Tarreau62644772008-07-16 18:36:06 +020015248
Willy Tarreau74ca5042013-06-11 23:12:07 +020015249ssl_c_i_dn([<entry>[,<occ>]]) : string
15250 When the incoming connection was made over an SSL/TLS transport layer,
15251 returns the full distinguished name of the issuer of the certificate
15252 presented by the client when no <entry> is specified, or the value of the
15253 first given entry found from the beginning of the DN. If a positive/negative
15254 occurrence number is specified as the optional second argument, it returns
15255 the value of the nth given entry value from the beginning/end of the DN.
15256 For instance, "ssl_c_i_dn(OU,2)" the second organization unit, and
15257 "ssl_c_i_dn(CN)" retrieves the common name.
Willy Tarreau62644772008-07-16 18:36:06 +020015258
Willy Tarreau74ca5042013-06-11 23:12:07 +020015259ssl_c_key_alg : string
15260 Returns the name of the algorithm used to generate the key of the certificate
15261 presented by the client when the incoming connection was made over an SSL/TLS
15262 transport layer.
Willy Tarreau62644772008-07-16 18:36:06 +020015263
Willy Tarreau74ca5042013-06-11 23:12:07 +020015264ssl_c_notafter : string
15265 Returns the end date presented by the client as a formatted string
15266 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
15267 transport layer.
Emeric Brunbede3d02009-06-30 17:54:00 +020015268
Willy Tarreau74ca5042013-06-11 23:12:07 +020015269ssl_c_notbefore : string
15270 Returns the start date presented by the client as a formatted string
15271 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
15272 transport layer.
Willy Tarreaub6672b52011-12-12 17:23:41 +010015273
Willy Tarreau74ca5042013-06-11 23:12:07 +020015274ssl_c_s_dn([<entry>[,<occ>]]) : string
15275 When the incoming connection was made over an SSL/TLS transport layer,
15276 returns the full distinguished name of the subject of the certificate
15277 presented by the client when no <entry> is specified, or the value of the
15278 first given entry found from the beginning of the DN. If a positive/negative
15279 occurrence number is specified as the optional second argument, it returns
15280 the value of the nth given entry value from the beginning/end of the DN.
15281 For instance, "ssl_c_s_dn(OU,2)" the second organization unit, and
15282 "ssl_c_s_dn(CN)" retrieves the common name.
Willy Tarreaub6672b52011-12-12 17:23:41 +010015283
Willy Tarreau74ca5042013-06-11 23:12:07 +020015284ssl_c_serial : binary
15285 Returns the serial of the certificate presented by the client when the
15286 incoming connection was made over an SSL/TLS transport layer. When used for
15287 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun2525b6b2012-10-18 15:59:43 +020015288
Willy Tarreau74ca5042013-06-11 23:12:07 +020015289ssl_c_sha1 : binary
15290 Returns the SHA-1 fingerprint of the certificate presented by the client when
15291 the incoming connection was made over an SSL/TLS transport layer. This can be
15292 used to stick a client to a server, or to pass this information to a server.
Willy Tarreau2d0caa32014-07-02 19:01:22 +020015293 Note that the output is binary, so if you want to pass that signature to the
15294 server, you need to encode it in hex or base64, such as in the example below:
15295
Jarno Huuskonen676f6222017-03-30 09:19:45 +030015296 Example:
Willy Tarreau2d0caa32014-07-02 19:01:22 +020015297 http-request set-header X-SSL-Client-SHA1 %[ssl_c_sha1,hex]
Emeric Brun2525b6b2012-10-18 15:59:43 +020015298
Willy Tarreau74ca5042013-06-11 23:12:07 +020015299ssl_c_sig_alg : string
15300 Returns the name of the algorithm used to sign the certificate presented by
15301 the client when the incoming connection was made over an SSL/TLS transport
15302 layer.
Emeric Brun87855892012-10-17 17:39:35 +020015303
Willy Tarreau74ca5042013-06-11 23:12:07 +020015304ssl_c_used : boolean
15305 Returns true if current SSL session uses a client certificate even if current
15306 connection uses SSL session resumption. See also "ssl_fc_has_crt".
Emeric Brun7f56e742012-10-19 18:15:40 +020015307
Willy Tarreau74ca5042013-06-11 23:12:07 +020015308ssl_c_verify : integer
15309 Returns the verify result error ID when the incoming connection was made over
15310 an SSL/TLS transport layer, otherwise zero if no error is encountered. Please
15311 refer to your SSL library's documentation for an exhaustive list of error
15312 codes.
Emeric Brunce5ad802012-10-22 14:11:22 +020015313
Willy Tarreau74ca5042013-06-11 23:12:07 +020015314ssl_c_version : integer
15315 Returns the version of the certificate presented by the client when the
15316 incoming connection was made over an SSL/TLS transport layer.
Emeric Brunce5ad802012-10-22 14:11:22 +020015317
Emeric Brun43e79582014-10-29 19:03:26 +010015318ssl_f_der : binary
15319 Returns the DER formatted certificate presented by the frontend when the
15320 incoming connection was made over an SSL/TLS transport layer. When used for
15321 an ACL, the value(s) to match against can be passed in hexadecimal form.
15322
Willy Tarreau74ca5042013-06-11 23:12:07 +020015323ssl_f_i_dn([<entry>[,<occ>]]) : string
15324 When the incoming connection was made over an SSL/TLS transport layer,
15325 returns the full distinguished name of the issuer of the certificate
15326 presented by the frontend when no <entry> is specified, or the value of the
15327 first given entry found from the beginning of the DN. If a positive/negative
Emeric Brun87855892012-10-17 17:39:35 +020015328 occurrence number is specified as the optional second argument, it returns
Willy Tarreau74ca5042013-06-11 23:12:07 +020015329 the value of the nth given entry value from the beginning/end of the DN.
15330 For instance, "ssl_f_i_dn(OU,2)" the second organization unit, and
15331 "ssl_f_i_dn(CN)" retrieves the common name.
Emeric Brun87855892012-10-17 17:39:35 +020015332
Willy Tarreau74ca5042013-06-11 23:12:07 +020015333ssl_f_key_alg : string
15334 Returns the name of the algorithm used to generate the key of the certificate
15335 presented by the frontend when the incoming connection was made over an
15336 SSL/TLS transport layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020015337
Willy Tarreau74ca5042013-06-11 23:12:07 +020015338ssl_f_notafter : string
15339 Returns the end date presented by the frontend as a formatted string
15340 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
15341 transport layer.
Emeric Brun2525b6b2012-10-18 15:59:43 +020015342
Willy Tarreau74ca5042013-06-11 23:12:07 +020015343ssl_f_notbefore : string
15344 Returns the start date presented by the frontend as a formatted string
15345 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
15346 transport layer.
Emeric Brun87855892012-10-17 17:39:35 +020015347
Willy Tarreau74ca5042013-06-11 23:12:07 +020015348ssl_f_s_dn([<entry>[,<occ>]]) : string
15349 When the incoming connection was made over an SSL/TLS transport layer,
15350 returns the full distinguished name of the subject of the certificate
15351 presented by the frontend when no <entry> is specified, or the value of the
15352 first given entry found from the beginning of the DN. If a positive/negative
15353 occurrence number is specified as the optional second argument, it returns
15354 the value of the nth given entry value from the beginning/end of the DN.
15355 For instance, "ssl_f_s_dn(OU,2)" the second organization unit, and
15356 "ssl_f_s_dn(CN)" retrieves the common name.
Emeric Brunce5ad802012-10-22 14:11:22 +020015357
Willy Tarreau74ca5042013-06-11 23:12:07 +020015358ssl_f_serial : binary
15359 Returns the serial of the certificate presented by the frontend when the
15360 incoming connection was made over an SSL/TLS transport layer. When used for
15361 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun87855892012-10-17 17:39:35 +020015362
Emeric Brun55f4fa82014-04-30 17:11:25 +020015363ssl_f_sha1 : binary
15364 Returns the SHA-1 fingerprint of the certificate presented by the frontend
15365 when the incoming connection was made over an SSL/TLS transport layer. This
15366 can be used to know which certificate was chosen using SNI.
15367
Willy Tarreau74ca5042013-06-11 23:12:07 +020015368ssl_f_sig_alg : string
15369 Returns the name of the algorithm used to sign the certificate presented by
15370 the frontend when the incoming connection was made over an SSL/TLS transport
15371 layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020015372
Willy Tarreau74ca5042013-06-11 23:12:07 +020015373ssl_f_version : integer
15374 Returns the version of the certificate presented by the frontend when the
15375 incoming connection was made over an SSL/TLS transport layer.
15376
15377ssl_fc : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020015378 Returns true when the front connection was made via an SSL/TLS transport
15379 layer and is locally deciphered. This means it has matched a socket declared
15380 with a "bind" line having the "ssl" option.
15381
Willy Tarreau74ca5042013-06-11 23:12:07 +020015382 Example :
15383 # This passes "X-Proto: https" to servers when client connects over SSL
15384 listen http-https
15385 bind :80
15386 bind :443 ssl crt /etc/haproxy.pem
15387 http-request add-header X-Proto https if { ssl_fc }
15388
15389ssl_fc_alg_keysize : integer
15390 Returns the symmetric cipher key size supported in bits when the incoming
15391 connection was made over an SSL/TLS transport layer.
15392
15393ssl_fc_alpn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030015394 This extracts the Application Layer Protocol Negotiation field from an
Willy Tarreau74ca5042013-06-11 23:12:07 +020015395 incoming connection made via a TLS transport layer and locally deciphered by
15396 haproxy. The result is a string containing the protocol name advertised by
15397 the client. The SSL library must have been built with support for TLS
15398 extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
15399 not advertised unless the "alpn" keyword on the "bind" line specifies a
15400 protocol list. Also, nothing forces the client to pick a protocol from this
15401 list, any other one may be requested. The TLS ALPN extension is meant to
15402 replace the TLS NPN extension. See also "ssl_fc_npn".
15403
Willy Tarreau74ca5042013-06-11 23:12:07 +020015404ssl_fc_cipher : string
15405 Returns the name of the used cipher when the incoming connection was made
15406 over an SSL/TLS transport layer.
Willy Tarreauab861d32013-04-02 02:30:41 +020015407
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010015408ssl_fc_cipherlist_bin : binary
15409 Returns the binary form of the client hello cipher list. The maximum returned
15410 value length is according with the value of
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010015411 "tune.ssl.capture-cipherlist-size".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010015412
15413ssl_fc_cipherlist_hex : string
15414 Returns the binary form of the client hello cipher list encoded as
15415 hexadecimal. The maximum returned value length is according with the value of
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010015416 "tune.ssl.capture-cipherlist-size".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010015417
15418ssl_fc_cipherlist_str : string
15419 Returns the decoded text form of the client hello cipher list. The maximum
15420 number of ciphers returned is according with the value of
15421 "tune.ssl.capture-cipherlist-size". Note that this sample-fetch is only
Davor Ocelice9ed2812017-12-25 17:49:28 +010015422 available with OpenSSL >= 1.0.2. If the function is not enabled, this
Emmanuel Hocdetddcde192017-09-01 17:32:08 +020015423 sample-fetch returns the hash like "ssl_fc_cipherlist_xxh".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010015424
15425ssl_fc_cipherlist_xxh : integer
15426 Returns a xxh64 of the cipher list. This hash can be return only is the value
15427 "tune.ssl.capture-cipherlist-size" is set greater than 0, however the hash
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010015428 take in account all the data of the cipher list.
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010015429
Patrick Hemmer65674662019-06-04 08:13:03 -040015430ssl_fc_client_random : binary
15431 Returns the client random of the front connection when the incoming connection
15432 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
15433 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
15434
Willy Tarreau74ca5042013-06-11 23:12:07 +020015435ssl_fc_has_crt : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020015436 Returns true if a client certificate is present in an incoming connection over
15437 SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
Emeric Brun9143d372012-12-20 15:44:16 +010015438 Note: on SSL session resumption with Session ID or TLS ticket, client
15439 certificate is not present in the current connection but may be retrieved
15440 from the cache or the ticket. So prefer "ssl_c_used" if you want to check if
15441 current SSL session uses a client certificate.
Emeric Brun2525b6b2012-10-18 15:59:43 +020015442
Olivier Houchardccaa7de2017-10-02 11:51:03 +020015443ssl_fc_has_early : boolean
15444 Returns true if early data were sent, and the handshake didn't happen yet. As
15445 it has security implications, it is useful to be able to refuse those, or
15446 wait until the handshake happened.
15447
Willy Tarreau74ca5042013-06-11 23:12:07 +020015448ssl_fc_has_sni : boolean
15449 This checks for the presence of a Server Name Indication TLS extension (SNI)
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020015450 in an incoming connection was made over an SSL/TLS transport layer. Returns
15451 true when the incoming connection presents a TLS SNI field. This requires
John Roeslerfb2fce12019-07-10 15:45:51 -050015452 that the SSL library is built with support for TLS extensions enabled (check
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020015453 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +020015454
Nenad Merdanovic1516fe32016-05-17 03:31:21 +020015455ssl_fc_is_resumed : boolean
Nenad Merdanovic26ea8222015-05-18 02:28:57 +020015456 Returns true if the SSL/TLS session has been resumed through the use of
Jérôme Magnin4a326cb2018-01-15 14:01:17 +010015457 SSL session cache or TLS tickets on an incoming connection over an SSL/TLS
15458 transport layer.
Nenad Merdanovic26ea8222015-05-18 02:28:57 +020015459
Willy Tarreau74ca5042013-06-11 23:12:07 +020015460ssl_fc_npn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030015461 This extracts the Next Protocol Negotiation field from an incoming connection
Willy Tarreau74ca5042013-06-11 23:12:07 +020015462 made via a TLS transport layer and locally deciphered by haproxy. The result
15463 is a string containing the protocol name advertised by the client. The SSL
15464 library must have been built with support for TLS extensions enabled (check
15465 haproxy -vv). Note that the TLS NPN extension is not advertised unless the
15466 "npn" keyword on the "bind" line specifies a protocol list. Also, nothing
15467 forces the client to pick a protocol from this list, any other one may be
15468 requested. Please note that the TLS NPN extension was replaced with ALPN.
Willy Tarreaua33c6542012-10-15 13:19:06 +020015469
Willy Tarreau74ca5042013-06-11 23:12:07 +020015470ssl_fc_protocol : string
15471 Returns the name of the used protocol when the incoming connection was made
15472 over an SSL/TLS transport layer.
Willy Tarreau7875d092012-09-10 08:20:03 +020015473
Emeric Brunb73a9b02014-04-30 18:49:19 +020015474ssl_fc_unique_id : binary
David Sc1ad52e2014-04-08 18:48:47 -040015475 When the incoming connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020015476 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
15477 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".
David Sc1ad52e2014-04-08 18:48:47 -040015478
Patrick Hemmer65674662019-06-04 08:13:03 -040015479ssl_fc_server_random : binary
15480 Returns the server random of the front connection when the incoming connection
15481 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
15482 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
15483
Willy Tarreau74ca5042013-06-11 23:12:07 +020015484ssl_fc_session_id : binary
15485 Returns the SSL ID of the front connection when the incoming connection was
15486 made over an SSL/TLS transport layer. It is useful to stick a given client to
15487 a server. It is important to note that some browsers refresh their session ID
15488 every few minutes.
Willy Tarreau7875d092012-09-10 08:20:03 +020015489
Patrick Hemmere0275472018-04-28 19:15:51 -040015490ssl_fc_session_key : binary
15491 Returns the SSL session master key of the front connection when the incoming
15492 connection was made over an SSL/TLS transport layer. It is useful to decrypt
15493 traffic sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or
15494 BoringSSL.
15495
15496
Willy Tarreau74ca5042013-06-11 23:12:07 +020015497ssl_fc_sni : string
15498 This extracts the Server Name Indication TLS extension (SNI) field from an
15499 incoming connection made via an SSL/TLS transport layer and locally
15500 deciphered by haproxy. The result (when present) typically is a string
15501 matching the HTTPS host name (253 chars or less). The SSL library must have
15502 been built with support for TLS extensions enabled (check haproxy -vv).
15503
15504 This fetch is different from "req_ssl_sni" above in that it applies to the
15505 connection being deciphered by haproxy and not to SSL contents being blindly
15506 forwarded. See also "ssl_fc_sni_end" and "ssl_fc_sni_reg" below. This
John Roeslerfb2fce12019-07-10 15:45:51 -050015507 requires that the SSL library is built with support for TLS extensions
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +020015508 enabled (check haproxy -vv).
Willy Tarreau62644772008-07-16 18:36:06 +020015509
Willy Tarreau74ca5042013-06-11 23:12:07 +020015510 ACL derivatives :
Willy Tarreau74ca5042013-06-11 23:12:07 +020015511 ssl_fc_sni_end : suffix match
15512 ssl_fc_sni_reg : regex match
Emeric Brun589fcad2012-10-16 14:13:26 +020015513
Willy Tarreau74ca5042013-06-11 23:12:07 +020015514ssl_fc_use_keysize : integer
15515 Returns the symmetric cipher key size used in bits when the incoming
15516 connection was made over an SSL/TLS transport layer.
Willy Tarreaub6fb4202008-07-20 11:18:28 +020015517
Willy Tarreaub6fb4202008-07-20 11:18:28 +020015518
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200155197.3.5. Fetching samples from buffer contents (Layer 6)
Willy Tarreau74ca5042013-06-11 23:12:07 +020015520------------------------------------------------------
Willy Tarreaub6fb4202008-07-20 11:18:28 +020015521
Willy Tarreau74ca5042013-06-11 23:12:07 +020015522Fetching samples from buffer contents is a bit different from the previous
15523sample fetches above because the sampled data are ephemeral. These data can
15524only be used when they're available and will be lost when they're forwarded.
15525For this reason, samples fetched from buffer contents during a request cannot
15526be used in a response for example. Even while the data are being fetched, they
15527can change. Sometimes it is necessary to set some delays or combine multiple
15528sample fetch methods to ensure that the expected data are complete and usable,
15529for example through TCP request content inspection. Please see the "tcp-request
15530content" keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +020015531
Willy Tarreau74ca5042013-06-11 23:12:07 +020015532payload(<offset>,<length>) : binary (deprecated)
Davor Ocelice9ed2812017-12-25 17:49:28 +010015533 This is an alias for "req.payload" when used in the context of a request (e.g.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015534 "stick on", "stick match"), and for "res.payload" when used in the context of
15535 a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010015536
Willy Tarreau74ca5042013-06-11 23:12:07 +020015537payload_lv(<offset1>,<length>[,<offset2>]) : binary (deprecated)
15538 This is an alias for "req.payload_lv" when used in the context of a request
Davor Ocelice9ed2812017-12-25 17:49:28 +010015539 (e.g. "stick on", "stick match"), and for "res.payload_lv" when used in the
Willy Tarreau74ca5042013-06-11 23:12:07 +020015540 context of a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010015541
Thierry FOURNIERd7d88812017-04-19 15:15:14 +020015542req.hdrs : string
15543 Returns the current request headers as string including the last empty line
15544 separating headers from the request body. The last empty line can be used to
15545 detect a truncated header block. This sample fetch is useful for some SPOE
15546 headers analyzers and for advanced logging.
15547
Thierry FOURNIER5617dce2017-04-09 05:38:19 +020015548req.hdrs_bin : binary
15549 Returns the current request headers contained in preparsed binary form. This
15550 is useful for offloading some processing with SPOE. Each string is described
15551 by a length followed by the number of bytes indicated in the length. The
15552 length is represented using the variable integer encoding detailed in the
15553 SPOE documentation. The end of the list is marked by a couple of empty header
15554 names and values (length of 0 for both).
15555
15556 *(<str:header-name><str:header-value>)<empty string><empty string>
15557
15558 int: refer to the SPOE documentation for the encoding
15559 str: <int:length><bytes>
15560
Willy Tarreau74ca5042013-06-11 23:12:07 +020015561req.len : integer
15562req_len : integer (deprecated)
15563 Returns an integer value corresponding to the number of bytes present in the
15564 request buffer. This is mostly used in ACL. It is important to understand
15565 that this test does not return false as long as the buffer is changing. This
15566 means that a check with equality to zero will almost always immediately match
15567 at the beginning of the session, while a test for more data will wait for
15568 that data to come in and return false only when haproxy is certain that no
15569 more data will come in. This test was designed to be used with TCP request
15570 content inspection.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015571
Willy Tarreau74ca5042013-06-11 23:12:07 +020015572req.payload(<offset>,<length>) : binary
15573 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020015574 in the request buffer. As a special case, if the <length> argument is zero,
15575 the the whole buffer from <offset> to the end is extracted. This can be used
15576 with ACLs in order to check for the presence of some content in a buffer at
15577 any location.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015578
Willy Tarreau74ca5042013-06-11 23:12:07 +020015579 ACL alternatives :
15580 payload(<offset>,<length>) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015581
Willy Tarreau74ca5042013-06-11 23:12:07 +020015582req.payload_lv(<offset1>,<length>[,<offset2>]) : binary
15583 This extracts a binary block whose size is specified at <offset1> for <length>
15584 bytes, and which starts at <offset2> if specified or just after the length in
15585 the request buffer. The <offset2> parameter also supports relative offsets if
15586 prepended with a '+' or '-' sign.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015587
Willy Tarreau74ca5042013-06-11 23:12:07 +020015588 ACL alternatives :
15589 payload_lv(<offset1>,<length>[,<offset2>]) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015590
Willy Tarreau74ca5042013-06-11 23:12:07 +020015591 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015592
Willy Tarreau74ca5042013-06-11 23:12:07 +020015593req.proto_http : boolean
15594req_proto_http : boolean (deprecated)
15595 Returns true when data in the request buffer look like HTTP and correctly
15596 parses as such. It is the same parser as the common HTTP request parser which
15597 is used so there should be no surprises. The test does not match until the
15598 request is complete, failed or timed out. This test may be used to report the
15599 protocol in TCP logs, but the biggest use is to block TCP request analysis
15600 until a complete HTTP request is present in the buffer, for example to track
15601 a header.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015602
Willy Tarreau74ca5042013-06-11 23:12:07 +020015603 Example:
15604 # track request counts per "base" (concatenation of Host+URL)
15605 tcp-request inspect-delay 10s
15606 tcp-request content reject if !HTTP
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020015607 tcp-request content track-sc0 base table req-rate
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020015608
Willy Tarreau74ca5042013-06-11 23:12:07 +020015609req.rdp_cookie([<name>]) : string
15610rdp_cookie([<name>]) : string (deprecated)
15611 When the request buffer looks like the RDP protocol, extracts the RDP cookie
15612 <name>, or any cookie if unspecified. The parser only checks for the first
15613 cookie, as illustrated in the RDP protocol specification. The cookie name is
15614 case insensitive. Generally the "MSTS" cookie name will be used, as it can
15615 contain the user name of the client connecting to the server if properly
15616 configured on the client. The "MSTSHASH" cookie is often used as well for
15617 session stickiness to servers.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015618
Willy Tarreau74ca5042013-06-11 23:12:07 +020015619 This differs from "balance rdp-cookie" in that any balancing algorithm may be
15620 used and thus the distribution of clients to backend servers is not linked to
15621 a hash of the RDP cookie. It is envisaged that using a balancing algorithm
15622 such as "balance roundrobin" or "balance leastconn" will lead to a more even
15623 distribution of clients to backend servers than the hash used by "balance
15624 rdp-cookie".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015625
Willy Tarreau74ca5042013-06-11 23:12:07 +020015626 ACL derivatives :
15627 req_rdp_cookie([<name>]) : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015628
Willy Tarreau74ca5042013-06-11 23:12:07 +020015629 Example :
15630 listen tse-farm
15631 bind 0.0.0.0:3389
15632 # wait up to 5s for an RDP cookie in the request
15633 tcp-request inspect-delay 5s
15634 tcp-request content accept if RDP_COOKIE
15635 # apply RDP cookie persistence
15636 persist rdp-cookie
15637 # Persist based on the mstshash cookie
15638 # This is only useful makes sense if
15639 # balance rdp-cookie is not used
15640 stick-table type string size 204800
15641 stick on req.rdp_cookie(mstshash)
15642 server srv1 1.1.1.1:3389
15643 server srv1 1.1.1.2:3389
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015644
Willy Tarreau74ca5042013-06-11 23:12:07 +020015645 See also : "balance rdp-cookie", "persist rdp-cookie", "tcp-request" and the
15646 "req_rdp_cookie" ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015647
Willy Tarreau74ca5042013-06-11 23:12:07 +020015648req.rdp_cookie_cnt([name]) : integer
15649rdp_cookie_cnt([name]) : integer (deprecated)
15650 Tries to parse the request buffer as RDP protocol, then returns an integer
15651 corresponding to the number of RDP cookies found. If an optional cookie name
15652 is passed, only cookies matching this name are considered. This is mostly
15653 used in ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015654
Willy Tarreau74ca5042013-06-11 23:12:07 +020015655 ACL derivatives :
15656 req_rdp_cookie_cnt([<name>]) : integer match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015657
Alex Zorin4afdd132018-12-30 13:56:28 +110015658req.ssl_alpn : string
15659 Returns a string containing the values of the Application-Layer Protocol
15660 Negotiation (ALPN) TLS extension (RFC7301), sent by the client within the SSL
15661 ClientHello message. Note that this only applies to raw contents found in the
15662 request buffer and not to the contents deciphered via an SSL data layer, so
15663 this will not work with "bind" lines having the "ssl" option. This is useful
15664 in ACL to make a routing decision based upon the ALPN preferences of a TLS
Jarno Huuskonene504f812019-01-03 07:56:49 +020015665 client, like in the example below. See also "ssl_fc_alpn".
Alex Zorin4afdd132018-12-30 13:56:28 +110015666
15667 Examples :
15668 # Wait for a client hello for at most 5 seconds
15669 tcp-request inspect-delay 5s
15670 tcp-request content accept if { req_ssl_hello_type 1 }
Jarno Huuskonene504f812019-01-03 07:56:49 +020015671 use_backend bk_acme if { req.ssl_alpn acme-tls/1 }
Alex Zorin4afdd132018-12-30 13:56:28 +110015672 default_backend bk_default
15673
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020015674req.ssl_ec_ext : boolean
15675 Returns a boolean identifying if client sent the Supported Elliptic Curves
15676 Extension as defined in RFC4492, section 5.1. within the SSL ClientHello
Cyril Bonté307ee1e2015-09-28 23:16:06 +020015677 message. This can be used to present ECC compatible clients with EC
15678 certificate and to use RSA for all others, on the same IP address. Note that
15679 this only applies to raw contents found in the request buffer and not to
15680 contents deciphered via an SSL data layer, so this will not work with "bind"
15681 lines having the "ssl" option.
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020015682
Willy Tarreau74ca5042013-06-11 23:12:07 +020015683req.ssl_hello_type : integer
15684req_ssl_hello_type : integer (deprecated)
15685 Returns an integer value containing the type of the SSL hello message found
15686 in the request buffer if the buffer contains data that parse as a complete
15687 SSL (v3 or superior) client hello message. Note that this only applies to raw
15688 contents found in the request buffer and not to contents deciphered via an
15689 SSL data layer, so this will not work with "bind" lines having the "ssl"
15690 option. This is mostly used in ACL to detect presence of an SSL hello message
15691 that is supposed to contain an SSL session ID usable for stickiness.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015692
Willy Tarreau74ca5042013-06-11 23:12:07 +020015693req.ssl_sni : string
15694req_ssl_sni : string (deprecated)
15695 Returns a string containing the value of the Server Name TLS extension sent
15696 by a client in a TLS stream passing through the request buffer if the buffer
15697 contains data that parse as a complete SSL (v3 or superior) client hello
15698 message. Note that this only applies to raw contents found in the request
15699 buffer and not to contents deciphered via an SSL data layer, so this will not
15700 work with "bind" lines having the "ssl" option. SNI normally contains the
15701 name of the host the client tries to connect to (for recent browsers). SNI is
15702 useful for allowing or denying access to certain hosts when SSL/TLS is used
15703 by the client. This test was designed to be used with TCP request content
15704 inspection. If content switching is needed, it is recommended to first wait
15705 for a complete client hello (type 1), like in the example below. See also
15706 "ssl_fc_sni".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015707
Willy Tarreau74ca5042013-06-11 23:12:07 +020015708 ACL derivatives :
15709 req_ssl_sni : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015710
Willy Tarreau74ca5042013-06-11 23:12:07 +020015711 Examples :
15712 # Wait for a client hello for at most 5 seconds
15713 tcp-request inspect-delay 5s
15714 tcp-request content accept if { req_ssl_hello_type 1 }
15715 use_backend bk_allow if { req_ssl_sni -f allowed_sites }
15716 default_backend bk_sorry_page
Willy Tarreau04aa6a92012-04-06 18:57:55 +020015717
Pradeep Jindalbb2acf52015-09-29 10:12:57 +053015718req.ssl_st_ext : integer
15719 Returns 0 if the client didn't send a SessionTicket TLS Extension (RFC5077)
15720 Returns 1 if the client sent SessionTicket TLS Extension
15721 Returns 2 if the client also sent non-zero length TLS SessionTicket
15722 Note that this only applies to raw contents found in the request buffer and
15723 not to contents deciphered via an SSL data layer, so this will not work with
15724 "bind" lines having the "ssl" option. This can for example be used to detect
15725 whether the client sent a SessionTicket or not and stick it accordingly, if
15726 no SessionTicket then stick on SessionID or don't stick as there's no server
15727 side state is there when SessionTickets are in use.
15728
Willy Tarreau74ca5042013-06-11 23:12:07 +020015729req.ssl_ver : integer
15730req_ssl_ver : integer (deprecated)
15731 Returns an integer value containing the version of the SSL/TLS protocol of a
15732 stream present in the request buffer. Both SSLv2 hello messages and SSLv3
15733 messages are supported. TLSv1 is announced as SSL version 3.1. The value is
15734 composed of the major version multiplied by 65536, added to the minor
15735 version. Note that this only applies to raw contents found in the request
15736 buffer and not to contents deciphered via an SSL data layer, so this will not
15737 work with "bind" lines having the "ssl" option. The ACL version of the test
Davor Ocelice9ed2812017-12-25 17:49:28 +010015738 matches against a decimal notation in the form MAJOR.MINOR (e.g. 3.1). This
Willy Tarreau74ca5042013-06-11 23:12:07 +020015739 fetch is mostly used in ACL.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015740
Willy Tarreau74ca5042013-06-11 23:12:07 +020015741 ACL derivatives :
15742 req_ssl_ver : decimal match
Willy Tarreaud63335a2010-02-26 12:56:52 +010015743
Willy Tarreau47e8eba2013-09-11 23:28:46 +020015744res.len : integer
15745 Returns an integer value corresponding to the number of bytes present in the
15746 response buffer. This is mostly used in ACL. It is important to understand
15747 that this test does not return false as long as the buffer is changing. This
15748 means that a check with equality to zero will almost always immediately match
15749 at the beginning of the session, while a test for more data will wait for
15750 that data to come in and return false only when haproxy is certain that no
15751 more data will come in. This test was designed to be used with TCP response
15752 content inspection.
15753
Willy Tarreau74ca5042013-06-11 23:12:07 +020015754res.payload(<offset>,<length>) : binary
15755 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020015756 in the response buffer. As a special case, if the <length> argument is zero,
15757 the the whole buffer from <offset> to the end is extracted. This can be used
15758 with ACLs in order to check for the presence of some content in a buffer at
15759 any location.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015760
Willy Tarreau74ca5042013-06-11 23:12:07 +020015761res.payload_lv(<offset1>,<length>[,<offset2>]) : binary
15762 This extracts a binary block whose size is specified at <offset1> for <length>
15763 bytes, and which starts at <offset2> if specified or just after the length in
15764 the response buffer. The <offset2> parameter also supports relative offsets
15765 if prepended with a '+' or '-' sign.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015766
Willy Tarreau74ca5042013-06-11 23:12:07 +020015767 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015768
Willy Tarreau971f7b62015-09-29 14:06:59 +020015769res.ssl_hello_type : integer
15770rep_ssl_hello_type : integer (deprecated)
15771 Returns an integer value containing the type of the SSL hello message found
15772 in the response buffer if the buffer contains data that parses as a complete
15773 SSL (v3 or superior) hello message. Note that this only applies to raw
15774 contents found in the response buffer and not to contents deciphered via an
15775 SSL data layer, so this will not work with "server" lines having the "ssl"
15776 option. This is mostly used in ACL to detect presence of an SSL hello message
15777 that is supposed to contain an SSL session ID usable for stickiness.
15778
Willy Tarreau74ca5042013-06-11 23:12:07 +020015779wait_end : boolean
15780 This fetch either returns true when the inspection period is over, or does
15781 not fetch. It is only used in ACLs, in conjunction with content analysis to
Davor Ocelice9ed2812017-12-25 17:49:28 +010015782 avoid returning a wrong verdict early. It may also be used to delay some
Willy Tarreau74ca5042013-06-11 23:12:07 +020015783 actions, such as a delayed reject for some special addresses. Since it either
15784 stops the rules evaluation or immediately returns true, it is recommended to
Davor Ocelice9ed2812017-12-25 17:49:28 +010015785 use this acl as the last one in a rule. Please note that the default ACL
Willy Tarreau74ca5042013-06-11 23:12:07 +020015786 "WAIT_END" is always usable without prior declaration. This test was designed
15787 to be used with TCP request content inspection.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015788
Willy Tarreau74ca5042013-06-11 23:12:07 +020015789 Examples :
15790 # delay every incoming request by 2 seconds
15791 tcp-request inspect-delay 2s
15792 tcp-request content accept if WAIT_END
Willy Tarreaud63335a2010-02-26 12:56:52 +010015793
Willy Tarreau74ca5042013-06-11 23:12:07 +020015794 # don't immediately tell bad guys they are rejected
15795 tcp-request inspect-delay 10s
15796 acl goodguys src 10.0.0.0/24
15797 acl badguys src 10.0.1.0/24
15798 tcp-request content accept if goodguys
15799 tcp-request content reject if badguys WAIT_END
15800 tcp-request content reject
15801
15802
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200158037.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +020015804--------------------------------------
15805
15806It is possible to fetch samples from HTTP contents, requests and responses.
15807This application layer is also called layer 7. It is only possible to fetch the
15808data in this section when a full HTTP request or response has been parsed from
15809its respective request or response buffer. This is always the case with all
15810HTTP specific rules and for sections running with "mode http". When using TCP
15811content inspection, it may be necessary to support an inspection delay in order
15812to let the request or response come in first. These fetches may require a bit
15813more CPU resources than the layer 4 ones, but not much since the request and
15814response are indexed.
15815
15816base : string
15817 This returns the concatenation of the first Host header and the path part of
15818 the request, which starts at the first slash and ends before the question
15819 mark. It can be useful in virtual hosted environments to detect URL abuses as
15820 well as to improve shared caches efficiency. Using this with a limited size
15821 stick table also allows one to collect statistics about most commonly
15822 requested objects by host/path. With ACLs it can allow simple content
15823 switching rules involving the host and the path at the same time, such as
15824 "www.example.com/favicon.ico". See also "path" and "uri".
15825
15826 ACL derivatives :
15827 base : exact string match
15828 base_beg : prefix match
15829 base_dir : subdir match
15830 base_dom : domain match
15831 base_end : suffix match
15832 base_len : length match
15833 base_reg : regex match
15834 base_sub : substring match
15835
15836base32 : integer
15837 This returns a 32-bit hash of the value returned by the "base" fetch method
15838 above. This is useful to track per-URL activity on high traffic sites without
15839 having to store all URLs. Instead a shorter hash is stored, saving a lot of
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020015840 memory. The output type is an unsigned integer. The hash function used is
15841 SDBM with full avalanche on the output. Technically, base32 is exactly equal
15842 to "base,sdbm(1)".
Willy Tarreau74ca5042013-06-11 23:12:07 +020015843
15844base32+src : binary
15845 This returns the concatenation of the base32 fetch above and the src fetch
15846 below. The resulting type is of type binary, with a size of 8 or 20 bytes
15847 depending on the source address family. This can be used to track per-IP,
15848 per-URL counters.
15849
William Lallemand65ad6e12014-01-31 15:08:02 +010015850capture.req.hdr(<idx>) : string
15851 This extracts the content of the header captured by the "capture request
15852 header", idx is the position of the capture keyword in the configuration.
15853 The first entry is an index of 0. See also: "capture request header".
15854
15855capture.req.method : string
15856 This extracts the METHOD of an HTTP request. It can be used in both request
15857 and response. Unlike "method", it can be used in both request and response
15858 because it's allocated.
15859
15860capture.req.uri : string
15861 This extracts the request's URI, which starts at the first slash and ends
15862 before the first space in the request (without the host part). Unlike "path"
15863 and "url", it can be used in both request and response because it's
15864 allocated.
15865
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020015866capture.req.ver : string
15867 This extracts the request's HTTP version and returns either "HTTP/1.0" or
15868 "HTTP/1.1". Unlike "req.ver", it can be used in both request, response, and
15869 logs because it relies on a persistent flag.
15870
William Lallemand65ad6e12014-01-31 15:08:02 +010015871capture.res.hdr(<idx>) : string
15872 This extracts the content of the header captured by the "capture response
15873 header", idx is the position of the capture keyword in the configuration.
15874 The first entry is an index of 0.
15875 See also: "capture response header"
15876
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020015877capture.res.ver : string
15878 This extracts the response's HTTP version and returns either "HTTP/1.0" or
15879 "HTTP/1.1". Unlike "res.ver", it can be used in logs because it relies on a
15880 persistent flag.
15881
Willy Tarreaua5910cc2015-05-02 00:46:08 +020015882req.body : binary
15883 This returns the HTTP request's available body as a block of data. It
15884 requires that the request body has been buffered made available using
15885 "option http-buffer-request". In case of chunked-encoded body, currently only
15886 the first chunk is analyzed.
15887
Thierry FOURNIER9826c772015-05-20 15:50:54 +020015888req.body_param([<name>) : string
15889 This fetch assumes that the body of the POST request is url-encoded. The user
15890 can check if the "content-type" contains the value
15891 "application/x-www-form-urlencoded". This extracts the first occurrence of the
15892 parameter <name> in the body, which ends before '&'. The parameter name is
15893 case-sensitive. If no name is given, any parameter will match, and the first
15894 one will be returned. The result is a string corresponding to the value of the
15895 parameter <name> as presented in the request body (no URL decoding is
15896 performed). Note that the ACL version of this fetch iterates over multiple
15897 parameters and will iteratively report all parameters values if no name is
15898 given.
15899
Willy Tarreaua5910cc2015-05-02 00:46:08 +020015900req.body_len : integer
15901 This returns the length of the HTTP request's available body in bytes. It may
15902 be lower than the advertised length if the body is larger than the buffer. It
15903 requires that the request body has been buffered made available using
15904 "option http-buffer-request".
15905
15906req.body_size : integer
15907 This returns the advertised length of the HTTP request's body in bytes. It
15908 will represent the advertised Content-Length header, or the size of the first
15909 chunk in case of chunked encoding. In order to parse the chunks, it requires
15910 that the request body has been buffered made available using
15911 "option http-buffer-request".
15912
Willy Tarreau74ca5042013-06-11 23:12:07 +020015913req.cook([<name>]) : string
15914cook([<name>]) : string (deprecated)
15915 This extracts the last occurrence of the cookie name <name> on a "Cookie"
15916 header line from the request, and returns its value as string. If no name is
15917 specified, the first cookie value is returned. When used with ACLs, all
15918 matching cookies are evaluated. Spaces around the name and the value are
15919 ignored as requested by the Cookie header specification (RFC6265). The cookie
15920 name is case-sensitive. Empty cookies are valid, so an empty cookie may very
15921 well return an empty value if it is present. Use the "found" match to detect
15922 presence. Use the res.cook() variant for response cookies sent by the server.
15923
15924 ACL derivatives :
15925 cook([<name>]) : exact string match
15926 cook_beg([<name>]) : prefix match
15927 cook_dir([<name>]) : subdir match
15928 cook_dom([<name>]) : domain match
15929 cook_end([<name>]) : suffix match
15930 cook_len([<name>]) : length match
15931 cook_reg([<name>]) : regex match
15932 cook_sub([<name>]) : substring match
Willy Tarreaud63335a2010-02-26 12:56:52 +010015933
Willy Tarreau74ca5042013-06-11 23:12:07 +020015934req.cook_cnt([<name>]) : integer
15935cook_cnt([<name>]) : integer (deprecated)
15936 Returns an integer value representing the number of occurrences of the cookie
15937 <name> in the request, or all cookies if <name> is not specified.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015938
Willy Tarreau74ca5042013-06-11 23:12:07 +020015939req.cook_val([<name>]) : integer
15940cook_val([<name>]) : integer (deprecated)
15941 This extracts the last occurrence of the cookie name <name> on a "Cookie"
15942 header line from the request, and converts its value to an integer which is
15943 returned. If no name is specified, the first cookie value is returned. When
15944 used in ACLs, all matching names are iterated over until a value matches.
Willy Tarreau0e698542011-09-16 08:32:32 +020015945
Willy Tarreau74ca5042013-06-11 23:12:07 +020015946cookie([<name>]) : string (deprecated)
15947 This extracts the last occurrence of the cookie name <name> on a "Cookie"
15948 header line from the request, or a "Set-Cookie" header from the response, and
15949 returns its value as a string. A typical use is to get multiple clients
15950 sharing a same profile use the same server. This can be similar to what
Willy Tarreau294d0f02015-08-10 19:40:12 +020015951 "appsession" did with the "request-learn" statement, but with support for
Willy Tarreau74ca5042013-06-11 23:12:07 +020015952 multi-peer synchronization and state keeping across restarts. If no name is
15953 specified, the first cookie value is returned. This fetch should not be used
15954 anymore and should be replaced by req.cook() or res.cook() instead as it
15955 ambiguously uses the direction based on the context where it is used.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015956
Willy Tarreau74ca5042013-06-11 23:12:07 +020015957hdr([<name>[,<occ>]]) : string
15958 This is equivalent to req.hdr() when used on requests, and to res.hdr() when
15959 used on responses. Please refer to these respective fetches for more details.
15960 In case of doubt about the fetch direction, please use the explicit ones.
15961 Note that contrary to the hdr() sample fetch method, the hdr_* ACL keywords
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030015962 unambiguously apply to the request headers.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015963
Willy Tarreau74ca5042013-06-11 23:12:07 +020015964req.fhdr(<name>[,<occ>]) : string
15965 This extracts the last occurrence of header <name> in an HTTP request. When
15966 used from an ACL, all occurrences are iterated over until a match is found.
15967 Optionally, a specific occurrence might be specified as a position number.
15968 Positive values indicate a position from the first occurrence, with 1 being
15969 the first one. Negative values indicate positions relative to the last one,
15970 with -1 being the last one. It differs from req.hdr() in that any commas
15971 present in the value are returned and are not used as delimiters. This is
15972 sometimes useful with headers such as User-Agent.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015973
Willy Tarreau74ca5042013-06-11 23:12:07 +020015974req.fhdr_cnt([<name>]) : integer
15975 Returns an integer value representing the number of occurrences of request
15976 header field name <name>, or the total number of header fields if <name> is
15977 not specified. Contrary to its req.hdr_cnt() cousin, this function returns
15978 the number of full line headers and does not stop on commas.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015979
Willy Tarreau74ca5042013-06-11 23:12:07 +020015980req.hdr([<name>[,<occ>]]) : string
15981 This extracts the last occurrence of header <name> in an HTTP request. When
15982 used from an ACL, all occurrences are iterated over until a match is found.
15983 Optionally, a specific occurrence might be specified as a position number.
15984 Positive values indicate a position from the first occurrence, with 1 being
15985 the first one. Negative values indicate positions relative to the last one,
15986 with -1 being the last one. A typical use is with the X-Forwarded-For header
15987 once converted to IP, associated with an IP stick-table. The function
15988 considers any comma as a delimiter for distinct values. If full-line headers
Lukas Tribus23953682017-04-28 13:24:30 +000015989 are desired instead, use req.fhdr(). Please carefully check RFC7231 to know
Willy Tarreau74ca5042013-06-11 23:12:07 +020015990 how certain headers are supposed to be parsed. Also, some of them are case
Davor Ocelice9ed2812017-12-25 17:49:28 +010015991 insensitive (e.g. Connection).
Willy Tarreaud63335a2010-02-26 12:56:52 +010015992
Willy Tarreau74ca5042013-06-11 23:12:07 +020015993 ACL derivatives :
15994 hdr([<name>[,<occ>]]) : exact string match
15995 hdr_beg([<name>[,<occ>]]) : prefix match
15996 hdr_dir([<name>[,<occ>]]) : subdir match
15997 hdr_dom([<name>[,<occ>]]) : domain match
15998 hdr_end([<name>[,<occ>]]) : suffix match
15999 hdr_len([<name>[,<occ>]]) : length match
16000 hdr_reg([<name>[,<occ>]]) : regex match
16001 hdr_sub([<name>[,<occ>]]) : substring match
16002
16003req.hdr_cnt([<name>]) : integer
16004hdr_cnt([<header>]) : integer (deprecated)
16005 Returns an integer value representing the number of occurrences of request
16006 header field name <name>, or the total number of header field values if
16007 <name> is not specified. It is important to remember that one header line may
16008 count as several headers if it has several values. The function considers any
16009 comma as a delimiter for distinct values. If full-line headers are desired
16010 instead, req.fhdr_cnt() should be used instead. With ACLs, it can be used to
16011 detect presence, absence or abuse of a specific header, as well as to block
16012 request smuggling attacks by rejecting requests which contain more than one
16013 of certain headers. See "req.hdr" for more information on header matching.
16014
16015req.hdr_ip([<name>[,<occ>]]) : ip
16016hdr_ip([<name>[,<occ>]]) : ip (deprecated)
16017 This extracts the last occurrence of header <name> in an HTTP request,
16018 converts it to an IPv4 or IPv6 address and returns this address. When used
16019 with ACLs, all occurrences are checked, and if <name> is omitted, every value
16020 of every header is checked. Optionally, a specific occurrence might be
16021 specified as a position number. Positive values indicate a position from the
Davor Ocelice9ed2812017-12-25 17:49:28 +010016022 first occurrence, with 1 being the first one. Negative values indicate
Willy Tarreau74ca5042013-06-11 23:12:07 +020016023 positions relative to the last one, with -1 being the last one. A typical use
16024 is with the X-Forwarded-For and X-Client-IP headers.
16025
16026req.hdr_val([<name>[,<occ>]]) : integer
16027hdr_val([<name>[,<occ>]]) : integer (deprecated)
16028 This extracts the last occurrence of header <name> in an HTTP request, and
16029 converts it to an integer value. When used with ACLs, all occurrences are
16030 checked, and if <name> is omitted, every value of every header is checked.
16031 Optionally, a specific occurrence might be specified as a position number.
16032 Positive values indicate a position from the first occurrence, with 1 being
16033 the first one. Negative values indicate positions relative to the last one,
16034 with -1 being the last one. A typical use is with the X-Forwarded-For header.
16035
Frédéric Lécailleec891192019-02-26 15:02:35 +010016036
16037
Willy Tarreau74ca5042013-06-11 23:12:07 +020016038http_auth(<userlist>) : boolean
16039 Returns a boolean indicating whether the authentication data received from
16040 the client match a username & password stored in the specified userlist. This
16041 fetch function is not really useful outside of ACLs. Currently only http
16042 basic auth is supported.
16043
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010016044http_auth_group(<userlist>) : string
16045 Returns a string corresponding to the user name found in the authentication
16046 data received from the client if both the user name and password are valid
16047 according to the specified userlist. The main purpose is to use it in ACLs
16048 where it is then checked whether the user belongs to any group within a list.
Willy Tarreau74ca5042013-06-11 23:12:07 +020016049 This fetch function is not really useful outside of ACLs. Currently only http
16050 basic auth is supported.
16051
16052 ACL derivatives :
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010016053 http_auth_group(<userlist>) : group ...
16054 Returns true when the user extracted from the request and whose password is
16055 valid according to the specified userlist belongs to at least one of the
16056 groups.
Willy Tarreau74ca5042013-06-11 23:12:07 +020016057
Christopher Fauleta4063562019-08-02 11:51:37 +020016058http_auth_pass : string
16059 Returns the user's password found in the authentication data received from
16060 the client, as supplied in the Authorization header. Not checks are
16061 performed by this sample fetch. Only Basic authentication is supported.
16062
16063http_auth_type : string
16064 Returns the authentication method found in the authentication data received from
16065 the client, as supplied in the Authorization header. Not checks are
16066 performed by this sample fetch. Only Basic authentication is supported.
16067
16068http_auth_user : string
16069 Returns the user name found in the authentication data received from the
16070 client, as supplied in the Authorization header. Not checks are performed by
16071 this sample fetch. Only Basic authentication is supported.
16072
Willy Tarreau74ca5042013-06-11 23:12:07 +020016073http_first_req : boolean
Willy Tarreau7f18e522010-10-22 20:04:13 +020016074 Returns true when the request being processed is the first one of the
16075 connection. This can be used to add or remove headers that may be missing
Willy Tarreau74ca5042013-06-11 23:12:07 +020016076 from some requests when a request is not the first one, or to help grouping
16077 requests in the logs.
Willy Tarreau7f18e522010-10-22 20:04:13 +020016078
Willy Tarreau74ca5042013-06-11 23:12:07 +020016079method : integer + string
16080 Returns an integer value corresponding to the method in the HTTP request. For
16081 example, "GET" equals 1 (check sources to establish the matching). Value 9
16082 means "other method" and may be converted to a string extracted from the
16083 stream. This should not be used directly as a sample, this is only meant to
16084 be used from ACLs, which transparently convert methods from patterns to these
16085 integer + string values. Some predefined ACL already check for most common
16086 methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016087
Willy Tarreau74ca5042013-06-11 23:12:07 +020016088 ACL derivatives :
16089 method : case insensitive method match
Willy Tarreau6a06a402007-07-15 20:15:28 +020016090
Willy Tarreau74ca5042013-06-11 23:12:07 +020016091 Example :
16092 # only accept GET and HEAD requests
16093 acl valid_method method GET HEAD
16094 http-request deny if ! valid_method
Willy Tarreau6a06a402007-07-15 20:15:28 +020016095
Willy Tarreau74ca5042013-06-11 23:12:07 +020016096path : string
16097 This extracts the request's URL path, which starts at the first slash and
16098 ends before the question mark (without the host part). A typical use is with
16099 prefetch-capable caches, and with portals which need to aggregate multiple
16100 information from databases and keep them in caches. Note that with outgoing
16101 caches, it would be wiser to use "url" instead. With ACLs, it's typically
Davor Ocelice9ed2812017-12-25 17:49:28 +010016102 used to match exact file names (e.g. "/login.php"), or directory parts using
Willy Tarreau74ca5042013-06-11 23:12:07 +020016103 the derivative forms. See also the "url" and "base" fetch methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016104
Willy Tarreau74ca5042013-06-11 23:12:07 +020016105 ACL derivatives :
16106 path : exact string match
16107 path_beg : prefix match
16108 path_dir : subdir match
16109 path_dom : domain match
16110 path_end : suffix match
16111 path_len : length match
16112 path_reg : regex match
16113 path_sub : substring match
Willy Tarreau6a06a402007-07-15 20:15:28 +020016114
Willy Tarreau49ad95c2015-01-19 15:06:26 +010016115query : string
16116 This extracts the request's query string, which starts after the first
16117 question mark. If no question mark is present, this fetch returns nothing. If
16118 a question mark is present but nothing follows, it returns an empty string.
16119 This means it's possible to easily know whether a query string is present
Tim Düsterhus4896c442016-11-29 02:15:19 +010016120 using the "found" matching method. This fetch is the complement of "path"
Willy Tarreau49ad95c2015-01-19 15:06:26 +010016121 which stops before the question mark.
16122
Willy Tarreaueb27ec72015-02-20 13:55:29 +010016123req.hdr_names([<delim>]) : string
16124 This builds a string made from the concatenation of all header names as they
16125 appear in the request when the rule is evaluated. The default delimiter is
16126 the comma (',') but it may be overridden as an optional argument <delim>. In
16127 this case, only the first character of <delim> is considered.
16128
Willy Tarreau74ca5042013-06-11 23:12:07 +020016129req.ver : string
16130req_ver : string (deprecated)
16131 Returns the version string from the HTTP request, for example "1.1". This can
16132 be useful for logs, but is mostly there for ACL. Some predefined ACL already
16133 check for versions 1.0 and 1.1.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016134
Willy Tarreau74ca5042013-06-11 23:12:07 +020016135 ACL derivatives :
16136 req_ver : exact string match
Willy Tarreau0e698542011-09-16 08:32:32 +020016137
Willy Tarreau74ca5042013-06-11 23:12:07 +020016138res.comp : boolean
16139 Returns the boolean "true" value if the response has been compressed by
16140 HAProxy, otherwise returns boolean "false". This may be used to add
16141 information in the logs.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016142
Willy Tarreau74ca5042013-06-11 23:12:07 +020016143res.comp_algo : string
16144 Returns a string containing the name of the algorithm used if the response
16145 was compressed by HAProxy, for example : "deflate". This may be used to add
16146 some information in the logs.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016147
Willy Tarreau74ca5042013-06-11 23:12:07 +020016148res.cook([<name>]) : string
16149scook([<name>]) : string (deprecated)
16150 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
16151 header line from the response, and returns its value as string. If no name is
16152 specified, the first cookie value is returned.
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020016153
Willy Tarreau74ca5042013-06-11 23:12:07 +020016154 ACL derivatives :
16155 scook([<name>] : exact string match
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020016156
Willy Tarreau74ca5042013-06-11 23:12:07 +020016157res.cook_cnt([<name>]) : integer
16158scook_cnt([<name>]) : integer (deprecated)
16159 Returns an integer value representing the number of occurrences of the cookie
16160 <name> in the response, or all cookies if <name> is not specified. This is
16161 mostly useful when combined with ACLs to detect suspicious responses.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016162
Willy Tarreau74ca5042013-06-11 23:12:07 +020016163res.cook_val([<name>]) : integer
16164scook_val([<name>]) : integer (deprecated)
16165 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
16166 header line from the response, and converts its value to an integer which is
16167 returned. If no name is specified, the first cookie value is returned.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016168
Willy Tarreau74ca5042013-06-11 23:12:07 +020016169res.fhdr([<name>[,<occ>]]) : string
16170 This extracts the last occurrence of header <name> in an HTTP response, or of
16171 the last header if no <name> is specified. Optionally, a specific occurrence
16172 might be specified as a position number. Positive values indicate a position
16173 from the first occurrence, with 1 being the first one. Negative values
16174 indicate positions relative to the last one, with -1 being the last one. It
16175 differs from res.hdr() in that any commas present in the value are returned
16176 and are not used as delimiters. If this is not desired, the res.hdr() fetch
16177 should be used instead. This is sometimes useful with headers such as Date or
16178 Expires.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016179
Willy Tarreau74ca5042013-06-11 23:12:07 +020016180res.fhdr_cnt([<name>]) : integer
16181 Returns an integer value representing the number of occurrences of response
16182 header field name <name>, or the total number of header fields if <name> is
16183 not specified. Contrary to its res.hdr_cnt() cousin, this function returns
16184 the number of full line headers and does not stop on commas. If this is not
16185 desired, the res.hdr_cnt() fetch should be used instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016186
Willy Tarreau74ca5042013-06-11 23:12:07 +020016187res.hdr([<name>[,<occ>]]) : string
16188shdr([<name>[,<occ>]]) : string (deprecated)
16189 This extracts the last occurrence of header <name> in an HTTP response, or of
16190 the last header if no <name> is specified. Optionally, a specific occurrence
16191 might be specified as a position number. Positive values indicate a position
16192 from the first occurrence, with 1 being the first one. Negative values
16193 indicate positions relative to the last one, with -1 being the last one. This
16194 can be useful to learn some data into a stick-table. The function considers
16195 any comma as a delimiter for distinct values. If this is not desired, the
16196 res.fhdr() fetch should be used instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016197
Willy Tarreau74ca5042013-06-11 23:12:07 +020016198 ACL derivatives :
16199 shdr([<name>[,<occ>]]) : exact string match
16200 shdr_beg([<name>[,<occ>]]) : prefix match
16201 shdr_dir([<name>[,<occ>]]) : subdir match
16202 shdr_dom([<name>[,<occ>]]) : domain match
16203 shdr_end([<name>[,<occ>]]) : suffix match
16204 shdr_len([<name>[,<occ>]]) : length match
16205 shdr_reg([<name>[,<occ>]]) : regex match
16206 shdr_sub([<name>[,<occ>]]) : substring match
16207
16208res.hdr_cnt([<name>]) : integer
16209shdr_cnt([<name>]) : integer (deprecated)
16210 Returns an integer value representing the number of occurrences of response
16211 header field name <name>, or the total number of header fields if <name> is
16212 not specified. The function considers any comma as a delimiter for distinct
16213 values. If this is not desired, the res.fhdr_cnt() fetch should be used
16214 instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016215
Willy Tarreau74ca5042013-06-11 23:12:07 +020016216res.hdr_ip([<name>[,<occ>]]) : ip
16217shdr_ip([<name>[,<occ>]]) : ip (deprecated)
16218 This extracts the last occurrence of header <name> in an HTTP response,
16219 convert it to an IPv4 or IPv6 address and returns this address. Optionally, a
16220 specific occurrence might be specified as a position number. Positive values
16221 indicate a position from the first occurrence, with 1 being the first one.
16222 Negative values indicate positions relative to the last one, with -1 being
16223 the last one. This can be useful to learn some data into a stick table.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016224
Willy Tarreaueb27ec72015-02-20 13:55:29 +010016225res.hdr_names([<delim>]) : string
16226 This builds a string made from the concatenation of all header names as they
16227 appear in the response when the rule is evaluated. The default delimiter is
16228 the comma (',') but it may be overridden as an optional argument <delim>. In
16229 this case, only the first character of <delim> is considered.
16230
Willy Tarreau74ca5042013-06-11 23:12:07 +020016231res.hdr_val([<name>[,<occ>]]) : integer
16232shdr_val([<name>[,<occ>]]) : integer (deprecated)
16233 This extracts the last occurrence of header <name> in an HTTP response, and
16234 converts it to an integer value. Optionally, a specific occurrence might be
16235 specified as a position number. Positive values indicate a position from the
16236 first occurrence, with 1 being the first one. Negative values indicate
16237 positions relative to the last one, with -1 being the last one. This can be
16238 useful to learn some data into a stick table.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010016239
Willy Tarreau74ca5042013-06-11 23:12:07 +020016240res.ver : string
16241resp_ver : string (deprecated)
16242 Returns the version string from the HTTP response, for example "1.1". This
16243 can be useful for logs, but is mostly there for ACL.
Willy Tarreau0e698542011-09-16 08:32:32 +020016244
Willy Tarreau74ca5042013-06-11 23:12:07 +020016245 ACL derivatives :
16246 resp_ver : exact string match
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010016247
Willy Tarreau74ca5042013-06-11 23:12:07 +020016248set-cookie([<name>]) : string (deprecated)
16249 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
16250 header line from the response and uses the corresponding value to match. This
Willy Tarreau294d0f02015-08-10 19:40:12 +020016251 can be comparable to what "appsession" did with default options, but with
Willy Tarreau74ca5042013-06-11 23:12:07 +020016252 support for multi-peer synchronization and state keeping across restarts.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010016253
Willy Tarreau74ca5042013-06-11 23:12:07 +020016254 This fetch function is deprecated and has been superseded by the "res.cook"
16255 fetch. This keyword will disappear soon.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010016256
Willy Tarreau74ca5042013-06-11 23:12:07 +020016257status : integer
16258 Returns an integer containing the HTTP status code in the HTTP response, for
16259 example, 302. It is mostly used within ACLs and integer ranges, for example,
16260 to remove any Location header if the response is not a 3xx.
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016261
Thierry Fournier0e00dca2016-04-07 15:47:40 +020016262unique-id : string
16263 Returns the unique-id attached to the request. The directive
16264 "unique-id-format" must be set. If it is not set, the unique-id sample fetch
16265 fails. Note that the unique-id is usually used with HTTP requests, however this
16266 sample fetch can be used with other protocols. Obviously, if it is used with
16267 other protocols than HTTP, the unique-id-format directive must not contain
16268 HTTP parts. See: unique-id-format and unique-id-header
16269
Willy Tarreau74ca5042013-06-11 23:12:07 +020016270url : string
16271 This extracts the request's URL as presented in the request. A typical use is
16272 with prefetch-capable caches, and with portals which need to aggregate
16273 multiple information from databases and keep them in caches. With ACLs, using
16274 "path" is preferred over using "url", because clients may send a full URL as
16275 is normally done with proxies. The only real use is to match "*" which does
16276 not match in "path", and for which there is already a predefined ACL. See
16277 also "path" and "base".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016278
Willy Tarreau74ca5042013-06-11 23:12:07 +020016279 ACL derivatives :
16280 url : exact string match
16281 url_beg : prefix match
16282 url_dir : subdir match
16283 url_dom : domain match
16284 url_end : suffix match
16285 url_len : length match
16286 url_reg : regex match
16287 url_sub : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016288
Willy Tarreau74ca5042013-06-11 23:12:07 +020016289url_ip : ip
16290 This extracts the IP address from the request's URL when the host part is
16291 presented as an IP address. Its use is very limited. For instance, a
16292 monitoring system might use this field as an alternative for the source IP in
16293 order to test what path a given source address would follow, or to force an
16294 entry in a table for a given source address. With ACLs it can be used to
16295 restrict access to certain systems through a proxy, for example when combined
16296 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016297
Willy Tarreau74ca5042013-06-11 23:12:07 +020016298url_port : integer
16299 This extracts the port part from the request's URL. Note that if the port is
16300 not specified in the request, port 80 is assumed. With ACLs it can be used to
16301 restrict access to certain systems through a proxy, for example when combined
16302 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016303
Willy Tarreau1ede1da2015-05-07 16:06:18 +020016304urlp([<name>[,<delim>]]) : string
16305url_param([<name>[,<delim>]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020016306 This extracts the first occurrence of the parameter <name> in the query
16307 string, which begins after either '?' or <delim>, and which ends before '&',
Willy Tarreau1ede1da2015-05-07 16:06:18 +020016308 ';' or <delim>. The parameter name is case-sensitive. If no name is given,
16309 any parameter will match, and the first one will be returned. The result is
16310 a string corresponding to the value of the parameter <name> as presented in
16311 the request (no URL decoding is performed). This can be used for session
Willy Tarreau74ca5042013-06-11 23:12:07 +020016312 stickiness based on a client ID, to extract an application cookie passed as a
16313 URL parameter, or in ACLs to apply some checks. Note that the ACL version of
Willy Tarreau1ede1da2015-05-07 16:06:18 +020016314 this fetch iterates over multiple parameters and will iteratively report all
16315 parameters values if no name is given
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016316
Willy Tarreau74ca5042013-06-11 23:12:07 +020016317 ACL derivatives :
16318 urlp(<name>[,<delim>]) : exact string match
16319 urlp_beg(<name>[,<delim>]) : prefix match
16320 urlp_dir(<name>[,<delim>]) : subdir match
16321 urlp_dom(<name>[,<delim>]) : domain match
16322 urlp_end(<name>[,<delim>]) : suffix match
16323 urlp_len(<name>[,<delim>]) : length match
16324 urlp_reg(<name>[,<delim>]) : regex match
16325 urlp_sub(<name>[,<delim>]) : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016326
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016327
Willy Tarreau74ca5042013-06-11 23:12:07 +020016328 Example :
16329 # match http://example.com/foo?PHPSESSIONID=some_id
16330 stick on urlp(PHPSESSIONID)
16331 # match http://example.com/foo;JSESSIONID=some_id
16332 stick on urlp(JSESSIONID,;)
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016333
Jarno Huuskonen676f6222017-03-30 09:19:45 +030016334urlp_val([<name>[,<delim>]]) : integer
Willy Tarreau74ca5042013-06-11 23:12:07 +020016335 See "urlp" above. This one extracts the URL parameter <name> in the request
16336 and converts it to an integer value. This can be used for session stickiness
16337 based on a user ID for example, or with ACLs to match a page number or price.
Willy Tarreaua9fddca2012-07-31 07:51:48 +020016338
Dragan Dosen0070cd52016-06-16 12:19:49 +020016339url32 : integer
16340 This returns a 32-bit hash of the value obtained by concatenating the first
16341 Host header and the whole URL including parameters (not only the path part of
16342 the request, as in the "base32" fetch above). This is useful to track per-URL
16343 activity. A shorter hash is stored, saving a lot of memory. The output type
16344 is an unsigned integer.
16345
16346url32+src : binary
16347 This returns the concatenation of the "url32" fetch and the "src" fetch. The
16348 resulting type is of type binary, with a size of 8 or 20 bytes depending on
16349 the source address family. This can be used to track per-IP, per-URL counters.
16350
Willy Tarreau198a7442008-01-17 12:05:32 +010016351
Willy Tarreau74ca5042013-06-11 23:12:07 +0200163527.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016353---------------------
Willy Tarreauced27012008-01-17 20:35:34 +010016354
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016355Some predefined ACLs are hard-coded so that they do not have to be declared in
16356every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +020016357order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +010016358
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016359ACL name Equivalent to Usage
16360---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016361FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +020016362HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016363HTTP_1.0 req_ver 1.0 match HTTP version 1.0
16364HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +010016365HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
16366HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
16367HTTP_URL_SLASH url_beg / match URL beginning with "/"
16368HTTP_URL_STAR url * match URL equal to "*"
16369LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016370METH_CONNECT method CONNECT match HTTP CONNECT method
Daniel Schneller9ff96c72016-04-11 17:45:29 +020016371METH_DELETE method DELETE match HTTP DELETE method
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016372METH_GET method GET HEAD match HTTP GET or HEAD method
16373METH_HEAD method HEAD match HTTP HEAD method
16374METH_OPTIONS method OPTIONS match HTTP OPTIONS method
16375METH_POST method POST match HTTP POST method
Daniel Schneller9ff96c72016-04-11 17:45:29 +020016376METH_PUT method PUT match HTTP PUT method
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016377METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +020016378RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016379REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +010016380TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016381WAIT_END wait_end wait for end of content analysis
16382---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +010016383
Willy Tarreaub937b7e2010-01-12 15:27:54 +010016384
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200163858. Logging
16386----------
Willy Tarreau844e3c52008-01-11 16:28:18 +010016387
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016388One of HAProxy's strong points certainly lies is its precise logs. It probably
16389provides the finest level of information available for such a product, which is
16390very important for troubleshooting complex environments. Standard information
16391provided in logs include client ports, TCP/HTTP state timers, precise session
16392state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010016393to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016394headers.
16395
16396In order to improve administrators reactivity, it offers a great transparency
16397about encountered problems, both internal and external, and it is possible to
16398send logs to different sources at the same time with different level filters :
16399
16400 - global process-level logs (system errors, start/stop, etc..)
16401 - per-instance system and internal errors (lack of resource, bugs, ...)
16402 - per-instance external troubles (servers up/down, max connections)
16403 - per-instance activity (client connections), either at the establishment or
16404 at the termination.
Davor Ocelice9ed2812017-12-25 17:49:28 +010016405 - per-request control of log-level, e.g.
Jim Freeman9e8714b2015-05-26 09:16:34 -060016406 http-request set-log-level silent if sensitive_request
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016407
16408The ability to distribute different levels of logs to different log servers
16409allow several production teams to interact and to fix their problems as soon
16410as possible. For example, the system team might monitor system-wide errors,
16411while the application team might be monitoring the up/down for their servers in
16412real time, and the security team might analyze the activity logs with one hour
16413delay.
16414
16415
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200164168.1. Log levels
16417---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016418
Simon Hormandf791f52011-05-29 15:01:10 +090016419TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016420source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +090016421HTTP request, HTTP return code, number of bytes transmitted, conditions
16422in which the session ended, and even exchanged cookies values. For example
16423track a particular user's problems. All messages may be sent to up to two
16424syslog servers. Check the "log" keyword in section 4.2 for more information
16425about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016426
16427
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200164288.2. Log formats
16429----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016430
William Lallemand48940402012-01-30 16:47:22 +010016431HAProxy supports 5 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +090016432and will be detailed in the following sections. A few of them may vary
16433slightly with the configuration, due to indicators specific to certain
16434options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016435
16436 - the default format, which is very basic and very rarely used. It only
16437 provides very basic information about the incoming connection at the moment
16438 it is accepted : source IP:port, destination IP:port, and frontend-name.
16439 This mode will eventually disappear so it will not be described to great
16440 extents.
16441
16442 - the TCP format, which is more advanced. This format is enabled when "option
16443 tcplog" is set on the frontend. HAProxy will then usually wait for the
16444 connection to terminate before logging. This format provides much richer
16445 information, such as timers, connection counts, queue size, etc... This
16446 format is recommended for pure TCP proxies.
16447
16448 - the HTTP format, which is the most advanced for HTTP proxying. This format
16449 is enabled when "option httplog" is set on the frontend. It provides the
16450 same information as the TCP format with some HTTP-specific fields such as
16451 the request, the status code, and captures of headers and cookies. This
16452 format is recommended for HTTP proxies.
16453
Emeric Brun3a058f32009-06-30 18:26:00 +020016454 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
16455 fields arranged in the same order as the CLF format. In this mode, all
16456 timers, captures, flags, etc... appear one per field after the end of the
16457 common fields, in the same order they appear in the standard HTTP format.
16458
William Lallemand48940402012-01-30 16:47:22 +010016459 - the custom log format, allows you to make your own log line.
16460
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016461Next sections will go deeper into details for each of these formats. Format
16462specification will be performed on a "field" basis. Unless stated otherwise, a
16463field is a portion of text delimited by any number of spaces. Since syslog
16464servers are susceptible of inserting fields at the beginning of a line, it is
16465always assumed that the first field is the one containing the process name and
16466identifier.
16467
16468Note : Since log lines may be quite long, the log examples in sections below
16469 might be broken into multiple lines. The example log lines will be
16470 prefixed with 3 closing angle brackets ('>>>') and each time a log is
16471 broken into multiple lines, each non-final line will end with a
16472 backslash ('\') and the next line will start indented by two characters.
16473
16474
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200164758.2.1. Default log format
16476-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016477
16478This format is used when no specific option is set. The log is emitted as soon
16479as the connection is accepted. One should note that this currently is the only
16480format which logs the request's destination IP and ports.
16481
16482 Example :
16483 listen www
16484 mode http
16485 log global
16486 server srv1 127.0.0.1:8000
16487
16488 >>> Feb 6 12:12:09 localhost \
16489 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
16490 (www/HTTP)
16491
16492 Field Format Extract from the example above
16493 1 process_name '[' pid ']:' haproxy[14385]:
16494 2 'Connect from' Connect from
16495 3 source_ip ':' source_port 10.0.1.2:33312
16496 4 'to' to
16497 5 destination_ip ':' destination_port 10.0.3.31:8012
16498 6 '(' frontend_name '/' mode ')' (www/HTTP)
16499
16500Detailed fields description :
16501 - "source_ip" is the IP address of the client which initiated the connection.
16502 - "source_port" is the TCP port of the client which initiated the connection.
16503 - "destination_ip" is the IP address the client connected to.
16504 - "destination_port" is the TCP port the client connected to.
16505 - "frontend_name" is the name of the frontend (or listener) which received
16506 and processed the connection.
16507 - "mode is the mode the frontend is operating (TCP or HTTP).
16508
Willy Tarreauceb24bc2010-11-09 12:46:41 +010016509In case of a UNIX socket, the source and destination addresses are marked as
16510"unix:" and the ports reflect the internal ID of the socket which accepted the
16511connection (the same ID as reported in the stats).
16512
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016513It is advised not to use this deprecated format for newer installations as it
16514will eventually disappear.
16515
16516
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200165178.2.2. TCP log format
16518---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016519
16520The TCP format is used when "option tcplog" is specified in the frontend, and
16521is the recommended format for pure TCP proxies. It provides a lot of precious
16522information for troubleshooting. Since this format includes timers and byte
16523counts, the log is normally emitted at the end of the session. It can be
16524emitted earlier if "option logasap" is specified, which makes sense in most
16525environments with long sessions such as remote terminals. Sessions which match
16526the "monitor" rules are never logged. It is also possible not to emit logs for
16527sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020016528specifying "option dontlognull" in the frontend. Successful connections will
16529not be logged if "option dontlog-normal" is specified in the frontend. A few
16530fields may slightly vary depending on some configuration options, those are
16531marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016532
16533 Example :
16534 frontend fnt
16535 mode tcp
16536 option tcplog
16537 log global
16538 default_backend bck
16539
16540 backend bck
16541 server srv1 127.0.0.1:8000
16542
16543 >>> Feb 6 12:12:56 localhost \
16544 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
16545 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
16546
16547 Field Format Extract from the example above
16548 1 process_name '[' pid ']:' haproxy[14387]:
16549 2 client_ip ':' client_port 10.0.1.2:33313
16550 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
16551 4 frontend_name fnt
16552 5 backend_name '/' server_name bck/srv1
16553 6 Tw '/' Tc '/' Tt* 0/0/5007
16554 7 bytes_read* 212
16555 8 termination_state --
16556 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
16557 10 srv_queue '/' backend_queue 0/0
16558
16559Detailed fields description :
16560 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010016561 connection to haproxy. If the connection was accepted on a UNIX socket
16562 instead, the IP address would be replaced with the word "unix". Note that
16563 when the connection is accepted on a socket configured with "accept-proxy"
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010016564 and the PROXY protocol is correctly used, or with a "accept-netscaler-cip"
Davor Ocelice9ed2812017-12-25 17:49:28 +010016565 and the NetScaler Client IP insertion protocol is correctly used, then the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010016566 logs will reflect the forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016567
16568 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010016569 If the connection was accepted on a UNIX socket instead, the port would be
16570 replaced with the ID of the accepting socket, which is also reported in the
16571 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016572
16573 - "accept_date" is the exact date when the connection was received by haproxy
16574 (which might be very slightly different from the date observed on the
16575 network if there was some queuing in the system's backlog). This is usually
Willy Tarreau590a0512018-09-05 11:56:48 +020016576 the same date which may appear in any upstream firewall's log. When used in
16577 HTTP mode, the accept_date field will be reset to the first moment the
16578 connection is ready to receive a new request (end of previous response for
16579 HTTP/1, immediately after previous request for HTTP/2).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016580
16581 - "frontend_name" is the name of the frontend (or listener) which received
16582 and processed the connection.
16583
16584 - "backend_name" is the name of the backend (or listener) which was selected
16585 to manage the connection to the server. This will be the same as the
16586 frontend if no switching rule has been applied, which is common for TCP
16587 applications.
16588
16589 - "server_name" is the name of the last server to which the connection was
16590 sent, which might differ from the first one if there were connection errors
16591 and a redispatch occurred. Note that this server belongs to the backend
16592 which processed the request. If the connection was aborted before reaching
16593 a server, "<NOSRV>" is indicated instead of a server name.
16594
16595 - "Tw" is the total time in milliseconds spent waiting in the various queues.
16596 It can be "-1" if the connection was aborted before reaching the queue.
16597 See "Timers" below for more details.
16598
16599 - "Tc" is the total time in milliseconds spent waiting for the connection to
16600 establish to the final server, including retries. It can be "-1" if the
16601 connection was aborted before a connection could be established. See
16602 "Timers" below for more details.
16603
16604 - "Tt" is the total time in milliseconds elapsed between the accept and the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016605 last close. It covers all possible processing. There is one exception, if
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016606 "option logasap" was specified, then the time counting stops at the moment
16607 the log is emitted. In this case, a '+' sign is prepended before the value,
16608 indicating that the final one will be larger. See "Timers" below for more
16609 details.
16610
16611 - "bytes_read" is the total number of bytes transmitted from the server to
16612 the client when the log is emitted. If "option logasap" is specified, the
16613 this value will be prefixed with a '+' sign indicating that the final one
16614 may be larger. Please note that this value is a 64-bit counter, so log
16615 analysis tools must be able to handle it without overflowing.
16616
16617 - "termination_state" is the condition the session was in when the session
16618 ended. This indicates the session state, which side caused the end of
16619 session to happen, and for what reason (timeout, error, ...). The normal
16620 flags should be "--", indicating the session was closed by either end with
16621 no data remaining in buffers. See below "Session state at disconnection"
16622 for more details.
16623
16624 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040016625 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016626 limits have been reached. For instance, if actconn is close to 512 when
16627 multiple connection errors occur, chances are high that the system limits
16628 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016629 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016630
16631 - "feconn" is the total number of concurrent connections on the frontend when
16632 the session was logged. It is useful to estimate the amount of resource
16633 required to sustain high loads, and to detect when the frontend's "maxconn"
16634 has been reached. Most often when this value increases by huge jumps, it is
16635 because there is congestion on the backend servers, but sometimes it can be
16636 caused by a denial of service attack.
16637
16638 - "beconn" is the total number of concurrent connections handled by the
16639 backend when the session was logged. It includes the total number of
16640 concurrent connections active on servers as well as the number of
16641 connections pending in queues. It is useful to estimate the amount of
16642 additional servers needed to support high loads for a given application.
16643 Most often when this value increases by huge jumps, it is because there is
16644 congestion on the backend servers, but sometimes it can be caused by a
16645 denial of service attack.
16646
16647 - "srv_conn" is the total number of concurrent connections still active on
16648 the server when the session was logged. It can never exceed the server's
16649 configured "maxconn" parameter. If this value is very often close or equal
16650 to the server's "maxconn", it means that traffic regulation is involved a
16651 lot, meaning that either the server's maxconn value is too low, or that
16652 there aren't enough servers to process the load with an optimal response
16653 time. When only one of the server's "srv_conn" is high, it usually means
16654 that this server has some trouble causing the connections to take longer to
16655 be processed than on other servers.
16656
16657 - "retries" is the number of connection retries experienced by this session
16658 when trying to connect to the server. It must normally be zero, unless a
16659 server is being stopped at the same moment the connection was attempted.
16660 Frequent retries generally indicate either a network problem between
16661 haproxy and the server, or a misconfigured system backlog on the server
16662 preventing new connections from being queued. This field may optionally be
16663 prefixed with a '+' sign, indicating that the session has experienced a
16664 redispatch after the maximal retry count has been reached on the initial
16665 server. In this case, the server name appearing in the log is the one the
16666 connection was redispatched to, and not the first one, though both may
16667 sometimes be the same in case of hashing for instance. So as a general rule
16668 of thumb, when a '+' is present in front of the retry count, this count
16669 should not be attributed to the logged server.
16670
16671 - "srv_queue" is the total number of requests which were processed before
16672 this one in the server queue. It is zero when the request has not gone
16673 through the server queue. It makes it possible to estimate the approximate
16674 server's response time by dividing the time spent in queue by the number of
16675 requests in the queue. It is worth noting that if a session experiences a
16676 redispatch and passes through two server queues, their positions will be
Davor Ocelice9ed2812017-12-25 17:49:28 +010016677 cumulative. A request should not pass through both the server queue and the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016678 backend queue unless a redispatch occurs.
16679
16680 - "backend_queue" is the total number of requests which were processed before
16681 this one in the backend's global queue. It is zero when the request has not
16682 gone through the global queue. It makes it possible to estimate the average
16683 queue length, which easily translates into a number of missing servers when
16684 divided by a server's "maxconn" parameter. It is worth noting that if a
16685 session experiences a redispatch, it may pass twice in the backend's queue,
Davor Ocelice9ed2812017-12-25 17:49:28 +010016686 and then both positions will be cumulative. A request should not pass
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016687 through both the server queue and the backend queue unless a redispatch
16688 occurs.
16689
16690
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200166918.2.3. HTTP log format
16692----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016693
16694The HTTP format is the most complete and the best suited for HTTP proxies. It
16695is enabled by when "option httplog" is specified in the frontend. It provides
16696the same level of information as the TCP format with additional features which
16697are specific to the HTTP protocol. Just like the TCP format, the log is usually
16698emitted at the end of the session, unless "option logasap" is specified, which
16699generally only makes sense for download sites. A session which matches the
16700"monitor" rules will never logged. It is also possible not to log sessions for
16701which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020016702frontend. Successful connections will not be logged if "option dontlog-normal"
16703is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016704
16705Most fields are shared with the TCP log, some being different. A few fields may
16706slightly vary depending on some configuration options. Those ones are marked
16707with a star ('*') after the field name below.
16708
16709 Example :
16710 frontend http-in
16711 mode http
16712 option httplog
16713 log global
16714 default_backend bck
16715
16716 backend static
16717 server srv1 127.0.0.1:8000
16718
16719 >>> Feb 6 12:14:14 localhost \
16720 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
16721 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 +010016722 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016723
16724 Field Format Extract from the example above
16725 1 process_name '[' pid ']:' haproxy[14389]:
16726 2 client_ip ':' client_port 10.0.1.2:33317
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016727 3 '[' request_date ']' [06/Feb/2009:12:14:14.655]
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016728 4 frontend_name http-in
16729 5 backend_name '/' server_name static/srv1
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016730 6 TR '/' Tw '/' Tc '/' Tr '/' Ta* 10/0/30/69/109
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016731 7 status_code 200
16732 8 bytes_read* 2750
16733 9 captured_request_cookie -
16734 10 captured_response_cookie -
16735 11 termination_state ----
16736 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
16737 13 srv_queue '/' backend_queue 0/0
16738 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
16739 15 '{' captured_response_headers* '}' {}
16740 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +010016741
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016742Detailed fields description :
16743 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010016744 connection to haproxy. If the connection was accepted on a UNIX socket
16745 instead, the IP address would be replaced with the word "unix". Note that
16746 when the connection is accepted on a socket configured with "accept-proxy"
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010016747 and the PROXY protocol is correctly used, or with a "accept-netscaler-cip"
Davor Ocelice9ed2812017-12-25 17:49:28 +010016748 and the NetScaler Client IP insertion protocol is correctly used, then the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010016749 logs will reflect the forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016750
16751 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010016752 If the connection was accepted on a UNIX socket instead, the port would be
16753 replaced with the ID of the accepting socket, which is also reported in the
16754 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016755
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016756 - "request_date" is the exact date when the first byte of the HTTP request
16757 was received by haproxy (log field %tr).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016758
16759 - "frontend_name" is the name of the frontend (or listener) which received
16760 and processed the connection.
16761
16762 - "backend_name" is the name of the backend (or listener) which was selected
16763 to manage the connection to the server. This will be the same as the
16764 frontend if no switching rule has been applied.
16765
16766 - "server_name" is the name of the last server to which the connection was
16767 sent, which might differ from the first one if there were connection errors
16768 and a redispatch occurred. Note that this server belongs to the backend
16769 which processed the request. If the request was aborted before reaching a
16770 server, "<NOSRV>" is indicated instead of a server name. If the request was
16771 intercepted by the stats subsystem, "<STATS>" is indicated instead.
16772
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016773 - "TR" is the total time in milliseconds spent waiting for a full HTTP
16774 request from the client (not counting body) after the first byte was
16775 received. It can be "-1" if the connection was aborted before a complete
John Roeslerfb2fce12019-07-10 15:45:51 -050016776 request could be received or a bad request was received. It should
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016777 always be very small because a request generally fits in one single packet.
16778 Large times here generally indicate network issues between the client and
Willy Tarreau590a0512018-09-05 11:56:48 +020016779 haproxy or requests being typed by hand. See section 8.4 "Timing Events"
16780 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016781
16782 - "Tw" is the total time in milliseconds spent waiting in the various queues.
16783 It can be "-1" if the connection was aborted before reaching the queue.
Willy Tarreau590a0512018-09-05 11:56:48 +020016784 See section 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016785
16786 - "Tc" is the total time in milliseconds spent waiting for the connection to
16787 establish to the final server, including retries. It can be "-1" if the
Willy Tarreau590a0512018-09-05 11:56:48 +020016788 request was aborted before a connection could be established. See section
16789 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016790
16791 - "Tr" is the total time in milliseconds spent waiting for the server to send
16792 a full HTTP response, not counting data. It can be "-1" if the request was
16793 aborted before a complete response could be received. It generally matches
16794 the server's processing time for the request, though it may be altered by
16795 the amount of data sent by the client to the server. Large times here on
Willy Tarreau590a0512018-09-05 11:56:48 +020016796 "GET" requests generally indicate an overloaded server. See section 8.4
16797 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016798
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016799 - "Ta" is the time the request remained active in haproxy, which is the total
16800 time in milliseconds elapsed between the first byte of the request was
16801 received and the last byte of response was sent. It covers all possible
16802 processing except the handshake (see Th) and idle time (see Ti). There is
16803 one exception, if "option logasap" was specified, then the time counting
16804 stops at the moment the log is emitted. In this case, a '+' sign is
16805 prepended before the value, indicating that the final one will be larger.
Willy Tarreau590a0512018-09-05 11:56:48 +020016806 See section 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016807
16808 - "status_code" is the HTTP status code returned to the client. This status
16809 is generally set by the server, but it might also be set by haproxy when
16810 the server cannot be reached or when its response is blocked by haproxy.
16811
16812 - "bytes_read" is the total number of bytes transmitted to the client when
16813 the log is emitted. This does include HTTP headers. If "option logasap" is
John Roeslerfb2fce12019-07-10 15:45:51 -050016814 specified, this value will be prefixed with a '+' sign indicating that
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016815 the final one may be larger. Please note that this value is a 64-bit
16816 counter, so log analysis tools must be able to handle it without
16817 overflowing.
16818
16819 - "captured_request_cookie" is an optional "name=value" entry indicating that
16820 the client had this cookie in the request. The cookie name and its maximum
16821 length are defined by the "capture cookie" statement in the frontend
16822 configuration. The field is a single dash ('-') when the option is not
16823 set. Only one cookie may be captured, it is generally used to track session
16824 ID exchanges between a client and a server to detect session crossing
16825 between clients due to application bugs. For more details, please consult
16826 the section "Capturing HTTP headers and cookies" below.
16827
16828 - "captured_response_cookie" is an optional "name=value" entry indicating
16829 that the server has returned a cookie with its response. The cookie name
16830 and its maximum length are defined by the "capture cookie" statement in the
16831 frontend configuration. The field is a single dash ('-') when the option is
16832 not set. Only one cookie may be captured, it is generally used to track
16833 session ID exchanges between a client and a server to detect session
16834 crossing between clients due to application bugs. For more details, please
16835 consult the section "Capturing HTTP headers and cookies" below.
16836
16837 - "termination_state" is the condition the session was in when the session
16838 ended. This indicates the session state, which side caused the end of
16839 session to happen, for what reason (timeout, error, ...), just like in TCP
16840 logs, and information about persistence operations on cookies in the last
16841 two characters. The normal flags should begin with "--", indicating the
16842 session was closed by either end with no data remaining in buffers. See
16843 below "Session state at disconnection" for more details.
16844
16845 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040016846 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016847 limits have been reached. For instance, if actconn is close to 512 or 1024
16848 when multiple connection errors occur, chances are high that the system
16849 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016850 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016851 system.
16852
16853 - "feconn" is the total number of concurrent connections on the frontend when
16854 the session was logged. It is useful to estimate the amount of resource
16855 required to sustain high loads, and to detect when the frontend's "maxconn"
16856 has been reached. Most often when this value increases by huge jumps, it is
16857 because there is congestion on the backend servers, but sometimes it can be
16858 caused by a denial of service attack.
16859
16860 - "beconn" is the total number of concurrent connections handled by the
16861 backend when the session was logged. It includes the total number of
16862 concurrent connections active on servers as well as the number of
16863 connections pending in queues. It is useful to estimate the amount of
16864 additional servers needed to support high loads for a given application.
16865 Most often when this value increases by huge jumps, it is because there is
16866 congestion on the backend servers, but sometimes it can be caused by a
16867 denial of service attack.
16868
16869 - "srv_conn" is the total number of concurrent connections still active on
16870 the server when the session was logged. It can never exceed the server's
16871 configured "maxconn" parameter. If this value is very often close or equal
16872 to the server's "maxconn", it means that traffic regulation is involved a
16873 lot, meaning that either the server's maxconn value is too low, or that
16874 there aren't enough servers to process the load with an optimal response
16875 time. When only one of the server's "srv_conn" is high, it usually means
16876 that this server has some trouble causing the requests to take longer to be
16877 processed than on other servers.
16878
16879 - "retries" is the number of connection retries experienced by this session
16880 when trying to connect to the server. It must normally be zero, unless a
16881 server is being stopped at the same moment the connection was attempted.
16882 Frequent retries generally indicate either a network problem between
16883 haproxy and the server, or a misconfigured system backlog on the server
16884 preventing new connections from being queued. This field may optionally be
16885 prefixed with a '+' sign, indicating that the session has experienced a
16886 redispatch after the maximal retry count has been reached on the initial
16887 server. In this case, the server name appearing in the log is the one the
16888 connection was redispatched to, and not the first one, though both may
16889 sometimes be the same in case of hashing for instance. So as a general rule
16890 of thumb, when a '+' is present in front of the retry count, this count
16891 should not be attributed to the logged server.
16892
16893 - "srv_queue" is the total number of requests which were processed before
16894 this one in the server queue. It is zero when the request has not gone
16895 through the server queue. It makes it possible to estimate the approximate
16896 server's response time by dividing the time spent in queue by the number of
16897 requests in the queue. It is worth noting that if a session experiences a
16898 redispatch and passes through two server queues, their positions will be
Davor Ocelice9ed2812017-12-25 17:49:28 +010016899 cumulative. A request should not pass through both the server queue and the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016900 backend queue unless a redispatch occurs.
16901
16902 - "backend_queue" is the total number of requests which were processed before
16903 this one in the backend's global queue. It is zero when the request has not
16904 gone through the global queue. It makes it possible to estimate the average
16905 queue length, which easily translates into a number of missing servers when
16906 divided by a server's "maxconn" parameter. It is worth noting that if a
16907 session experiences a redispatch, it may pass twice in the backend's queue,
Davor Ocelice9ed2812017-12-25 17:49:28 +010016908 and then both positions will be cumulative. A request should not pass
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016909 through both the server queue and the backend queue unless a redispatch
16910 occurs.
16911
16912 - "captured_request_headers" is a list of headers captured in the request due
16913 to the presence of the "capture request header" statement in the frontend.
16914 Multiple headers can be captured, they will be delimited by a vertical bar
16915 ('|'). When no capture is enabled, the braces do not appear, causing a
16916 shift of remaining fields. It is important to note that this field may
16917 contain spaces, and that using it requires a smarter log parser than when
16918 it's not used. Please consult the section "Capturing HTTP headers and
16919 cookies" below for more details.
16920
16921 - "captured_response_headers" is a list of headers captured in the response
16922 due to the presence of the "capture response header" statement in the
16923 frontend. Multiple headers can be captured, they will be delimited by a
16924 vertical bar ('|'). When no capture is enabled, the braces do not appear,
16925 causing a shift of remaining fields. It is important to note that this
16926 field may contain spaces, and that using it requires a smarter log parser
16927 than when it's not used. Please consult the section "Capturing HTTP headers
16928 and cookies" below for more details.
16929
16930 - "http_request" is the complete HTTP request line, including the method,
16931 request and HTTP version string. Non-printable characters are encoded (see
16932 below the section "Non-printable characters"). This is always the last
16933 field, and it is always delimited by quotes and is the only one which can
16934 contain quotes. If new fields are added to the log format, they will be
16935 added before this field. This field might be truncated if the request is
16936 huge and does not fit in the standard syslog buffer (1024 characters). This
16937 is the reason why this field must always remain the last one.
16938
16939
Cyril Bontédc4d9032012-04-08 21:57:39 +0200169408.2.4. Custom log format
16941------------------------
William Lallemand48940402012-01-30 16:47:22 +010016942
Willy Tarreau2beef582012-12-20 17:22:52 +010016943The directive log-format allows you to customize the logs in http mode and tcp
William Lallemandbddd4fd2012-02-27 11:23:10 +010016944mode. It takes a string as argument.
William Lallemand48940402012-01-30 16:47:22 +010016945
Davor Ocelice9ed2812017-12-25 17:49:28 +010016946HAProxy understands some log format variables. % precedes log format variables.
William Lallemand48940402012-01-30 16:47:22 +010016947Variables can take arguments using braces ('{}'), and multiple arguments are
16948separated by commas within the braces. Flags may be added or removed by
16949prefixing them with a '+' or '-' sign.
16950
16951Special variable "%o" may be used to propagate its flags to all other
16952variables on the same format string. This is particularly handy with quoted
Dragan Dosen835b9212016-02-12 13:23:03 +010016953("Q") and escaped ("E") string formats.
William Lallemand48940402012-01-30 16:47:22 +010016954
Willy Tarreauc8368452012-12-21 00:09:23 +010016955If a variable is named between square brackets ('[' .. ']') then it is used
Willy Tarreaube722a22014-06-13 16:31:59 +020016956as a sample expression rule (see section 7.3). This it useful to add some
Willy Tarreauc8368452012-12-21 00:09:23 +010016957less common information such as the client's SSL certificate's DN, or to log
16958the key that would be used to store an entry into a stick table.
16959
William Lallemand48940402012-01-30 16:47:22 +010016960Note: spaces must be escaped. A space character is considered as a separator.
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016961In order to emit a verbatim '%', it must be preceded by another '%' resulting
Willy Tarreau06d97f92013-12-02 17:45:48 +010016962in '%%'. HAProxy will automatically merge consecutive separators.
William Lallemand48940402012-01-30 16:47:22 +010016963
Dragan Dosen835b9212016-02-12 13:23:03 +010016964Note: when using the RFC5424 syslog message format, the characters '"',
16965'\' and ']' inside PARAM-VALUE should be escaped with '\' as prefix (see
16966https://tools.ietf.org/html/rfc5424#section-6.3.3 for more details). In
16967such cases, the use of the flag "E" should be considered.
16968
William Lallemand48940402012-01-30 16:47:22 +010016969Flags are :
16970 * Q: quote a string
Jamie Gloudonaaa21002012-08-25 00:18:33 -040016971 * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid)
Dragan Dosen835b9212016-02-12 13:23:03 +010016972 * E: escape characters '"', '\' and ']' in a string with '\' as prefix
16973 (intended purpose is for the RFC5424 structured-data log formats)
William Lallemand48940402012-01-30 16:47:22 +010016974
16975 Example:
16976
16977 log-format %T\ %t\ Some\ Text
16978 log-format %{+Q}o\ %t\ %s\ %{-Q}r
16979
Dragan Dosen835b9212016-02-12 13:23:03 +010016980 log-format-sd %{+Q,+E}o\ [exampleSDID@1234\ header=%[capture.req.hdr(0)]]
16981
William Lallemand48940402012-01-30 16:47:22 +010016982At the moment, the default HTTP format is defined this way :
16983
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016984 log-format "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC \
16985 %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs %{+Q}r"
William Lallemand48940402012-01-30 16:47:22 +010016986
William Lallemandbddd4fd2012-02-27 11:23:10 +010016987the default CLF format is defined this way :
William Lallemand48940402012-01-30 16:47:22 +010016988
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016989 log-format "%{+Q}o %{-Q}ci - - [%trg] %r %ST %B \"\" \"\" %cp \
16990 %ms %ft %b %s %TR %Tw %Tc %Tr %Ta %tsc %ac %fc \
16991 %bc %sc %rc %sq %bq %CC %CS %hrl %hsl"
William Lallemand48940402012-01-30 16:47:22 +010016992
William Lallemandbddd4fd2012-02-27 11:23:10 +010016993and the default TCP format is defined this way :
16994
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016995 log-format "%ci:%cp [%t] %ft %b/%s %Tw/%Tc/%Tt %B %ts \
16996 %ac/%fc/%bc/%sc/%rc %sq/%bq"
William Lallemandbddd4fd2012-02-27 11:23:10 +010016997
William Lallemand48940402012-01-30 16:47:22 +010016998Please refer to the table below for currently defined variables :
16999
William Lallemandbddd4fd2012-02-27 11:23:10 +010017000 +---+------+-----------------------------------------------+-------------+
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020017001 | R | var | field name (8.2.2 and 8.2.3 for description) | type |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017002 +---+------+-----------------------------------------------+-------------+
17003 | | %o | special variable, apply flags on all next var | |
17004 +---+------+-----------------------------------------------+-------------+
Willy Tarreau2beef582012-12-20 17:22:52 +010017005 | | %B | bytes_read (from server to client) | numeric |
17006 | H | %CC | captured_request_cookie | string |
17007 | H | %CS | captured_response_cookie | string |
William Lallemand5f232402012-04-05 18:02:55 +020017008 | | %H | hostname | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000017009 | H | %HM | HTTP method (ex: POST) | string |
17010 | H | %HP | HTTP request URI without query string (path) | string |
Andrew Hayworthe63ac872015-07-31 16:14:16 +000017011 | H | %HQ | HTTP request URI query string (ex: ?bar=baz) | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000017012 | H | %HU | HTTP request URI (ex: /foo?bar=baz) | string |
17013 | H | %HV | HTTP version (ex: HTTP/1.0) | string |
William Lallemanda73203e2012-03-12 12:48:57 +010017014 | | %ID | unique-id | string |
Willy Tarreau4bf99632014-06-13 12:21:40 +020017015 | | %ST | status_code | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020017016 | | %T | gmt_date_time | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017017 | | %Ta | Active time of the request (from TR to end) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017018 | | %Tc | Tc | numeric |
Willy Tarreau27b639d2016-05-17 17:55:27 +020017019 | | %Td | Td = Tt - (Tq + Tw + Tc + Tr) | numeric |
Yuxans Yao4e25b012012-10-19 10:36:09 +080017020 | | %Tl | local_date_time | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017021 | | %Th | connection handshake time (SSL, PROXY proto) | numeric |
17022 | H | %Ti | idle time before the HTTP request | numeric |
17023 | H | %Tq | Th + Ti + TR | numeric |
17024 | H | %TR | time to receive the full request from 1st byte| numeric |
17025 | H | %Tr | Tr (response time) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020017026 | | %Ts | timestamp | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017027 | | %Tt | Tt | numeric |
17028 | | %Tw | Tw | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010017029 | | %U | bytes_uploaded (from client to server) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017030 | | %ac | actconn | numeric |
17031 | | %b | backend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010017032 | | %bc | beconn (backend concurrent connections) | numeric |
17033 | | %bi | backend_source_ip (connecting address) | IP |
17034 | | %bp | backend_source_port (connecting address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017035 | | %bq | backend_queue | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010017036 | | %ci | client_ip (accepted address) | IP |
17037 | | %cp | client_port (accepted address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017038 | | %f | frontend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010017039 | | %fc | feconn (frontend concurrent connections) | numeric |
17040 | | %fi | frontend_ip (accepting address) | IP |
17041 | | %fp | frontend_port (accepting address) | numeric |
Willy Tarreau773d65f2012-10-12 14:56:11 +020017042 | | %ft | frontend_name_transport ('~' suffix for SSL) | string |
Willy Tarreau7346acb2014-08-28 15:03:15 +020017043 | | %lc | frontend_log_counter | numeric |
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020017044 | | %hr | captured_request_headers default style | string |
17045 | | %hrl | captured_request_headers CLF style | string list |
17046 | | %hs | captured_response_headers default style | string |
17047 | | %hsl | captured_response_headers CLF style | string list |
Willy Tarreau812c88e2015-08-09 10:56:35 +020017048 | | %ms | accept date milliseconds (left-padded with 0) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020017049 | | %pid | PID | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020017050 | H | %r | http_request | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017051 | | %rc | retries | numeric |
Willy Tarreau1f0da242014-01-25 11:01:50 +010017052 | | %rt | request_counter (HTTP req or TCP session) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017053 | | %s | server_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010017054 | | %sc | srv_conn (server concurrent connections) | numeric |
17055 | | %si | server_IP (target address) | IP |
17056 | | %sp | server_port (target address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017057 | | %sq | srv_queue | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020017058 | S | %sslc| ssl_ciphers (ex: AES-SHA) | string |
17059 | S | %sslv| ssl_version (ex: TLSv1) | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010017060 | | %t | date_time (with millisecond resolution) | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017061 | H | %tr | date_time of HTTP request | date |
17062 | H | %trg | gmt_date_time of start of HTTP request | date |
Jens Bissinger15c64ff2018-08-23 14:11:27 +020017063 | H | %trl | local_date_time of start of HTTP request | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017064 | | %ts | termination_state | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020017065 | H | %tsc | termination_state with cookie status | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017066 +---+------+-----------------------------------------------+-------------+
William Lallemand48940402012-01-30 16:47:22 +010017067
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020017068 R = Restrictions : H = mode http only ; S = SSL only
William Lallemand48940402012-01-30 16:47:22 +010017069
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010017070
170718.2.5. Error log format
17072-----------------------
17073
17074When an incoming connection fails due to an SSL handshake or an invalid PROXY
17075protocol header, haproxy will log the event using a shorter, fixed line format.
17076By default, logs are emitted at the LOG_INFO level, unless the option
17077"log-separate-errors" is set in the backend, in which case the LOG_ERR level
Davor Ocelice9ed2812017-12-25 17:49:28 +010017078will be used. Connections on which no data are exchanged (e.g. probes) are not
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010017079logged if the "dontlognull" option is set.
17080
17081The format looks like this :
17082
17083 >>> Dec 3 18:27:14 localhost \
17084 haproxy[6103]: 127.0.0.1:56059 [03/Dec/2012:17:35:10.380] frt/f1: \
17085 Connection error during SSL handshake
17086
17087 Field Format Extract from the example above
17088 1 process_name '[' pid ']:' haproxy[6103]:
17089 2 client_ip ':' client_port 127.0.0.1:56059
17090 3 '[' accept_date ']' [03/Dec/2012:17:35:10.380]
17091 4 frontend_name "/" bind_name ":" frt/f1:
17092 5 message Connection error during SSL handshake
17093
17094These fields just provide minimal information to help debugging connection
17095failures.
17096
17097
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200170988.3. Advanced logging options
17099-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017100
17101Some advanced logging options are often looked for but are not easy to find out
17102just by looking at the various options. Here is an entry point for the few
17103options which can enable better logging. Please refer to the keywords reference
17104for more information about their usage.
17105
17106
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200171078.3.1. Disabling logging of external tests
17108------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017109
17110It is quite common to have some monitoring tools perform health checks on
17111haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
17112commercial load-balancer, and sometimes it will simply be a more complete
17113monitoring system such as Nagios. When the tests are very frequent, users often
17114ask how to disable logging for those checks. There are three possibilities :
17115
17116 - if connections come from everywhere and are just TCP probes, it is often
17117 desired to simply disable logging of connections without data exchange, by
17118 setting "option dontlognull" in the frontend. It also disables logging of
17119 port scans, which may or may not be desired.
17120
17121 - if the connection come from a known source network, use "monitor-net" to
17122 declare this network as monitoring only. Any host in this network will then
17123 only be able to perform health checks, and their requests will not be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017124 logged. This is generally appropriate to designate a list of equipment
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017125 such as other load-balancers.
17126
17127 - if the tests are performed on a known URI, use "monitor-uri" to declare
17128 this URI as dedicated to monitoring. Any host sending this request will
17129 only get the result of a health-check, and the request will not be logged.
17130
17131
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200171328.3.2. Logging before waiting for the session to terminate
17133----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017134
17135The problem with logging at end of connection is that you have no clue about
17136what is happening during very long sessions, such as remote terminal sessions
17137or large file downloads. This problem can be worked around by specifying
Davor Ocelice9ed2812017-12-25 17:49:28 +010017138"option logasap" in the frontend. HAProxy will then log as soon as possible,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017139just before data transfer begins. This means that in case of TCP, it will still
17140log the connection status to the server, and in case of HTTP, it will log just
17141after processing the server headers. In this case, the number of bytes reported
17142is the number of header bytes sent to the client. In order to avoid confusion
17143with normal logs, the total time field and the number of bytes are prefixed
17144with a '+' sign which means that real numbers are certainly larger.
17145
17146
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200171478.3.3. Raising log level upon errors
17148------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020017149
17150Sometimes it is more convenient to separate normal traffic from errors logs,
17151for instance in order to ease error monitoring from log files. When the option
17152"log-separate-errors" is used, connections which experience errors, timeouts,
17153retries, redispatches or HTTP status codes 5xx will see their syslog level
17154raised from "info" to "err". This will help a syslog daemon store the log in
17155a separate file. It is very important to keep the errors in the normal traffic
17156file too, so that log ordering is not altered. You should also be careful if
17157you already have configured your syslog daemon to store all logs higher than
17158"notice" in an "admin" file, because the "err" level is higher than "notice".
17159
17160
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200171618.3.4. Disabling logging of successful connections
17162--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020017163
17164Although this may sound strange at first, some large sites have to deal with
17165multiple thousands of logs per second and are experiencing difficulties keeping
17166them intact for a long time or detecting errors within them. If the option
17167"dontlog-normal" is set on the frontend, all normal connections will not be
17168logged. In this regard, a normal connection is defined as one without any
17169error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
17170and a response with a status 5xx is not considered normal and will be logged
17171too. Of course, doing is is really discouraged as it will remove most of the
17172useful information from the logs. Do this only if you have no other
17173alternative.
17174
17175
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200171768.4. Timing events
17177------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017178
17179Timers provide a great help in troubleshooting network problems. All values are
17180reported in milliseconds (ms). These timers should be used in conjunction with
17181the session termination flags. In TCP mode with "option tcplog" set on the
17182frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017183mode, 5 control points are reported under the form "TR/Tw/Tc/Tr/Ta". In
17184addition, three other measures are provided, "Th", "Ti", and "Tq".
17185
Guillaume de Lafondf27cddc2016-12-23 17:32:43 +010017186Timings events in HTTP mode:
17187
17188 first request 2nd request
17189 |<-------------------------------->|<-------------- ...
17190 t tr t tr ...
17191 ---|----|----|----|----|----|----|----|----|--
17192 : Th Ti TR Tw Tc Tr Td : Ti ...
17193 :<---- Tq ---->: :
17194 :<-------------- Tt -------------->:
17195 :<--------- Ta --------->:
17196
17197Timings events in TCP mode:
17198
17199 TCP session
17200 |<----------------->|
17201 t t
17202 ---|----|----|----|----|---
17203 | Th Tw Tc Td |
17204 |<------ Tt ------->|
17205
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017206 - Th: total time to accept tcp connection and execute handshakes for low level
Davor Ocelice9ed2812017-12-25 17:49:28 +010017207 protocols. Currently, these protocols are proxy-protocol and SSL. This may
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017208 only happen once during the whole connection's lifetime. A large time here
17209 may indicate that the client only pre-established the connection without
17210 speaking, that it is experiencing network issues preventing it from
Davor Ocelice9ed2812017-12-25 17:49:28 +010017211 completing a handshake in a reasonable time (e.g. MTU issues), or that an
Willy Tarreau590a0512018-09-05 11:56:48 +020017212 SSL handshake was very expensive to compute. Please note that this time is
17213 reported only before the first request, so it is safe to average it over
17214 all request to calculate the amortized value. The second and subsequent
17215 request will always report zero here.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017216
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017217 - Ti: is the idle time before the HTTP request (HTTP mode only). This timer
17218 counts between the end of the handshakes and the first byte of the HTTP
17219 request. When dealing with a second request in keep-alive mode, it starts
Willy Tarreau590a0512018-09-05 11:56:48 +020017220 to count after the end of the transmission the previous response. When a
17221 multiplexed protocol such as HTTP/2 is used, it starts to count immediately
17222 after the previous request. Some browsers pre-establish connections to a
17223 server in order to reduce the latency of a future request, and keep them
17224 pending until they need it. This delay will be reported as the idle time. A
17225 value of -1 indicates that nothing was received on the connection.
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017226
17227 - TR: total time to get the client request (HTTP mode only). It's the time
17228 elapsed between the first bytes received and the moment the proxy received
17229 the empty line marking the end of the HTTP headers. The value "-1"
17230 indicates that the end of headers has never been seen. This happens when
17231 the client closes prematurely or times out. This time is usually very short
17232 since most requests fit in a single packet. A large time may indicate a
17233 request typed by hand during a test.
17234
17235 - Tq: total time to get the client request from the accept date or since the
17236 emission of the last byte of the previous response (HTTP mode only). It's
Davor Ocelice9ed2812017-12-25 17:49:28 +010017237 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 +020017238 returns -1 as well. This timer used to be very useful before the arrival of
17239 HTTP keep-alive and browsers' pre-connect feature. It's recommended to drop
17240 it in favor of TR nowadays, as the idle time adds a lot of noise to the
17241 reports.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017242
17243 - Tw: total time spent in the queues waiting for a connection slot. It
17244 accounts for backend queue as well as the server queues, and depends on the
17245 queue size, and the time needed for the server to complete previous
17246 requests. The value "-1" means that the request was killed before reaching
17247 the queue, which is generally what happens with invalid or denied requests.
17248
17249 - Tc: total time to establish the TCP connection to the server. It's the time
17250 elapsed between the moment the proxy sent the connection request, and the
17251 moment it was acknowledged by the server, or between the TCP SYN packet and
17252 the matching SYN/ACK packet in return. The value "-1" means that the
17253 connection never established.
17254
17255 - Tr: server response time (HTTP mode only). It's the time elapsed between
17256 the moment the TCP connection was established to the server and the moment
17257 the server sent its complete response headers. It purely shows its request
17258 processing time, without the network overhead due to the data transmission.
17259 It is worth noting that when the client has data to send to the server, for
17260 instance during a POST request, the time already runs, and this can distort
17261 apparent response time. For this reason, it's generally wise not to trust
17262 too much this field for POST requests initiated from clients behind an
17263 untrusted network. A value of "-1" here means that the last the response
17264 header (empty line) was never seen, most likely because the server timeout
17265 stroke before the server managed to process the request.
17266
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017267 - Ta: total active time for the HTTP request, between the moment the proxy
17268 received the first byte of the request header and the emission of the last
17269 byte of the response body. The exception is when the "logasap" option is
17270 specified. In this case, it only equals (TR+Tw+Tc+Tr), and is prefixed with
17271 a '+' sign. From this field, we can deduce "Td", the data transmission time,
17272 by subtracting other timers when valid :
17273
17274 Td = Ta - (TR + Tw + Tc + Tr)
17275
17276 Timers with "-1" values have to be excluded from this equation. Note that
17277 "Ta" can never be negative.
17278
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017279 - Tt: total session duration time, between the moment the proxy accepted it
17280 and the moment both ends were closed. The exception is when the "logasap"
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017281 option is specified. In this case, it only equals (Th+Ti+TR+Tw+Tc+Tr), and
17282 is prefixed with a '+' sign. From this field, we can deduce "Td", the data
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017283 transmission time, by subtracting other timers when valid :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017284
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017285 Td = Tt - (Th + Ti + TR + Tw + Tc + Tr)
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017286
17287 Timers with "-1" values have to be excluded from this equation. In TCP
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017288 mode, "Ti", "Tq" and "Tr" have to be excluded too. Note that "Tt" can never
17289 be negative and that for HTTP, Tt is simply equal to (Th+Ti+Ta).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017290
17291These timers provide precious indications on trouble causes. Since the TCP
17292protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
17293that timers close to multiples of 3s are nearly always related to lost packets
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017294due to network problems (wires, negotiation, congestion). Moreover, if "Ta" or
17295"Tt" is close to a timeout value specified in the configuration, it often means
17296that a session has been aborted on timeout.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017297
17298Most common cases :
17299
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017300 - If "Th" or "Ti" are close to 3000, a packet has probably been lost between
17301 the client and the proxy. This is very rare on local networks but might
17302 happen when clients are on far remote networks and send large requests. It
17303 may happen that values larger than usual appear here without any network
17304 cause. Sometimes, during an attack or just after a resource starvation has
17305 ended, haproxy may accept thousands of connections in a few milliseconds.
17306 The time spent accepting these connections will inevitably slightly delay
17307 processing of other connections, and it can happen that request times in the
17308 order of a few tens of milliseconds are measured after a few thousands of
17309 new connections have been accepted at once. Using one of the keep-alive
17310 modes may display larger idle times since "Ti" measures the time spent
Patrick Mezard105faca2010-06-12 17:02:46 +020017311 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017312
17313 - If "Tc" is close to 3000, a packet has probably been lost between the
17314 server and the proxy during the server connection phase. This value should
17315 always be very low, such as 1 ms on local networks and less than a few tens
17316 of ms on remote networks.
17317
Willy Tarreau55165fe2009-05-10 12:02:55 +020017318 - If "Tr" is nearly always lower than 3000 except some rare values which seem
17319 to be the average majored by 3000, there are probably some packets lost
17320 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017321
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017322 - If "Ta" is large even for small byte counts, it generally is because
17323 neither the client nor the server decides to close the connection while
17324 haproxy is running in tunnel mode and both have agreed on a keep-alive
17325 connection mode. In order to solve this issue, it will be needed to specify
17326 one of the HTTP options to manipulate keep-alive or close options on either
17327 the frontend or the backend. Having the smallest possible 'Ta' or 'Tt' is
17328 important when connection regulation is used with the "maxconn" option on
17329 the servers, since no new connection will be sent to the server until
17330 another one is released.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017331
17332Other noticeable HTTP log cases ('xx' means any value to be ignored) :
17333
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017334 TR/Tw/Tc/Tr/+Ta The "option logasap" is present on the frontend and the log
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017335 was emitted before the data phase. All the timers are valid
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017336 except "Ta" which is shorter than reality.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017337
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017338 -1/xx/xx/xx/Ta The client was not able to send a complete request in time
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017339 or it aborted too early. Check the session termination flags
17340 then "timeout http-request" and "timeout client" settings.
17341
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017342 TR/-1/xx/xx/Ta It was not possible to process the request, maybe because
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017343 servers were out of order, because the request was invalid
17344 or forbidden by ACL rules. Check the session termination
17345 flags.
17346
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017347 TR/Tw/-1/xx/Ta The connection could not establish on the server. Either it
17348 actively refused it or it timed out after Ta-(TR+Tw) ms.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017349 Check the session termination flags, then check the
17350 "timeout connect" setting. Note that the tarpit action might
17351 return similar-looking patterns, with "Tw" equal to the time
17352 the client connection was maintained open.
17353
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017354 TR/Tw/Tc/-1/Ta The server has accepted the connection but did not return
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017355 a complete response in time, or it closed its connection
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017356 unexpectedly after Ta-(TR+Tw+Tc) ms. Check the session
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017357 termination flags, then check the "timeout server" setting.
17358
17359
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200173608.5. Session state at disconnection
17361-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017362
17363TCP and HTTP logs provide a session termination indicator in the
17364"termination_state" field, just before the number of active connections. It is
173652-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
17366each of which has a special meaning :
17367
17368 - On the first character, a code reporting the first event which caused the
17369 session to terminate :
17370
17371 C : the TCP session was unexpectedly aborted by the client.
17372
17373 S : the TCP session was unexpectedly aborted by the server, or the
17374 server explicitly refused it.
17375
17376 P : the session was prematurely aborted by the proxy, because of a
17377 connection limit enforcement, because a DENY filter was matched,
17378 because of a security check which detected and blocked a dangerous
17379 error in server response which might have caused information leak
Davor Ocelice9ed2812017-12-25 17:49:28 +010017380 (e.g. cacheable cookie).
Willy Tarreau570f2212013-06-10 16:42:09 +020017381
17382 L : the session was locally processed by haproxy and was not passed to
17383 a server. This is what happens for stats and redirects.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017384
17385 R : a resource on the proxy has been exhausted (memory, sockets, source
17386 ports, ...). Usually, this appears during the connection phase, and
17387 system logs should contain a copy of the precise error. If this
17388 happens, it must be considered as a very serious anomaly which
17389 should be fixed as soon as possible by any means.
17390
17391 I : an internal error was identified by the proxy during a self-check.
17392 This should NEVER happen, and you are encouraged to report any log
17393 containing this, because this would almost certainly be a bug. It
17394 would be wise to preventively restart the process after such an
17395 event too, in case it would be caused by memory corruption.
17396
Simon Horman752dc4a2011-06-21 14:34:59 +090017397 D : the session was killed by haproxy because the server was detected
17398 as down and was configured to kill all connections when going down.
17399
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070017400 U : the session was killed by haproxy on this backup server because an
17401 active server was detected as up and was configured to kill all
17402 backup connections when going up.
17403
Willy Tarreaua2a64e92011-09-07 23:01:56 +020017404 K : the session was actively killed by an admin operating on haproxy.
17405
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017406 c : the client-side timeout expired while waiting for the client to
17407 send or receive data.
17408
17409 s : the server-side timeout expired while waiting for the server to
17410 send or receive data.
17411
17412 - : normal session completion, both the client and the server closed
17413 with nothing left in the buffers.
17414
17415 - on the second character, the TCP or HTTP session state when it was closed :
17416
Willy Tarreauf7b30a92010-12-06 22:59:17 +010017417 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017418 (HTTP mode only). Nothing was sent to any server.
17419
17420 Q : the proxy was waiting in the QUEUE for a connection slot. This can
17421 only happen when servers have a 'maxconn' parameter set. It can
17422 also happen in the global queue after a redispatch consecutive to
17423 a failed attempt to connect to a dying server. If no redispatch is
17424 reported, then no connection attempt was made to any server.
17425
17426 C : the proxy was waiting for the CONNECTION to establish on the
17427 server. The server might at most have noticed a connection attempt.
17428
17429 H : the proxy was waiting for complete, valid response HEADERS from the
17430 server (HTTP only).
17431
17432 D : the session was in the DATA phase.
17433
17434 L : the proxy was still transmitting LAST data to the client while the
17435 server had already finished. This one is very rare as it can only
17436 happen when the client dies while receiving the last packets.
17437
17438 T : the request was tarpitted. It has been held open with the client
17439 during the whole "timeout tarpit" duration or until the client
17440 closed, both of which will be reported in the "Tw" timer.
17441
17442 - : normal session completion after end of data transfer.
17443
17444 - the third character tells whether the persistence cookie was provided by
17445 the client (only in HTTP mode) :
17446
17447 N : the client provided NO cookie. This is usually the case for new
17448 visitors, so counting the number of occurrences of this flag in the
17449 logs generally indicate a valid trend for the site frequentation.
17450
17451 I : the client provided an INVALID cookie matching no known server.
17452 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +020017453 cookies between HTTP/HTTPS sites, persistence conditionally
17454 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017455
17456 D : the client provided a cookie designating a server which was DOWN,
17457 so either "option persist" was used and the client was sent to
17458 this server, or it was not set and the client was redispatched to
17459 another server.
17460
Willy Tarreau996a92c2010-10-13 19:30:47 +020017461 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017462 server.
17463
Willy Tarreau996a92c2010-10-13 19:30:47 +020017464 E : the client provided a valid cookie, but with a last date which was
17465 older than what is allowed by the "maxidle" cookie parameter, so
17466 the cookie is consider EXPIRED and is ignored. The request will be
17467 redispatched just as if there was no cookie.
17468
17469 O : the client provided a valid cookie, but with a first date which was
17470 older than what is allowed by the "maxlife" cookie parameter, so
17471 the cookie is consider too OLD and is ignored. The request will be
17472 redispatched just as if there was no cookie.
17473
Willy Tarreauc89ccb62012-04-05 21:18:22 +020017474 U : a cookie was present but was not used to select the server because
17475 some other server selection mechanism was used instead (typically a
17476 "use-server" rule).
17477
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017478 - : does not apply (no cookie set in configuration).
17479
17480 - the last character reports what operations were performed on the persistence
17481 cookie returned by the server (only in HTTP mode) :
17482
17483 N : NO cookie was provided by the server, and none was inserted either.
17484
17485 I : no cookie was provided by the server, and the proxy INSERTED one.
17486 Note that in "cookie insert" mode, if the server provides a cookie,
17487 it will still be overwritten and reported as "I" here.
17488
Willy Tarreau996a92c2010-10-13 19:30:47 +020017489 U : the proxy UPDATED the last date in the cookie that was presented by
17490 the client. This can only happen in insert mode with "maxidle". It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017491 happens every time there is activity at a different date than the
Willy Tarreau996a92c2010-10-13 19:30:47 +020017492 date indicated in the cookie. If any other change happens, such as
17493 a redispatch, then the cookie will be marked as inserted instead.
17494
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017495 P : a cookie was PROVIDED by the server and transmitted as-is.
17496
17497 R : the cookie provided by the server was REWRITTEN by the proxy, which
17498 happens in "cookie rewrite" or "cookie prefix" modes.
17499
17500 D : the cookie provided by the server was DELETED by the proxy.
17501
17502 - : does not apply (no cookie set in configuration).
17503
Willy Tarreau996a92c2010-10-13 19:30:47 +020017504The combination of the two first flags gives a lot of information about what
17505was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017506helpful to detect server saturation, network troubles, local system resource
17507starvation, attacks, etc...
17508
17509The most common termination flags combinations are indicated below. They are
17510alphabetically sorted, with the lowercase set just after the upper case for
17511easier finding and understanding.
17512
17513 Flags Reason
17514
17515 -- Normal termination.
17516
17517 CC The client aborted before the connection could be established to the
17518 server. This can happen when haproxy tries to connect to a recently
17519 dead (or unchecked) server, and the client aborts while haproxy is
17520 waiting for the server to respond or for "timeout connect" to expire.
17521
17522 CD The client unexpectedly aborted during data transfer. This can be
17523 caused by a browser crash, by an intermediate equipment between the
17524 client and haproxy which decided to actively break the connection,
17525 by network routing issues between the client and haproxy, or by a
17526 keep-alive session between the server and the client terminated first
17527 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +010017528
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017529 cD The client did not send nor acknowledge any data for as long as the
17530 "timeout client" delay. This is often caused by network failures on
Cyril Bontédc4d9032012-04-08 21:57:39 +020017531 the client side, or the client simply leaving the net uncleanly.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017532
17533 CH The client aborted while waiting for the server to start responding.
17534 It might be the server taking too long to respond or the client
17535 clicking the 'Stop' button too fast.
17536
17537 cH The "timeout client" stroke while waiting for client data during a
17538 POST request. This is sometimes caused by too large TCP MSS values
17539 for PPPoE networks which cannot transport full-sized packets. It can
17540 also happen when client timeout is smaller than server timeout and
17541 the server takes too long to respond.
17542
17543 CQ The client aborted while its session was queued, waiting for a server
17544 with enough empty slots to accept it. It might be that either all the
17545 servers were saturated or that the assigned server was taking too
17546 long a time to respond.
17547
17548 CR The client aborted before sending a full HTTP request. Most likely
17549 the request was typed by hand using a telnet client, and aborted
17550 too early. The HTTP status code is likely a 400 here. Sometimes this
17551 might also be caused by an IDS killing the connection between haproxy
Willy Tarreau0f228a02015-05-01 15:37:53 +020017552 and the client. "option http-ignore-probes" can be used to ignore
17553 connections without any data transfer.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017554
17555 cR The "timeout http-request" stroke before the client sent a full HTTP
17556 request. This is sometimes caused by too large TCP MSS values on the
17557 client side for PPPoE networks which cannot transport full-sized
17558 packets, or by clients sending requests by hand and not typing fast
17559 enough, or forgetting to enter the empty line at the end of the
Willy Tarreau2705a612014-05-23 17:38:34 +020017560 request. The HTTP status code is likely a 408 here. Note: recently,
Willy Tarreau0f228a02015-05-01 15:37:53 +020017561 some browsers started to implement a "pre-connect" feature consisting
17562 in speculatively connecting to some recently visited web sites just
17563 in case the user would like to visit them. This results in many
17564 connections being established to web sites, which end up in 408
17565 Request Timeout if the timeout strikes first, or 400 Bad Request when
17566 the browser decides to close them first. These ones pollute the log
17567 and feed the error counters. Some versions of some browsers have even
17568 been reported to display the error code. It is possible to work
Davor Ocelice9ed2812017-12-25 17:49:28 +010017569 around the undesirable effects of this behavior by adding "option
Willy Tarreau0f228a02015-05-01 15:37:53 +020017570 http-ignore-probes" in the frontend, resulting in connections with
17571 zero data transfer to be totally ignored. This will definitely hide
17572 the errors of people experiencing connectivity issues though.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017573
17574 CT The client aborted while its session was tarpitted. It is important to
17575 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +020017576 wrong tarpit rules have been written. If a lot of them happen, it
17577 might make sense to lower the "timeout tarpit" value to something
17578 closer to the average reported "Tw" timer, in order not to consume
17579 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017580
Willy Tarreau570f2212013-06-10 16:42:09 +020017581 LR The request was intercepted and locally handled by haproxy. Generally
17582 it means that this was a redirect or a stats request.
17583
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010017584 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017585 the TCP connection (the proxy received a TCP RST or an ICMP message
17586 in return). Under some circumstances, it can also be the network
Davor Ocelice9ed2812017-12-25 17:49:28 +010017587 stack telling the proxy that the server is unreachable (e.g. no route,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017588 or no ARP response on local network). When this happens in HTTP mode,
17589 the status code is likely a 502 or 503 here.
17590
17591 sC The "timeout connect" stroke before a connection to the server could
17592 complete. When this happens in HTTP mode, the status code is likely a
17593 503 or 504 here.
17594
17595 SD The connection to the server died with an error during the data
17596 transfer. This usually means that haproxy has received an RST from
17597 the server or an ICMP message from an intermediate equipment while
17598 exchanging data with the server. This can be caused by a server crash
17599 or by a network issue on an intermediate equipment.
17600
17601 sD The server did not send nor acknowledge any data for as long as the
17602 "timeout server" setting during the data phase. This is often caused
Davor Ocelice9ed2812017-12-25 17:49:28 +010017603 by too short timeouts on L4 equipment before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017604 load-balancers, ...), as well as keep-alive sessions maintained
17605 between the client and the server expiring first on haproxy.
17606
17607 SH The server aborted before sending its full HTTP response headers, or
17608 it crashed while processing the request. Since a server aborting at
17609 this moment is very rare, it would be wise to inspect its logs to
17610 control whether it crashed and why. The logged request may indicate a
17611 small set of faulty requests, demonstrating bugs in the application.
17612 Sometimes this might also be caused by an IDS killing the connection
17613 between haproxy and the server.
17614
17615 sH The "timeout server" stroke before the server could return its
17616 response headers. This is the most common anomaly, indicating too
17617 long transactions, probably caused by server or database saturation.
17618 The immediate workaround consists in increasing the "timeout server"
17619 setting, but it is important to keep in mind that the user experience
17620 will suffer from these long response times. The only long term
17621 solution is to fix the application.
17622
17623 sQ The session spent too much time in queue and has been expired. See
17624 the "timeout queue" and "timeout connect" settings to find out how to
17625 fix this if it happens too often. If it often happens massively in
17626 short periods, it may indicate general problems on the affected
17627 servers due to I/O or database congestion, or saturation caused by
17628 external attacks.
17629
17630 PC The proxy refused to establish a connection to the server because the
17631 process' socket limit has been reached while attempting to connect.
Cyril Bontédc4d9032012-04-08 21:57:39 +020017632 The global "maxconn" parameter may be increased in the configuration
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017633 so that it does not happen anymore. This status is very rare and
17634 might happen when the global "ulimit-n" parameter is forced by hand.
17635
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010017636 PD The proxy blocked an incorrectly formatted chunked encoded message in
17637 a request or a response, after the server has emitted its headers. In
17638 most cases, this will indicate an invalid message from the server to
Davor Ocelice9ed2812017-12-25 17:49:28 +010017639 the client. HAProxy supports chunk sizes of up to 2GB - 1 (2147483647
Willy Tarreauf3a3e132013-08-31 08:16:26 +020017640 bytes). Any larger size will be considered as an error.
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010017641
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017642 PH The proxy blocked the server's response, because it was invalid,
17643 incomplete, dangerous (cache control), or matched a security filter.
17644 In any case, an HTTP 502 error is sent to the client. One possible
17645 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010017646 containing unauthorized characters. It is also possible but quite
17647 rare, that the proxy blocked a chunked-encoding request from the
17648 client due to an invalid syntax, before the server responded. In this
17649 case, an HTTP 400 error is sent to the client and reported in the
17650 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017651
17652 PR The proxy blocked the client's HTTP request, either because of an
17653 invalid HTTP syntax, in which case it returned an HTTP 400 error to
17654 the client, or because a deny filter matched, in which case it
17655 returned an HTTP 403 error.
17656
17657 PT The proxy blocked the client's request and has tarpitted its
17658 connection before returning it a 500 server error. Nothing was sent
17659 to the server. The connection was maintained open for as long as
17660 reported by the "Tw" timer field.
17661
17662 RC A local resource has been exhausted (memory, sockets, source ports)
17663 preventing the connection to the server from establishing. The error
17664 logs will tell precisely what was missing. This is very rare and can
17665 only be solved by proper system tuning.
17666
Willy Tarreau996a92c2010-10-13 19:30:47 +020017667The combination of the two last flags gives a lot of information about how
17668persistence was handled by the client, the server and by haproxy. This is very
17669important to troubleshoot disconnections, when users complain they have to
17670re-authenticate. The commonly encountered flags are :
17671
17672 -- Persistence cookie is not enabled.
17673
17674 NN No cookie was provided by the client, none was inserted in the
17675 response. For instance, this can be in insert mode with "postonly"
17676 set on a GET request.
17677
17678 II A cookie designating an invalid server was provided by the client,
17679 a valid one was inserted in the response. This typically happens when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040017680 a "server" entry is removed from the configuration, since its cookie
Willy Tarreau996a92c2010-10-13 19:30:47 +020017681 value can be presented by a client when no other server knows it.
17682
17683 NI No cookie was provided by the client, one was inserted in the
17684 response. This typically happens for first requests from every user
17685 in "insert" mode, which makes it an easy way to count real users.
17686
17687 VN A cookie was provided by the client, none was inserted in the
17688 response. This happens for most responses for which the client has
17689 already got a cookie.
17690
17691 VU A cookie was provided by the client, with a last visit date which is
17692 not completely up-to-date, so an updated cookie was provided in
17693 response. This can also happen if there was no date at all, or if
17694 there was a date but the "maxidle" parameter was not set, so that the
17695 cookie can be switched to unlimited time.
17696
17697 EI A cookie was provided by the client, with a last visit date which is
17698 too old for the "maxidle" parameter, so the cookie was ignored and a
17699 new cookie was inserted in the response.
17700
17701 OI A cookie was provided by the client, with a first visit date which is
17702 too old for the "maxlife" parameter, so the cookie was ignored and a
17703 new cookie was inserted in the response.
17704
17705 DI The server designated by the cookie was down, a new server was
17706 selected and a new cookie was emitted in the response.
17707
17708 VI The server designated by the cookie was not marked dead but could not
17709 be reached. A redispatch happened and selected another one, which was
17710 then advertised in the response.
17711
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017712
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200177138.6. Non-printable characters
17714-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017715
17716In order not to cause trouble to log analysis tools or terminals during log
17717consulting, non-printable characters are not sent as-is into log files, but are
17718converted to the two-digits hexadecimal representation of their ASCII code,
17719prefixed by the character '#'. The only characters that can be logged without
17720being escaped are comprised between 32 and 126 (inclusive). Obviously, the
17721escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
17722is the same for the character '"' which becomes "#22", as well as '{', '|' and
17723'}' when logging headers.
17724
17725Note that the space character (' ') is not encoded in headers, which can cause
17726issues for tools relying on space count to locate fields. A typical header
17727containing spaces is "User-Agent".
17728
17729Last, it has been observed that some syslog daemons such as syslog-ng escape
17730the quote ('"') with a backslash ('\'). The reverse operation can safely be
17731performed since no quote may appear anywhere else in the logs.
17732
17733
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200177348.7. Capturing HTTP cookies
17735---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017736
17737Cookie capture simplifies the tracking a complete user session. This can be
17738achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017739section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017740cookie will simultaneously be checked in the request ("Cookie:" header) and in
17741the response ("Set-Cookie:" header). The respective values will be reported in
17742the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017743locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017744not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
17745user switches to a new session for example, because the server will reassign it
17746a new cookie. It is also possible to detect if a server unexpectedly sets a
17747wrong cookie to a client, leading to session crossing.
17748
17749 Examples :
17750 # capture the first cookie whose name starts with "ASPSESSION"
17751 capture cookie ASPSESSION len 32
17752
17753 # capture the first cookie whose name is exactly "vgnvisitor"
17754 capture cookie vgnvisitor= len 32
17755
17756
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200177578.8. Capturing HTTP headers
17758---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017759
17760Header captures are useful to track unique request identifiers set by an upper
17761proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
17762the response, one can search for information about the response length, how the
17763server asked the cache to behave, or an object location during a redirection.
17764
17765Header captures are performed using the "capture request header" and "capture
17766response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017767section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017768
17769It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010017770time. Non-existent headers are logged as empty strings, and if one header
17771appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017772are grouped within braces '{' and '}' in the same order as they were declared,
17773and delimited with a vertical bar '|' without any space. Response headers
17774follow the same representation, but are displayed after a space following the
17775request headers block. These blocks are displayed just before the HTTP request
17776in the logs.
17777
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020017778As a special case, it is possible to specify an HTTP header capture in a TCP
17779frontend. The purpose is to enable logging of headers which will be parsed in
17780an HTTP backend if the request is then switched to this HTTP backend.
17781
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017782 Example :
17783 # This instance chains to the outgoing proxy
17784 listen proxy-out
17785 mode http
17786 option httplog
17787 option logasap
17788 log global
17789 server cache1 192.168.1.1:3128
17790
17791 # log the name of the virtual server
17792 capture request header Host len 20
17793
17794 # log the amount of data uploaded during a POST
17795 capture request header Content-Length len 10
17796
17797 # log the beginning of the referrer
17798 capture request header Referer len 20
17799
17800 # server name (useful for outgoing proxies only)
17801 capture response header Server len 20
17802
17803 # logging the content-length is useful with "option logasap"
17804 capture response header Content-Length len 10
17805
Davor Ocelice9ed2812017-12-25 17:49:28 +010017806 # log the expected cache behavior on the response
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017807 capture response header Cache-Control len 8
17808
17809 # the Via header will report the next proxy's name
17810 capture response header Via len 20
17811
17812 # log the URL location during a redirection
17813 capture response header Location len 20
17814
17815 >>> Aug 9 20:26:09 localhost \
17816 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
17817 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
17818 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
17819 "GET http://fr.adserver.yahoo.com/"
17820
17821 >>> Aug 9 20:30:46 localhost \
17822 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
17823 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
17824 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010017825 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017826
17827 >>> Aug 9 20:30:46 localhost \
17828 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
17829 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
17830 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
17831 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010017832 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017833
17834
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200178358.9. Examples of logs
17836---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017837
17838These are real-world examples of logs accompanied with an explanation. Some of
17839them have been made up by hand. The syslog part has been removed for better
17840reading. Their sole purpose is to explain how to decipher them.
17841
17842 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
17843 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
17844 "HEAD / HTTP/1.0"
17845
17846 => long request (6.5s) entered by hand through 'telnet'. The server replied
17847 in 147 ms, and the session ended normally ('----')
17848
17849 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
17850 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
17851 0/9 "HEAD / HTTP/1.0"
17852
17853 => Idem, but the request was queued in the global queue behind 9 other
17854 requests, and waited there for 1230 ms.
17855
17856 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
17857 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
17858 "GET /image.iso HTTP/1.0"
17859
17860 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010017861 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017862 14 ms, 243 bytes of headers were sent to the client, and total time from
17863 accept to first data byte is 30 ms.
17864
17865 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
17866 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
17867 "GET /cgi-bin/bug.cgi? HTTP/1.0"
17868
Christopher Faulet87f1f3d2019-07-18 14:51:20 +020017869 => the proxy blocked a server response either because of an "http-response
17870 deny" rule, or because the response was improperly formatted and not
17871 HTTP-compliant, or because it blocked sensitive information which risked
17872 being cached. In this case, the response is replaced with a "502 bad
17873 gateway". The flags ("PH--") tell us that it was haproxy who decided to
17874 return the 502 and not the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017875
17876 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +010017877 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 +010017878
17879 => the client never completed its request and aborted itself ("C---") after
17880 8.5s, while the proxy was waiting for the request headers ("-R--").
17881 Nothing was sent to any server.
17882
17883 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
17884 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
17885
17886 => The client never completed its request, which was aborted by the
17887 time-out ("c---") after 50s, while the proxy was waiting for the request
Davor Ocelice9ed2812017-12-25 17:49:28 +010017888 headers ("-R--"). Nothing was sent to any server, but the proxy could
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017889 send a 408 return code to the client.
17890
17891 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
17892 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
17893
17894 => This log was produced with "option tcplog". The client timed out after
17895 5 seconds ("c----").
17896
17897 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
17898 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +010017899 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017900
17901 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017902 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017903 (config says 'retries 3'), and no redispatch (otherwise we would have
17904 seen "/+3"). Status code 503 was returned to the client. There were 115
17905 connections on this server, 202 connections on this proxy, and 205 on
17906 the global process. It is possible that the server refused the
17907 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +010017908
Willy Tarreau52b2d222011-09-07 23:48:48 +020017909
Christopher Fauletc3fe5332016-04-07 15:30:10 +0200179109. Supported filters
17911--------------------
17912
17913Here are listed officially supported filters with the list of parameters they
17914accept. Depending on compile options, some of these filters might be
17915unavailable. The list of available filters is reported in haproxy -vv.
17916
17917See also : "filter"
17918
179199.1. Trace
17920----------
17921
Christopher Faulet31bfe1f2016-12-09 17:42:38 +010017922filter trace [name <name>] [random-parsing] [random-forwarding] [hexdump]
Christopher Fauletc3fe5332016-04-07 15:30:10 +020017923
17924 Arguments:
17925 <name> is an arbitrary name that will be reported in
17926 messages. If no name is provided, "TRACE" is used.
17927
17928 <random-parsing> enables the random parsing of data exchanged between
17929 the client and the server. By default, this filter
17930 parses all available data. With this parameter, it
17931 only parses a random amount of the available data.
17932
Davor Ocelice9ed2812017-12-25 17:49:28 +010017933 <random-forwarding> enables the random forwarding of parsed data. By
Christopher Fauletc3fe5332016-04-07 15:30:10 +020017934 default, this filter forwards all previously parsed
17935 data. With this parameter, it only forwards a random
17936 amount of the parsed data.
17937
Davor Ocelice9ed2812017-12-25 17:49:28 +010017938 <hexdump> dumps all forwarded data to the server and the client.
Christopher Faulet31bfe1f2016-12-09 17:42:38 +010017939
Christopher Fauletc3fe5332016-04-07 15:30:10 +020017940This filter can be used as a base to develop new filters. It defines all
17941callbacks and print a message on the standard error stream (stderr) with useful
17942information for all of them. It may be useful to debug the activity of other
17943filters or, quite simply, HAProxy's activity.
17944
17945Using <random-parsing> and/or <random-forwarding> parameters is a good way to
17946tests the behavior of a filter that parses data exchanged between a client and
17947a server by adding some latencies in the processing.
17948
17949
179509.2. HTTP compression
17951---------------------
17952
17953filter compression
17954
17955The HTTP compression has been moved in a filter in HAProxy 1.7. "compression"
17956keyword must still be used to enable and configure the HTTP compression. And
Christopher Fauletb30b3102019-09-12 23:03:09 +020017957when no other filter is used, it is enough. When used with the cache or the
17958fcgi-app enabled, it is also enough. In this case, the compression is always
17959done after the response is stored in the cache. But it is mandatory to
17960explicitly use a filter line to enable the HTTP compression when at least one
17961filter other than the cache or the fcgi-app is used for the same
17962listener/frontend/backend. This is important to know the filters evaluation
17963order.
Christopher Fauletc3fe5332016-04-07 15:30:10 +020017964
Christopher Fauletb30b3102019-09-12 23:03:09 +020017965See also : "compression", section 9.4 about the cache filter and section 9.5
17966 about the fcgi-app filter.
Christopher Fauletc3fe5332016-04-07 15:30:10 +020017967
17968
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200179699.3. Stream Processing Offload Engine (SPOE)
17970--------------------------------------------
17971
17972filter spoe [engine <name>] config <file>
17973
17974 Arguments :
17975
17976 <name> is the engine name that will be used to find the right scope in
17977 the configuration file. If not provided, all the file will be
17978 parsed.
17979
17980 <file> is the path of the engine configuration file. This file can
17981 contain configuration of several engines. In this case, each
17982 part must be placed in its own scope.
17983
17984The Stream Processing Offload Engine (SPOE) is a filter communicating with
17985external components. It allows the offload of some specifics processing on the
Davor Ocelice9ed2812017-12-25 17:49:28 +010017986streams in tiered applications. These external components and information
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020017987exchanged with them are configured in dedicated files, for the main part. It
17988also requires dedicated backends, defined in HAProxy configuration.
17989
17990SPOE communicates with external components using an in-house binary protocol,
17991the Stream Processing Offload Protocol (SPOP).
17992
Tim Düsterhus4896c442016-11-29 02:15:19 +010017993For all information about the SPOE configuration and the SPOP specification, see
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020017994"doc/SPOE.txt".
17995
17996Important note:
17997 The SPOE filter is highly experimental for now and was not heavily
17998 tested. It is really not production ready. So use it carefully.
17999
Christopher Faulet99a17a22018-12-11 09:18:27 +0100180009.4. Cache
18001----------
18002
18003filter cache <name>
18004
18005 Arguments :
18006
18007 <name> is name of the cache section this filter will use.
18008
18009The cache uses a filter to store cacheable responses. The HTTP rules
18010"cache-store" and "cache-use" must be used to define how and when to use a
John Roeslerfb2fce12019-07-10 15:45:51 -050018011cache. By default the corresponding filter is implicitly defined. And when no
Christopher Fauletb30b3102019-09-12 23:03:09 +020018012other filters than fcgi-app or compression are used, it is enough. In such
18013case, the compression filter is always evaluated after the cache filter. But it
18014is mandatory to explicitly use a filter line to use a cache when at least one
18015filter other than the compression or the fcgi-app is used for the same
Christopher Faulet27d93c32018-12-15 22:32:02 +010018016listener/frontend/backend. This is important to know the filters evaluation
18017order.
Christopher Faulet99a17a22018-12-11 09:18:27 +010018018
Christopher Fauletb30b3102019-09-12 23:03:09 +020018019See also : section 9.2 about the compression filter, section 9.5 about the
18020 fcgi-app filter and section 6 about cache.
18021
18022
180239.5. Fcgi-app
18024-------------
18025
18026filter fcg-app <name>
18027
18028 Arguments :
18029
18030 <name> is name of the fcgi-app section this filter will use.
18031
18032The FastCGI application uses a filter to evaluate all custom parameters on the
18033request path, and to process the headers on the response path. the <name> must
18034reference an existing fcgi-app section. The directive "use-fcgi-app" should be
18035used to define the application to use. By default the corresponding filter is
18036implicitly defined. And when no other filters than cache or compression are
18037used, it is enough. But it is mandatory to explicitly use a filter line to a
18038fcgi-app when at least one filter other than the compression or the cache is
18039used for the same backend. This is important to know the filters evaluation
18040order.
18041
18042See also: "use-fcgi-app", section 9.2 about the compression filter, section 9.4
18043 about the cache filter and section 10 about FastCGI application.
18044
18045
1804610. FastCGI applications
18047-------------------------
18048
18049HAProxy is able to send HTTP requests to Responder FastCGI applications. This
18050feature was added in HAProxy 2.1. To do so, servers must be configured to use
18051the FastCGI protocol (using the keyword "proto fcgi" on the server line) and a
18052FastCGI application must be configured and used by the backend managing these
18053servers (using the keyword "use-fcgi-app" into the proxy section). Several
18054FastCGI applications may be defined, but only one can be used at a time by a
18055backend.
18056
18057HAProxy implements all features of the FastCGI specification for Responder
18058application. Especially it is able to multiplex several requests on a simple
18059connection.
18060
1806110.1. Setup
18062-----------
18063
1806410.1.1. Fcgi-app section
18065--------------------------
18066
18067fcgi-app <name>
18068 Declare a FastCGI application named <name>. To be valid, at least the
18069 document root must be defined.
18070
18071acl <aclname> <criterion> [flags] [operator] <value> ...
18072 Declare or complete an access list.
18073
18074 See "acl" keyword in section 4.2 and section 7 about ACL usage for
18075 details. ACLs defined for a FastCGI application are private. They cannot be
18076 used by any other application or by any proxy. In the same way, ACLs defined
18077 in any other section are not usable by a FastCGI application. However,
18078 Pre-defined ACLs are available.
18079
18080docroot <path>
18081 Define the document root on the remote host. <path> will be used to build
18082 the default value of FastCGI parameters SCRIPT_FILENAME and
18083 PATH_TRANSLATED. It is a mandatory setting.
18084
18085index <script-name>
18086 Define the script name that will be appended after an URI that ends with a
18087 slash ("/") to set the default value of the FastCGI parameter SCRIPT_NAME. It
18088 is an optional setting.
18089
18090 Example :
18091 index index.php
18092
18093log-stderr global
18094log-stderr <address> [len <length>] [format <format>]
18095 [sample <ranges>:<smp_size>] <facility> [<level> [<minlevel>]]
18096 Enable logging of STDERR messages reported by the FastCGI application.
18097
18098 See "log" keyword in section 4.2 for details. It is an optional setting. By
18099 default STDERR messages are ignored.
18100
18101pass-header <name> [ { if | unless } <condition> ]
18102 Specify the name of a request header which will be passed to the FastCGI
18103 application. It may optionally be followed by an ACL-based condition, in
18104 which case it will only be evaluated if the condition is true.
18105
18106 Most request headers are already available to the FastCGI application,
18107 prefixed with "HTTP_". Thus, this directive is only required to pass headers
18108 that are purposefully omitted. Currently, the headers "Authorization",
18109 "Proxy-Authorization" and hop-by-hop headers are omitted.
18110
18111 Note that the headers "Content-type" and "Content-length" are never passed to
18112 the FastCGI application because they are already converted into parameters.
18113
18114path-info <regex>
18115 Define a regular expression to extract the script-name and the path-info
18116 from the URI. Thus, <regex> should have two captures: the first one to
18117 capture the script name and the second one to capture the path-info. It is an
18118 optional setting. If it is not defined, no matching is performed on the
18119 URI. and the FastCGI parameters PATH_INFO and PATH_TRANSLATED are not filled.
18120
18121 Example :
18122 path-info ^(/.+\.php)(/.*)?$
18123
18124option get-values
18125no option get-values
18126 Enable or disable the retrieve of variables about connection management.
18127
18128 HAproxy is able to send the record FCGI_GET_VALUES on connection
18129 establishment to retrieve the value for following variables:
18130
18131 * FCGI_MAX_REQS The maximum number of concurrent requests this
18132 application will accept.
18133
William Lallemand93e548e2019-09-30 13:54:02 +020018134 * FCGI_MPXS_CONNS "0" if this application does not multiplex connections,
18135 "1" otherwise.
Christopher Fauletb30b3102019-09-12 23:03:09 +020018136
18137 Some FastCGI applications does not support this feature. Some others close
18138 the connexion immediately after sending their response. So, by default, this
18139 option is disabled.
18140
18141 Note that the maximum number of concurrent requests accepted by a FastCGI
18142 application is a connection variable. It only limits the number of streams
18143 per connection. If the global load must be limited on the application, the
18144 server parameters "maxconn" and "pool-max-conn" must be set. In addition, if
18145 an application does not support connection multiplexing, the maximum number
18146 of concurrent requests is automatically set to 1.
18147
18148option keep-conn
18149no option keep-conn
18150 Instruct the FastCGI application to keep the connection open or not after
18151 sending a response.
18152
18153 If disabled, the FastCGI application closes the connection after responding
18154 to this request. By default, this option is enabled.
18155
18156option max-reqs <reqs>
18157 Define the maximum number of concurrent requests this application will
18158 accept.
18159
18160 This option may be overwritten if the variable FCGI_MAX_REQS is retrieved
18161 during connection establishment. Furthermore, if the application does not
18162 support connection multiplexing, this option will be ignored. By default set
18163 to 1.
18164
18165option mpxs-conns
18166no option mpxs-conns
18167 Enable or disable the support of connection multiplexing.
18168
18169 This option may be overwritten if the variable FCGI_MPXS_CONNS is retrieved
18170 during connection establishment. It is disabled by default.
18171
18172set-param <name> <fmt> [ { if | unless } <condition> ]
18173 Set a FastCGI parameter that should be passed to this application. Its
18174 value, defined by <fmt> must follows the log-format rules (see section 8.2.4
18175 "Custom Log format"). It may optionally be followed by an ACL-based
18176 condition, in which case it will only be evaluated if the condition is true.
18177
18178 With this directive, it is possible to overwrite the value of default FastCGI
18179 parameters. If the value is evaluated to an empty string, the rule is
18180 ignored. These directives are evaluated in their declaration order.
18181
18182 Example :
18183 # PHP only, required if PHP was built with --enable-force-cgi-redirect
18184 set-param REDIRECT_STATUS 200
18185
18186 set-param PHP_AUTH_DIGEST %[req.hdr(Authorization)]
18187
18188
1818910.1.2. Proxy section
18190---------------------
18191
18192use-fcgi-app <name>
18193 Define the FastCGI application to use for the backend.
18194
18195 Arguments :
18196 <name> is the name of the FastCGI application to use.
18197
18198 This keyword is only available for HTTP proxies with the backend capability
18199 and with at least one FastCGI server. However, FastCGI servers can be mixed
18200 with HTTP servers. But except there is a good reason to do so, it is not
18201 recommended (see section 10.3 about the limitations for details). Only one
18202 application may be defined at a time per backend.
18203
18204 Note that, once a FastCGI application is referenced for a backend, depending
18205 on the configuration some processing may be done even if the request is not
18206 sent to a FastCGI server. Rules to set parameters or pass headers to an
18207 application are evaluated.
18208
18209
1821010.1.3. Example
18211---------------
18212
18213 frontend front-http
18214 mode http
18215 bind *:80
18216 bind *:
18217
18218 use_backend back-dynamic if { path_reg ^/.+\.php(/.*)?$ }
18219 default_backend back-static
18220
18221 backend back-static
18222 mode http
18223 server www A.B.C.D:80
18224
18225 backend back-dynamic
18226 mode http
18227 use-fcgi-app php-fpm
18228 server php-fpm A.B.C.D:9000 proto fcgi
18229
18230 fcgi-app php-fpm
18231 log-stderr global
18232 option keep-conn
18233
18234 docroot /var/www/my-app
18235 index index.php
18236 path-info ^(/.+\.php)(/.*)?$
18237
18238
1823910.2. Default parameters
18240------------------------
18241
18242A Responder FastCGI application has the same purpose as a CGI/1.1 program. In
18243the CGI/1.1 specification (RFC3875), several variables must be passed to the
18244scipt. So HAProxy set them and some others commonly used by FastCGI
18245applications. All these variables may be overwritten, with caution though.
18246
18247 +-------------------+-----------------------------------------------------+
18248 | AUTH_TYPE | Identifies the mechanism, if any, used by HAProxy |
18249 | | to authenticate the user. Concretely, only the |
18250 | | BASIC authentication mechanism is supported. |
18251 | | |
18252 +-------------------+-----------------------------------------------------+
18253 | CONTENT_LENGTH | Contains the size of the message-body attached to |
18254 | | the request. It means only requests with a known |
18255 | | size are considered as valid and sent to the |
18256 | | application. |
18257 | | |
18258 +-------------------+-----------------------------------------------------+
18259 | CONTENT_TYPE | Contains the type of the message-body attached to |
18260 | | the request. It may not be set. |
18261 | | |
18262 +-------------------+-----------------------------------------------------+
18263 | DOCUMENT_ROOT | Contains the document root on the remote host under |
18264 | | which the script should be executed, as defined in |
18265 | | the application's configuration. |
18266 | | |
18267 +-------------------+-----------------------------------------------------+
18268 | GATEWAY_INTERFACE | Contains the dialect of CGI being used by HAProxy |
18269 | | to communicate with the FastCGI application. |
18270 | | Concretely, it is set to "CGI/1.1". |
18271 | | |
18272 +-------------------+-----------------------------------------------------+
18273 | PATH_INFO | Contains the portion of the URI path hierarchy |
18274 | | following the part that identifies the script |
18275 | | itself. To be set, the directive "path-info" must |
18276 | | be defined. |
18277 | | |
18278 +-------------------+-----------------------------------------------------+
18279 | PATH_TRANSLATED | If PATH_INFO is set, it is its translated version. |
18280 | | It is the concatenation of DOCUMENT_ROOT and |
18281 | | PATH_INFO. If PATH_INFO is not set, this parameters |
18282 | | is not set too. |
18283 | | |
18284 +-------------------+-----------------------------------------------------+
18285 | QUERY_STRING | Contains the request's query string. It may not be |
18286 | | set. |
18287 | | |
18288 +-------------------+-----------------------------------------------------+
18289 | REMOTE_ADDR | Contains the network address of the client sending |
18290 | | the request. |
18291 | | |
18292 +-------------------+-----------------------------------------------------+
18293 | REMOTE_USER | Contains the user identification string supplied by |
18294 | | client as part of user authentication. |
18295 | | |
18296 +-------------------+-----------------------------------------------------+
18297 | REQUEST_METHOD | Contains the method which should be used by the |
18298 | | script to process the request. |
18299 | | |
18300 +-------------------+-----------------------------------------------------+
18301 | REQUEST_URI | Contains the request's URI. |
18302 | | |
18303 +-------------------+-----------------------------------------------------+
18304 | SCRIPT_FILENAME | Contains the absolute pathname of the script. it is |
18305 | | the concatenation of DOCUMENT_ROOT and SCRIPT_NAME. |
18306 | | |
18307 +-------------------+-----------------------------------------------------+
18308 | SCRIPT_NAME | Contains the name of the script. If the directive |
18309 | | "path-info" is defined, it is the first part of the |
18310 | | URI path hierarchy, ending with the script name. |
18311 | | Otherwise, it is the entire URI path. |
18312 | | |
18313 +-------------------+-----------------------------------------------------+
18314 | SERVER_NAME | Contains the name of the server host to which the |
18315 | | client request is directed. It is the value of the |
18316 | | header "Host", if defined. Otherwise, the |
18317 | | destination address of the connection on the client |
18318 | | side. |
18319 | | |
18320 +-------------------+-----------------------------------------------------+
18321 | SERVER_PORT | Contains the destination TCP port of the connection |
18322 | | on the client side, which is the port the client |
18323 | | connected to. |
18324 | | |
18325 +-------------------+-----------------------------------------------------+
18326 | SERVER_PROTOCOL | Contains the request's protocol. |
18327 | | |
18328 +-------------------+-----------------------------------------------------+
18329 | HTTPS | Set to a non-empty value ("on") if the script was |
18330 | | queried through the HTTPS protocol. |
18331 | | |
18332 +-------------------+-----------------------------------------------------+
18333
18334
1833510.3. Limitations
18336------------------
18337
18338The current implementation have some limitations. The first one is about the
18339way some request headers are hidden to the FastCGI applications. This happens
18340during the headers analysis, on the backend side, before the connection
18341establishment. At this stage, HAProxy know the backend is using a FastCGI
18342application but it don't know if the request will be routed to a FastCGI server
18343or not. But to hide request headers, it simply removes them from the HTX
18344message. So, if the request is finally routed to an HTTP server, it never see
18345these headers. For this reason, it is not recommended to mix FastCGI servers
18346and HTTP servers under the same backend.
18347
18348Similarly, the rules "set-param" and "pass-header" are evaluated during the
18349request headers analysis. So the evaluation is always performed, even if the
18350requests is finally forwarded to an HTTP server.
18351
18352About the rules "set-param", when a rule is applied, a pseudo header is added
18353into the HTX message. So, the same way than for HTTP header rewrites, it may
18354fail if the buffer is full. The rules "set-param" will compete with
18355"http-request" ones.
18356
18357Finally, all FastCGI params and HTTP headers are sent into a unique record
18358FCGI_PARAM. Encoding of this record must be done in one pass, otherwise a
18359processing error is returned. It means the record FCGI_PARAM, once encoded,
18360must not exceeds the size of a buffer. However, there is no reserve to respect
18361here.
William Lallemand86d0df02017-11-24 21:36:45 +010018362
Willy Tarreau0ba27502007-12-24 16:55:16 +010018363/*
18364 * Local variables:
18365 * fill-column: 79
18366 * End:
18367 */