blob: 208c11e51f5f8999bface7cae7f40a7979d5eec0 [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 Tarreaub3066502017-11-26 19:50:17 +01005 version 1.9
Willy Tarreau6a06a402007-07-15 20:15:28 +02006 willy tarreau
Willy Tarreau0b787922017-11-26 19:25:23 +01007 2017/11/26
Willy Tarreau6a06a402007-07-15 20:15:28 +02008
9
10This document covers the configuration language as implemented in the version
11specified above. It does not provide any hint, example or advice. For such
Willy Tarreau0ba27502007-12-24 16:55:16 +010012documentation, please refer to the Reference Manual or the Architecture Manual.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013The summary below is meant to help you search sections by name and navigate
14through 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
22 sometimes useful to prefix all output lines (logs, console outs) with 3
23 closing angle brackets ('>>>') in order to help get the difference between
24 inputs and outputs when it can become ambiguous. If you add sections,
25 please update the summary below for easier searching.
Willy 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
341.2.1. The Request line
351.2.2. The request headers
361.3. HTTP response
371.3.1. The Response line
381.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
Willy Tarreauc57f0e22009-05-10 13:12:33 +020054
554. Proxies
564.1. Proxy keywords matrix
574.2. Alphabetically sorted keywords reference
58
Willy Tarreau086fbf52012-09-24 20:34:51 +0200595. Bind and Server options
605.1. Bind options
615.2. Server and default-server options
Baptiste Assmann1fa66662015-04-14 00:28:47 +0200625.3. Server DNS resolution
635.3.1. Global overview
645.3.2. The resolvers section
Willy Tarreauc57f0e22009-05-10 13:12:33 +020065
666. HTTP header manipulation
67
Willy Tarreau74ca5042013-06-11 23:12:07 +0200687. Using ACLs and fetching samples
697.1. ACL basics
707.1.1. Matching booleans
717.1.2. Matching integers
727.1.3. Matching strings
737.1.4. Matching regular expressions (regexes)
747.1.5. Matching arbitrary data blocks
757.1.6. Matching IPv4 and IPv6 addresses
767.2. Using ACLs to form conditions
777.3. Fetching samples
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200787.3.1. Converters
797.3.2. Fetching samples from internal states
807.3.3. Fetching samples at Layer 4
817.3.4. Fetching samples at Layer 5
827.3.5. Fetching samples from buffer contents (Layer 6)
837.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +0200847.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020085
868. Logging
878.1. Log levels
888.2. Log formats
898.2.1. Default log format
908.2.2. TCP log format
918.2.3. HTTP log format
William Lallemand48940402012-01-30 16:47:22 +0100928.2.4. Custom log format
Willy Tarreau5f51e1a2012-12-03 18:40:10 +0100938.2.5. Error log format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200948.3. Advanced logging options
958.3.1. Disabling logging of external tests
968.3.2. Logging before waiting for the session to terminate
978.3.3. Raising log level upon errors
988.3.4. Disabling logging of successful connections
998.4. Timing events
1008.5. Session state at disconnection
1018.6. Non-printable characters
1028.7. Capturing HTTP cookies
1038.8. Capturing HTTP headers
1048.9. Examples of logs
105
Christopher Fauletc3fe5332016-04-07 15:30:10 +02001069. Supported filters
1079.1. Trace
1089.2. HTTP compression
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001099.3. Stream Processing Offload Engine (SPOE)
Christopher Fauletc3fe5332016-04-07 15:30:10 +0200110
William Lallemand86d0df02017-11-24 21:36:45 +010011110. Cache
Cyril Bonté7b888f12017-11-26 22:24:31 +010011210.1. Limitation
11310.2. Setup
11410.2.1. Cache section
11510.2.2. Proxy section
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200116
1171. Quick reminder about HTTP
118----------------------------
119
120When haproxy is running in HTTP mode, both the request and the response are
121fully analyzed and indexed, thus it becomes possible to build matching criteria
122on almost anything found in the contents.
123
124However, it is important to understand how HTTP requests and responses are
125formed, and how HAProxy decomposes them. It will then become easier to write
126correct rules and to debug existing configurations.
127
128
1291.1. The HTTP transaction model
130-------------------------------
131
132The HTTP protocol is transaction-driven. This means that each request will lead
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100133to one and only one response. Traditionally, a TCP connection is established
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200134from the client to the server, a request is sent by the client on the
135connection, the server responds and the connection is closed. A new request
136will involve a new connection :
137
138 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
139
140In this mode, called the "HTTP close" mode, there are as many connection
141establishments as there are HTTP transactions. Since the connection is closed
142by the server after the response, the client does not need to know the content
143length.
144
145Due to the transactional nature of the protocol, it was possible to improve it
146to avoid closing a connection between two subsequent transactions. In this mode
147however, it is mandatory that the server indicates the content length for each
148response so that the client does not wait indefinitely. For this, a special
149header is used: "Content-length". This mode is called the "keep-alive" mode :
150
151 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
152
153Its advantages are a reduced latency between transactions, and less processing
154power required on the server side. It is generally better than the close mode,
155but not always because the clients often limit their concurrent connections to
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200156a smaller value.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200157
Willy Tarreau95c4e142017-11-26 12:18:55 +0100158Another improvement in the communications is the pipelining mode. It still uses
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200159keep-alive, but the client does not wait for the first response to send the
160second request. This is useful for fetching large number of images composing a
161page :
162
163 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
164
165This can obviously have a tremendous benefit on performance because the network
166latency is eliminated between subsequent requests. Many HTTP agents do not
167correctly support pipelining since there is no way to associate a response with
168the corresponding request in HTTP. For this reason, it is mandatory for the
Cyril Bonté78caf842010-03-10 22:41:43 +0100169server to reply in the exact same order as the requests were received.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200170
Willy Tarreau95c4e142017-11-26 12:18:55 +0100171The next improvement is the multiplexed mode, as implemented in HTTP/2. This
172time, each transaction is assigned a single stream identifier, and all streams
173are multiplexed over an existing connection. Many requests can be sent in
174parallel by the client, and responses can arrive in any order since they also
175carry the stream identifier.
176
Willy Tarreau70dffda2014-01-30 03:07:23 +0100177By default HAProxy operates in keep-alive mode with regards to persistent
178connections: for each connection it processes each request and response, and
179leaves the connection idle on both sides between the end of a response and the
Willy Tarreau95c4e142017-11-26 12:18:55 +0100180start of a new request. When it receives HTTP/2 connections from a client, it
181processes all the requests in parallel and leaves the connection idling,
182waiting for new requests, just as if it was a keep-alive HTTP connection.
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200183
Willy Tarreau70dffda2014-01-30 03:07:23 +0100184HAProxy supports 5 connection modes :
185 - keep alive : all requests and responses are processed (default)
186 - tunnel : only the first request and response are processed,
187 everything else is forwarded with no analysis.
188 - passive close : tunnel with "Connection: close" added in both directions.
189 - server close : the server-facing connection is closed after the response.
190 - forced close : the connection is actively closed after end of response.
191
Willy Tarreau95c4e142017-11-26 12:18:55 +0100192For HTTP/2, the connection mode ressembles more the "server close" mode : given
193the independance of all streams, there is currently no place to hook the idle
194server connection after a response, so it is closed after the response. HTTP/2
195is only supported for incoming connections, not on connections going to
196servers.
197
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200198
1991.2. HTTP request
200-----------------
201
202First, let's consider this HTTP request :
203
204 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100205 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200206 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
207 2 Host: www.mydomain.com
208 3 User-agent: my small browser
209 4 Accept: image/jpeg, image/gif
210 5 Accept: image/png
211
212
2131.2.1. The Request line
214-----------------------
215
216Line 1 is the "request line". It is always composed of 3 fields :
217
218 - a METHOD : GET
219 - a URI : /serv/login.php?lang=en&profile=2
220 - a version tag : HTTP/1.1
221
222All of them are delimited by what the standard calls LWS (linear white spaces),
223which are commonly spaces, but can also be tabs or line feeds/carriage returns
224followed by spaces/tabs. The method itself cannot contain any colon (':') and
225is limited to alphabetic letters. All those various combinations make it
226desirable that HAProxy performs the splitting itself rather than leaving it to
227the user to write a complex or inaccurate regular expression.
228
229The URI itself can have several forms :
230
231 - A "relative URI" :
232
233 /serv/login.php?lang=en&profile=2
234
235 It is a complete URL without the host part. This is generally what is
236 received by servers, reverse proxies and transparent proxies.
237
238 - An "absolute URI", also called a "URL" :
239
240 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
241
242 It is composed of a "scheme" (the protocol name followed by '://'), a host
243 name or address, optionally a colon (':') followed by a port number, then
244 a relative URI beginning at the first slash ('/') after the address part.
245 This is generally what proxies receive, but a server supporting HTTP/1.1
246 must accept this form too.
247
248 - a star ('*') : this form is only accepted in association with the OPTIONS
249 method and is not relayable. It is used to inquiry a next hop's
250 capabilities.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100251
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200252 - an address:port combination : 192.168.0.12:80
253 This is used with the CONNECT method, which is used to establish TCP
254 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
255 other protocols too.
256
257In a relative URI, two sub-parts are identified. The part before the question
258mark is called the "path". It is typically the relative path to static objects
259on the server. The part after the question mark is called the "query string".
260It is mostly used with GET requests sent to dynamic scripts and is very
261specific to the language, framework or application in use.
262
Willy Tarreau95c4e142017-11-26 12:18:55 +0100263HTTP/2 doesn't convey a version information with the request, so the version is
264assumed to be the same as the one of the underlying protocol (ie: "HTTP/2").
265However, haproxy natively processes HTTP/1.x requests and headers, so requests
266received over an HTTP/2 connection are transcoded to HTTP/1.1 before being
267processed. This explains why they still appear as "HTTP/1.1" in haproxy's logs
268as well as in server logs.
269
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200270
2711.2.2. The request headers
272--------------------------
273
274The headers start at the second line. They are composed of a name at the
275beginning of the line, immediately followed by a colon (':'). Traditionally,
276an LWS is added after the colon but that's not required. Then come the values.
277Multiple identical headers may be folded into one single line, delimiting the
278values with commas, provided that their order is respected. This is commonly
279encountered in the "Cookie:" field. A header may span over multiple lines if
280the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
281define a total of 3 values for the "Accept:" header.
282
283Contrary to a common mis-conception, header names are not case-sensitive, and
284their values are not either if they refer to other header names (such as the
Willy Tarreau95c4e142017-11-26 12:18:55 +0100285"Connection:" header). In HTTP/2, header names are always sent in lower case,
286as can be seen when running in debug mode.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200287
288The end of the headers is indicated by the first empty line. People often say
289that it's a double line feed, which is not exact, even if a double line feed
290is one valid form of empty line.
291
292Fortunately, HAProxy takes care of all these complex combinations when indexing
293headers, checking values and counting them, so there is no reason to worry
294about the way they could be written, but it is important not to accuse an
295application of being buggy if it does unusual, valid things.
296
297Important note:
Lukas Tribus23953682017-04-28 13:24:30 +0000298 As suggested by RFC7231, HAProxy normalizes headers by replacing line breaks
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200299 in the middle of headers by LWS in order to join multi-line headers. This
300 is necessary for proper analysis and helps less capable HTTP parsers to work
301 correctly and not to be fooled by such complex constructs.
302
303
3041.3. HTTP response
305------------------
306
307An HTTP response looks very much like an HTTP request. Both are called HTTP
308messages. Let's consider this HTTP response :
309
310 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100311 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200312 1 HTTP/1.1 200 OK
313 2 Content-length: 350
314 3 Content-Type: text/html
315
Willy Tarreau816b9792009-09-15 21:25:21 +0200316As a special case, HTTP supports so called "Informational responses" as status
317codes 1xx. These messages are special in that they don't convey any part of the
318response, they're just used as sort of a signaling message to ask a client to
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100319continue to post its request for instance. In the case of a status 100 response
320the requested information will be carried by the next non-100 response message
321following the informational one. This implies that multiple responses may be
322sent to a single request, and that this only works when keep-alive is enabled
323(1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to
324correctly forward and skip them, and only process the next non-100 response. As
325such, these messages are neither logged nor transformed, unless explicitly
326state otherwise. Status 101 messages indicate that the protocol is changing
327over the same connection and that haproxy must switch to tunnel mode, just as
328if a CONNECT had occurred. Then the Upgrade header would contain additional
329information about the type of protocol the connection is switching to.
Willy Tarreau816b9792009-09-15 21:25:21 +0200330
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200331
3321.3.1. The Response line
333------------------------
334
335Line 1 is the "response line". It is always composed of 3 fields :
336
337 - a version tag : HTTP/1.1
338 - a status code : 200
339 - a reason : OK
340
341The status code is always 3-digit. The first digit indicates a general status :
Willy Tarreau816b9792009-09-15 21:25:21 +0200342 - 1xx = informational message to be skipped (eg: 100, 101)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200343 - 2xx = OK, content is following (eg: 200, 206)
344 - 3xx = OK, no content following (eg: 302, 304)
345 - 4xx = error caused by the client (eg: 401, 403, 404)
346 - 5xx = error caused by the server (eg: 500, 502, 503)
347
Lukas Tribus23953682017-04-28 13:24:30 +0000348Please refer to RFC7231 for the detailed meaning of all such codes. The
Willy Tarreaud72758d2010-01-12 10:42:19 +0100349"reason" field is just a hint, but is not parsed by clients. Anything can be
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200350found there, but it's a common practice to respect the well-established
351messages. It can be composed of one or multiple words, such as "OK", "Found",
352or "Authentication Required".
353
354Haproxy may emit the following status codes by itself :
355
356 Code When / reason
357 200 access to stats page, and when replying to monitoring requests
358 301 when performing a redirection, depending on the configured code
359 302 when performing a redirection, depending on the configured code
360 303 when performing a redirection, depending on the configured code
Willy Tarreaub67fdc42013-03-29 19:28:11 +0100361 307 when performing a redirection, depending on the configured code
362 308 when performing a redirection, depending on the configured code
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200363 400 for an invalid or too large request
364 401 when an authentication is required to perform the action (when
365 accessing the stats page)
366 403 when a request is forbidden by a "block" ACL or "reqdeny" filter
367 408 when the request timeout strikes before the request is complete
368 500 when haproxy encounters an unrecoverable internal error, such as a
369 memory allocation failure, which should never happen
370 502 when the server returns an empty, invalid or incomplete response, or
371 when an "rspdeny" filter blocks the response.
372 503 when no server was available to handle the request, or in response to
373 monitoring requests which match the "monitor fail" condition
374 504 when the response timeout strikes before the server responds
375
376The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3774.2).
378
379
3801.3.2. The response headers
381---------------------------
382
383Response headers work exactly like request headers, and as such, HAProxy uses
384the same parsing function for both. Please refer to paragraph 1.2.2 for more
385details.
386
387
3882. Configuring HAProxy
389----------------------
390
3912.1. Configuration file format
392------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200393
394HAProxy's configuration process involves 3 major sources of parameters :
395
396 - the arguments from the command-line, which always take precedence
397 - the "global" section, which sets process-wide parameters
398 - the proxies sections which can take form of "defaults", "listen",
399 "frontend" and "backend".
400
Willy Tarreau0ba27502007-12-24 16:55:16 +0100401The configuration file syntax consists in lines beginning with a keyword
402referenced in this manual, optionally followed by one or several parameters
William Lallemandf9873ba2015-05-05 17:37:14 +0200403delimited by spaces.
Willy Tarreau0ba27502007-12-24 16:55:16 +0100404
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200405
William Lallemandf9873ba2015-05-05 17:37:14 +02004062.2. Quoting and escaping
407-------------------------
408
409HAProxy's configuration introduces a quoting and escaping system similar to
410many programming languages. The configuration file supports 3 types: escaping
411with a backslash, weak quoting with double quotes, and strong quoting with
412single quotes.
413
414If spaces have to be entered in strings, then they must be escaped by preceding
415them by a backslash ('\') or by quoting them. Backslashes also have to be
416escaped by doubling or strong quoting them.
417
418Escaping is achieved by preceding a special character by a backslash ('\'):
419
420 \ to mark a space and differentiate it from a delimiter
421 \# to mark a hash and differentiate it from a comment
422 \\ to use a backslash
423 \' to use a single quote and differentiate it from strong quoting
424 \" to use a double quote and differentiate it from weak quoting
425
426Weak quoting is achieved by using double quotes (""). Weak quoting prevents
427the interpretation of:
428
429 space as a parameter separator
430 ' single quote as a strong quoting delimiter
431 # hash as a comment start
432
William Lallemandb2f07452015-05-12 14:27:13 +0200433Weak quoting permits the interpretation of variables, if you want to use a non
434-interpreted dollar within a double quoted string, you should escape it with a
435backslash ("\$"), it does not work outside weak quoting.
436
437Interpretation of escaping and special characters are not prevented by weak
William Lallemandf9873ba2015-05-05 17:37:14 +0200438quoting.
439
440Strong quoting is achieved by using single quotes (''). Inside single quotes,
441nothing is interpreted, it's the efficient way to quote regexes.
442
443Quoted and escaped strings are replaced in memory by their interpreted
444equivalent, it allows you to perform concatenation.
445
446 Example:
447 # those are equivalents:
448 log-format %{+Q}o\ %t\ %s\ %{-Q}r
449 log-format "%{+Q}o %t %s %{-Q}r"
450 log-format '%{+Q}o %t %s %{-Q}r'
451 log-format "%{+Q}o %t"' %s %{-Q}r'
452 log-format "%{+Q}o %t"' %s'\ %{-Q}r
453
454 # those are equivalents:
455 reqrep "^([^\ :]*)\ /static/(.*)" \1\ /\2
456 reqrep "^([^ :]*)\ /static/(.*)" '\1 /\2'
457 reqrep "^([^ :]*)\ /static/(.*)" "\1 /\2"
458 reqrep "^([^ :]*)\ /static/(.*)" "\1\ /\2"
459
460
William Lallemandb2f07452015-05-12 14:27:13 +02004612.3. Environment variables
462--------------------------
463
464HAProxy's configuration supports environment variables. Those variables are
465interpreted only within double quotes. Variables are expanded during the
466configuration parsing. Variable names must be preceded by a dollar ("$") and
467optionally enclosed with braces ("{}") similarly to what is done in Bourne
468shell. Variable names can contain alphanumerical characters or the character
469underscore ("_") but should not start with a digit.
470
471 Example:
472
473 bind "fd@${FD_APP1}"
474
475 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
476
477 user "$HAPROXY_USER"
478
479
4802.4. Time format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200481----------------
482
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100483Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100484values are generally expressed in milliseconds (unless explicitly stated
485otherwise) but may be expressed in any other unit by suffixing the unit to the
486numeric value. It is important to consider this because it will not be repeated
487for every keyword. Supported units are :
488
489 - us : microseconds. 1 microsecond = 1/1000000 second
490 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
491 - s : seconds. 1s = 1000ms
492 - m : minutes. 1m = 60s = 60000ms
493 - h : hours. 1h = 60m = 3600s = 3600000ms
494 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
495
496
Lukas Tribusaa83a312017-03-21 09:25:09 +00004972.5. Examples
Patrick Mezard35da19c2010-06-12 17:02:47 +0200498-------------
499
500 # Simple configuration for an HTTP proxy listening on port 80 on all
501 # interfaces and forwarding requests to a single backend "servers" with a
502 # single server "server1" listening on 127.0.0.1:8000
503 global
504 daemon
505 maxconn 256
506
507 defaults
508 mode http
509 timeout connect 5000ms
510 timeout client 50000ms
511 timeout server 50000ms
512
513 frontend http-in
514 bind *:80
515 default_backend servers
516
517 backend servers
518 server server1 127.0.0.1:8000 maxconn 32
519
520
521 # The same configuration defined with a single listen block. Shorter but
522 # less expressive, especially in HTTP mode.
523 global
524 daemon
525 maxconn 256
526
527 defaults
528 mode http
529 timeout connect 5000ms
530 timeout client 50000ms
531 timeout server 50000ms
532
533 listen http-in
534 bind *:80
535 server server1 127.0.0.1:8000 maxconn 32
536
537
538Assuming haproxy is in $PATH, test these configurations in a shell with:
539
Willy Tarreauccb289d2010-12-11 20:19:38 +0100540 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200541
542
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005433. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200544--------------------
545
546Parameters in the "global" section are process-wide and often OS-specific. They
547are generally set once for all and do not need being changed once correct. Some
548of them have command-line equivalents.
549
550The following keywords are supported in the "global" section :
551
552 * Process management and security
Emeric Brunc8e8d122012-10-02 18:42:10 +0200553 - ca-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200554 - chroot
Emeric Brunc8e8d122012-10-02 18:42:10 +0200555 - crt-base
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200556 - cpu-map
Willy Tarreau6a06a402007-07-15 20:15:28 +0200557 - daemon
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200558 - description
559 - deviceatlas-json-file
560 - deviceatlas-log-level
561 - deviceatlas-separator
562 - deviceatlas-properties-cookie
Simon Horman98637e52014-06-20 12:30:16 +0900563 - external-check
Willy Tarreau6a06a402007-07-15 20:15:28 +0200564 - gid
565 - group
Cyril Bonté203ec5a2017-03-23 22:44:13 +0100566 - hard-stop-after
Willy Tarreau6a06a402007-07-15 20:15:28 +0200567 - log
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200568 - log-tag
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100569 - log-send-hostname
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200570 - lua-load
Willy Tarreau6a06a402007-07-15 20:15:28 +0200571 - nbproc
Christopher Fauletbe0faa22017-08-29 15:37:10 +0200572 - nbthread
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200573 - node
Willy Tarreau6a06a402007-07-15 20:15:28 +0200574 - pidfile
Willy Tarreau1d549722016-02-16 12:41:57 +0100575 - presetenv
576 - resetenv
Willy Tarreau6a06a402007-07-15 20:15:28 +0200577 - uid
578 - ulimit-n
579 - user
Willy Tarreau1d549722016-02-16 12:41:57 +0100580 - setenv
Willy Tarreaufbee7132007-10-18 13:53:22 +0200581 - stats
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200582 - ssl-default-bind-ciphers
583 - ssl-default-bind-options
584 - ssl-default-server-ciphers
585 - ssl-default-server-options
586 - ssl-dh-param-file
Emeric Brun850efd52014-01-29 12:24:34 +0100587 - ssl-server-verify
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100588 - unix-bind
Willy Tarreau1d549722016-02-16 12:41:57 +0100589 - unsetenv
Thomas Holmesdb04f192015-05-18 13:21:39 +0100590 - 51degrees-data-file
591 - 51degrees-property-name-list
Dragan Dosen93b38d92015-06-29 16:43:25 +0200592 - 51degrees-property-separator
Dragan Dosenae6d39a2015-06-29 16:43:27 +0200593 - 51degrees-cache-size
scientiamobiled0027ed2016-11-04 10:55:08 +0100594 - wurfl-data-file
595 - wurfl-information-list
596 - wurfl-information-list-separator
597 - wurfl-engine-mode
598 - wurfl-cache-size
599 - wurfl-useragent-priority
Willy Tarreaud72758d2010-01-12 10:42:19 +0100600
Willy Tarreau6a06a402007-07-15 20:15:28 +0200601 * Performance tuning
Willy Tarreau1746eec2014-04-25 10:46:47 +0200602 - max-spread-checks
Willy Tarreau6a06a402007-07-15 20:15:28 +0200603 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +0200604 - maxconnrate
William Lallemandd85f9172012-11-09 17:05:39 +0100605 - maxcomprate
William Lallemand072a2bf2012-11-20 17:01:01 +0100606 - maxcompcpuusage
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100607 - maxpipes
Willy Tarreau93e7c002013-10-07 18:51:07 +0200608 - maxsessrate
Willy Tarreau403edff2012-09-06 11:58:37 +0200609 - maxsslconn
Willy Tarreaue43d5322013-10-07 20:01:52 +0200610 - maxsslrate
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200611 - maxzlibmem
Willy Tarreau6a06a402007-07-15 20:15:28 +0200612 - noepoll
613 - nokqueue
614 - nopoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100615 - nosplice
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300616 - nogetaddrinfo
Lukas Tribusa0bcbdc2016-09-12 21:42:20 +0000617 - noreuseport
Willy Tarreaufe255b72007-10-14 23:09:26 +0200618 - spread-checks
Baptiste Assmann5626f482015-08-23 10:00:10 +0200619 - server-state-base
Baptiste Assmannef1f0fc2015-08-23 10:06:39 +0200620 - server-state-file
Grant Zhang872f9c22017-01-21 01:10:18 +0000621 - ssl-engine
Grant Zhangfa6c7ee2017-01-14 01:42:15 +0000622 - ssl-mode-async
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200623 - tune.buffers.limit
624 - tune.buffers.reserve
Willy Tarreau27a674e2009-08-17 07:23:33 +0200625 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200626 - tune.chksize
William Lallemandf3747832012-11-09 12:33:10 +0100627 - tune.comp.maxlevel
Willy Tarreaufe20e5b2017-07-27 11:42:14 +0200628 - tune.h2.header-table-size
Willy Tarreaue6baec02017-07-27 11:45:11 +0200629 - tune.h2.initial-window-size
Willy Tarreau5242ef82017-07-27 11:47:28 +0200630 - tune.h2.max-concurrent-streams
Willy Tarreau193b8c62012-11-22 00:17:38 +0100631 - tune.http.cookielen
Stéphane Cottin23e9e932017-05-18 08:58:41 +0200632 - tune.http.logurilen
Willy Tarreauac1932d2011-10-24 19:14:41 +0200633 - tune.http.maxhdr
Willy Tarreau7e312732014-02-12 16:35:14 +0100634 - tune.idletimer
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100635 - tune.lua.forced-yield
Willy Tarreau32f61e22015-03-18 17:54:59 +0100636 - tune.lua.maxmem
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100637 - tune.lua.session-timeout
638 - tune.lua.task-timeout
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +0200639 - tune.lua.service-timeout
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100640 - tune.maxaccept
641 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200642 - tune.maxrewrite
Willy Tarreauf3045d22015-04-29 16:24:50 +0200643 - tune.pattern.cache-size
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200644 - tune.pipesize
Willy Tarreaue803de22010-01-21 17:43:04 +0100645 - tune.rcvbuf.client
646 - tune.rcvbuf.server
Willy Tarreaub22fc302015-12-14 12:04:35 +0100647 - tune.recv_enough
Willy Tarreaue803de22010-01-21 17:43:04 +0100648 - tune.sndbuf.client
649 - tune.sndbuf.server
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100650 - tune.ssl.cachesize
Willy Tarreaubfd59462013-02-21 07:46:09 +0100651 - tune.ssl.lifetime
Emeric Brun8dc60392014-05-09 13:52:00 +0200652 - tune.ssl.force-private-cache
Willy Tarreaubfd59462013-02-21 07:46:09 +0100653 - tune.ssl.maxrecord
Remi Gacognef46cd6e2014-06-12 14:58:40 +0200654 - tune.ssl.default-dh-param
Christopher Faulet31af49d2015-06-09 17:29:50 +0200655 - tune.ssl.ssl-ctx-cache-size
Thierry FOURNIER5bf77322017-02-25 12:45:22 +0100656 - tune.ssl.capture-cipherlist-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +0200657 - tune.vars.global-max-size
Christopher Fauletff2613e2016-11-09 11:36:17 +0100658 - tune.vars.proc-max-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +0200659 - tune.vars.reqres-max-size
660 - tune.vars.sess-max-size
661 - tune.vars.txn-max-size
William Lallemanda509e4c2012-11-07 16:54:34 +0100662 - tune.zlib.memlevel
663 - tune.zlib.windowsize
Willy Tarreaud72758d2010-01-12 10:42:19 +0100664
Willy Tarreau6a06a402007-07-15 20:15:28 +0200665 * Debugging
666 - debug
667 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200668
669
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006703.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200671------------------------------------
672
Emeric Brunc8e8d122012-10-02 18:42:10 +0200673ca-base <dir>
674 Assigns a default directory to fetch SSL CA certificates and CRLs from when a
Emeric Brunfd33a262012-10-11 16:28:27 +0200675 relative path is used with "ca-file" or "crl-file" directives. Absolute
676 locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200677
Willy Tarreau6a06a402007-07-15 20:15:28 +0200678chroot <jail dir>
679 Changes current directory to <jail dir> and performs a chroot() there before
680 dropping privileges. This increases the security level in case an unknown
681 vulnerability would be exploited, since it would make it very hard for the
682 attacker to exploit the system. This only works when the process is started
683 with superuser privileges. It is important to ensure that <jail_dir> is both
684 empty and unwritable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100685
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100686cpu-map [auto:]<process-set>[/<thread-set>] <cpu-set>...
687 On Linux 2.6 and above, it is possible to bind a process or a thread to a
688 specific CPU set. This means that the process or the thread will never run on
689 other CPUs. The "cpu-map" directive specifies CPU sets for process or thread
690 sets. The first argument is a process set, eventually followed by a thread
691 set. These sets have the format
692
693 all | odd | even | number[-[number]]
694
695 <number>> must be a number between 1 and 32 or 64, depending on the machine's
696 word size. any process IDs above nbrpoc and any thread IDs above nbthread are
697 ignored. It is possible to specify a range with two such number delimited by
698 a dash ('-'). It also is possible to specify all processes at once using
Christopher Faulet1dcb9cb2017-11-22 10:24:40 +0100699 "all", only odd numbers using "odd" or even numbers using "even", just like
700 with the "bind-process" directive. The second and forthcoming arguments are
701 CPU sets. Each CPU set is either a unique number between 0 and 31 or 63 or a
702 range with two such numbers delimited by a dash ('-'). Multiple CPU numbers
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100703 or ranges may be specified, and the processes or threads will be allowed to
704 bind to all of them. Obviously, multiple "cpu-map" directives may be
705 specified. Each "cpu-map" directive will replace the previous ones when they
706 overlap. A thread will be bound on the intersection of its mapping and the
707 one of the process on which it is attached. If the intersection is null, no
708 specific binding will be set for the thread.
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100709
Christopher Fauletff4121f2017-11-22 16:38:49 +0100710 Ranges can be partially defined. The higher bound can be omitted. In such
711 case, it is replaced by the corresponding maximum value, 32 or 64 depending
712 on the machine's word size.
713
Christopher Faulet26028f62017-11-22 15:01:51 +0100714 The prefix "auto:" can be added before the process set to let HAProxy
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100715 automatically bind a process or a thread to a CPU by incrementing
716 process/thread and CPU sets. To be valid, both sets must have the same
717 size. No matter the declaration order of the CPU sets, it will be bound from
718 the lowest to the highest bound. Having a process and a thread range with the
719 "auto:" prefix is not supported. Only one range is supported, the other one
720 must be a fixed number.
Christopher Faulet26028f62017-11-22 15:01:51 +0100721
722 Examples:
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100723 cpu-map 1-4 0-3 # bind processes 1 to 4 on the first 4 CPUs
724
725 cpu-map 1/all 0-3 # bind all threads of the first process on the
726 # first 4 CPUs
727
728 cpu-map 1- 0- # will be replaced by "cpu-map 1-64 0-63"
729 # or "cpu-map 1-32 0-31" depending on the machine's
730 # word size.
731
Christopher Faulet26028f62017-11-22 15:01:51 +0100732 # all these lines bind the process 1 to the cpu 0, the process 2 to cpu 1
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100733 # and so on.
Christopher Faulet26028f62017-11-22 15:01:51 +0100734 cpu-map auto:1-4 0-3
735 cpu-map auto:1-4 0-1 2-3
736 cpu-map auto:1-4 3 2 1 0
737
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100738 # all these lines bind the thread 1 to the cpu 0, the thread 2 to cpu 1
739 # and so on.
740 cpu-map auto:1/1-4 0-3
741 cpu-map auto:1/1-4 0-1 2-3
742 cpu-map auto:1/1-4 3 2 1 0
743
Christopher Faulet26028f62017-11-22 15:01:51 +0100744 # bind each process to exaclty one CPU using all/odd/even keyword
745 cpu-map auto:all 0-63
746 cpu-map auto:even 0-31
747 cpu-map auto:odd 32-63
748
749 # invalid cpu-map because process and CPU sets have different sizes.
750 cpu-map auto:1-4 0 # invalid
751 cpu-map auto:1 0-3 # invalid
752
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100753 # invalid cpu-map because automatic binding is used with a process range
754 # and a thread range.
755 cpu-map auto:all/all 0 # invalid
756 cpu-map auto:all/1-4 0 # invalid
757 cpu-map auto:1-4/all 0 # invalid
758
Emeric Brunc8e8d122012-10-02 18:42:10 +0200759crt-base <dir>
760 Assigns a default directory to fetch SSL certificates from when a relative
761 path is used with "crtfile" directives. Absolute locations specified after
762 "crtfile" prevail and ignore "crt-base".
763
Willy Tarreau6a06a402007-07-15 20:15:28 +0200764daemon
765 Makes the process fork into background. This is the recommended mode of
766 operation. It is equivalent to the command line "-D" argument. It can be
Lukas Tribusf46bf952017-11-21 12:39:34 +0100767 disabled by the command line "-db" argument. This option is ignored in
768 systemd mode.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200769
David Carlier8167f302015-06-01 13:50:06 +0200770deviceatlas-json-file <path>
771 Sets the path of the DeviceAtlas JSON data file to be loaded by the API.
772 The path must be a valid JSON data file and accessible by Haproxy process.
773
774deviceatlas-log-level <value>
775 Sets the level of informations returned by the API. This directive is
776 optional and set to 0 by default if not set.
777
778deviceatlas-separator <char>
779 Sets the character separator for the API properties results. This directive
780 is optional and set to | by default if not set.
781
Cyril Bonté0306c4a2015-10-26 22:37:38 +0100782deviceatlas-properties-cookie <name>
Cyril Bonté307ee1e2015-09-28 23:16:06 +0200783 Sets the client cookie's name used for the detection if the DeviceAtlas
784 Client-side component was used during the request. This directive is optional
785 and set to DAPROPS by default if not set.
David Carlier29b3ca32015-09-25 14:09:21 +0100786
Simon Horman98637e52014-06-20 12:30:16 +0900787external-check
788 Allows the use of an external agent to perform health checks.
789 This is disabled by default as a security precaution.
790 See "option external-check".
791
Willy Tarreau6a06a402007-07-15 20:15:28 +0200792gid <number>
793 Changes the process' group ID to <number>. It is recommended that the group
794 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
795 be started with a user belonging to this group, or with superuser privileges.
Michael Schererab012dd2013-01-12 18:35:19 +0100796 Note that if haproxy is started from a user having supplementary groups, it
797 will only be able to drop these groups if started with superuser privileges.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200798 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100799
Cyril Bonté203ec5a2017-03-23 22:44:13 +0100800hard-stop-after <time>
801 Defines the maximum time allowed to perform a clean soft-stop.
802
803 Arguments :
804 <time> is the maximum time (by default in milliseconds) for which the
805 instance will remain alive when a soft-stop is received via the
806 SIGUSR1 signal.
807
808 This may be used to ensure that the instance will quit even if connections
809 remain opened during a soft-stop (for example with long timeouts for a proxy
810 in tcp mode). It applies both in TCP and HTTP mode.
811
812 Example:
813 global
814 hard-stop-after 30s
815
Willy Tarreau6a06a402007-07-15 20:15:28 +0200816group <group name>
817 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
818 See also "gid" and "user".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100819
Dragan Dosen7ad31542015-09-28 17:16:47 +0200820log <address> [len <length>] [format <format>] <facility> [max level [min level]]
Willy Tarreau6a06a402007-07-15 20:15:28 +0200821 Adds a global syslog server. Up to two global servers can be defined. They
822 will receive logs for startups and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100823 configured with "log global".
824
825 <address> can be one of:
826
Willy Tarreau2769aa02007-12-27 18:26:09 +0100827 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100828 no port is specified, 514 is used by default (the standard syslog
829 port).
830
David du Colombier24bb5f52011-03-17 10:40:23 +0100831 - An IPv6 address followed by a colon and optionally a UDP port. If
832 no port is specified, 514 is used by default (the standard syslog
833 port).
834
Robert Tsai81ae1952007-12-05 10:47:29 +0100835 - A filesystem path to a UNIX domain socket, keeping in mind
836 considerations for chroot (be sure the path is accessible inside
837 the chroot) and uid/gid (be sure the path is appropriately
838 writeable).
839
William Lallemandb2f07452015-05-12 14:27:13 +0200840 You may want to reference some environment variables in the address
841 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +0100842
Willy Tarreau18324f52014-06-27 18:10:07 +0200843 <length> is an optional maximum line length. Log lines larger than this value
844 will be truncated before being sent. The reason is that syslog
845 servers act differently on log line length. All servers support the
846 default value of 1024, but some servers simply drop larger lines
847 while others do log them. If a server supports long lines, it may
848 make sense to set this value here in order to avoid truncating long
849 lines. Similarly, if a server drops long lines, it is preferable to
850 truncate them before sending them. Accepted values are 80 to 65535
851 inclusive. The default value of 1024 is generally fine for all
852 standard usages. Some specific cases of long captures or
Stéphane Cottin23e9e932017-05-18 08:58:41 +0200853 JSON-formated logs may require larger values. You may also need to
854 increase "tune.http.logurilen" if your request uris are truncated.
Willy Tarreau18324f52014-06-27 18:10:07 +0200855
Dragan Dosen7ad31542015-09-28 17:16:47 +0200856 <format> is the log format used when generating syslog messages. It may be
857 one of the following :
858
859 rfc3164 The RFC3164 syslog message format. This is the default.
860 (https://tools.ietf.org/html/rfc3164)
861
862 rfc5424 The RFC5424 syslog message format.
863 (https://tools.ietf.org/html/rfc5424)
864
Robert Tsai81ae1952007-12-05 10:47:29 +0100865 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200866
867 kern user mail daemon auth syslog lpr news
868 uucp cron auth2 ftp ntp audit alert cron2
869 local0 local1 local2 local3 local4 local5 local6 local7
870
871 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200872 all messages are sent. If a maximum level is specified, only messages with a
873 severity at least as important as this level will be sent. An optional minimum
874 level can be specified. If it is set, logs emitted with a more severe level
875 than this one will be capped to this level. This is used to avoid sending
876 "emerg" messages on all terminals on some default syslog configurations.
877 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200878
Cyril Bontédc4d9032012-04-08 21:57:39 +0200879 emerg alert crit err warning notice info debug
Willy Tarreau6a06a402007-07-15 20:15:28 +0200880
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100881log-send-hostname [<string>]
882 Sets the hostname field in the syslog header. If optional "string" parameter
883 is set the header is set to the string contents, otherwise uses the hostname
884 of the system. Generally used if one is not relaying logs through an
885 intermediate syslog server or for simply customizing the hostname printed in
886 the logs.
887
Kevinm48936af2010-12-22 16:08:21 +0000888log-tag <string>
889 Sets the tag field in the syslog header to this string. It defaults to the
890 program name as launched from the command line, which usually is "haproxy".
891 Sometimes it can be useful to differentiate between multiple processes
Willy Tarreau094af4e2015-01-07 15:03:42 +0100892 running on the same host. See also the per-proxy "log-tag" directive.
Kevinm48936af2010-12-22 16:08:21 +0000893
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100894lua-load <file>
895 This global directive loads and executes a Lua file. This directive can be
896 used multiple times.
897
William Lallemand4cfede82017-11-24 22:02:34 +0100898master-worker [no-exit-on-failure]
William Lallemande202b1e2017-06-01 17:38:56 +0200899 Master-worker mode. It is equivalent to the command line "-W" argument.
900 This mode will launch a "master" which will monitor the "workers". Using
901 this mode, you can reload HAProxy directly by sending a SIGUSR2 signal to
902 the master. The master-worker mode is compatible either with the foreground
903 or daemon mode. It is recommended to use this mode with multiprocess and
904 systemd.
William Lallemand4cfede82017-11-24 22:02:34 +0100905 By default, if a worker exits with a bad return code, in the case of a
906 segfault for example, all workers will be killed, and the master will leave.
907 It is convenient to combine this behavior with Restart=on-failure in a
908 systemd unit file in order to relaunch the whole process. If you don't want
909 this behavior, you must use the keyword "no-exit-on-failure".
William Lallemande202b1e2017-06-01 17:38:56 +0200910
William Lallemand4cfede82017-11-24 22:02:34 +0100911 See also "-W" in the management guide.
William Lallemande202b1e2017-06-01 17:38:56 +0200912
Willy Tarreau6a06a402007-07-15 20:15:28 +0200913nbproc <number>
914 Creates <number> processes when going daemon. This requires the "daemon"
915 mode. By default, only one process is created, which is the recommended mode
916 of operation. For systems limited to small sets of file descriptors per
917 process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES
918 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon".
919
Christopher Fauletbe0faa22017-08-29 15:37:10 +0200920nbthread <number>
921 This setting is only available when support for threads was built in. It
922 creates <number> threads for each created processes. It means if HAProxy is
923 started in foreground, it only creates <number> threads for the first
924 process. FOR NOW, THREADS SUPPORT IN HAPROXY IS HIGHLY EXPERIMENTAL AND IT
925 MUST BE ENABLED WITH CAUTION AND AT YOUR OWN RISK. See also "nbproc".
926
Willy Tarreau6a06a402007-07-15 20:15:28 +0200927pidfile <pidfile>
928 Writes pids of all daemons into file <pidfile>. This option is equivalent to
929 the "-p" command line argument. The file must be accessible to the user
930 starting the process. See also "daemon".
931
Willy Tarreau1d549722016-02-16 12:41:57 +0100932presetenv <name> <value>
933 Sets environment variable <name> to value <value>. If the variable exists, it
934 is NOT overwritten. The changes immediately take effect so that the next line
935 in the configuration file sees the new value. See also "setenv", "resetenv",
936 and "unsetenv".
937
938resetenv [<name> ...]
939 Removes all environment variables except the ones specified in argument. It
940 allows to use a clean controlled environment before setting new values with
941 setenv or unsetenv. Please note that some internal functions may make use of
942 some environment variables, such as time manipulation functions, but also
943 OpenSSL or even external checks. This must be used with extreme care and only
944 after complete validation. The changes immediately take effect so that the
945 next line in the configuration file sees the new environment. See also
946 "setenv", "presetenv", and "unsetenv".
947
Christopher Fauletff4121f2017-11-22 16:38:49 +0100948stats bind-process [ all | odd | even | <process_num>[-[process_num>]] ] ...
Willy Tarreau35b7b162012-10-22 23:17:18 +0200949 Limits the stats socket to a certain set of processes numbers. By default the
950 stats socket is bound to all processes, causing a warning to be emitted when
951 nbproc is greater than 1 because there is no way to select the target process
952 when connecting. However, by using this setting, it becomes possible to pin
953 the stats socket to a specific set of processes, typically the first one. The
954 warning will automatically be disabled when this setting is used, whatever
Willy Tarreaua9db57e2013-01-18 11:29:29 +0100955 the number of processes used. The maximum process ID depends on the machine's
Christopher Fauletff4121f2017-11-22 16:38:49 +0100956 word size (32 or 64). Ranges can be partially defined. The higher bound can
957 be omitted. In such case, it is replaced by the corresponding maximum
958 value. A better option consists in using the "process" setting of the "stats
959 socket" line to force the process on each line.
Willy Tarreau35b7b162012-10-22 23:17:18 +0200960
Baptiste Assmann5626f482015-08-23 10:00:10 +0200961server-state-base <directory>
962 Specifies the directory prefix to be prepended in front of all servers state
Baptiste Assmann01c6cc32015-08-23 11:45:29 +0200963 file names which do not start with a '/'. See also "server-state-file",
964 "load-server-state-from-file" and "server-state-file-name".
Baptiste Assmannef1f0fc2015-08-23 10:06:39 +0200965
966server-state-file <file>
967 Specifies the path to the file containing state of servers. If the path starts
968 with a slash ('/'), it is considered absolute, otherwise it is considered
969 relative to the directory specified using "server-state-base" (if set) or to
970 the current directory. Before reloading HAProxy, it is possible to save the
971 servers' current state using the stats command "show servers state". The
972 output of this command must be written in the file pointed by <file>. When
973 starting up, before handling traffic, HAProxy will read, load and apply state
974 for each server found in the file and available in its current running
Baptiste Assmann01c6cc32015-08-23 11:45:29 +0200975 configuration. See also "server-state-base" and "show servers state",
976 "load-server-state-from-file" and "server-state-file-name"
Baptiste Assmann5626f482015-08-23 10:00:10 +0200977
Willy Tarreau1d549722016-02-16 12:41:57 +0100978setenv <name> <value>
979 Sets environment variable <name> to value <value>. If the variable exists, it
980 is overwritten. The changes immediately take effect so that the next line in
981 the configuration file sees the new value. See also "presetenv", "resetenv",
982 and "unsetenv".
983
Willy Tarreau610f04b2014-02-13 11:36:41 +0100984ssl-default-bind-ciphers <ciphers>
985 This setting is only available when support for OpenSSL was built in. It sets
986 the default string describing the list of cipher algorithms ("cipher suite")
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300987 that are negotiated during the SSL/TLS handshake for all "bind" lines which
Willy Tarreau610f04b2014-02-13 11:36:41 +0100988 do not explicitly define theirs. The format of the string is defined in
989 "man 1 ciphers" from OpenSSL man pages, and can be for instance a string such
990 as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes). Please check the
991 "bind" keyword for more information.
992
Emeric Brun2c86cbf2014-10-30 15:56:50 +0100993ssl-default-bind-options [<option>]...
994 This setting is only available when support for OpenSSL was built in. It sets
995 default ssl-options to force on all "bind" lines. Please check the "bind"
996 keyword to see available options.
997
998 Example:
999 global
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +02001000 ssl-default-bind-options ssl-min-ver TLSv1.0 no-tls-tickets
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001001
Willy Tarreau610f04b2014-02-13 11:36:41 +01001002ssl-default-server-ciphers <ciphers>
1003 This setting is only available when support for OpenSSL was built in. It
1004 sets the default string describing the list of cipher algorithms that are
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001005 negotiated during the SSL/TLS handshake with the server, for all "server"
Willy Tarreau610f04b2014-02-13 11:36:41 +01001006 lines which do not explicitly define theirs. The format of the string is
1007 defined in "man 1 ciphers". Please check the "server" keyword for more
1008 information.
1009
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001010ssl-default-server-options [<option>]...
1011 This setting is only available when support for OpenSSL was built in. It sets
1012 default ssl-options to force on all "server" lines. Please check the "server"
1013 keyword to see available options.
1014
Remi Gacogne47783ef2015-05-29 15:53:22 +02001015ssl-dh-param-file <file>
1016 This setting is only available when support for OpenSSL was built in. It sets
1017 the default DH parameters that are used during the SSL/TLS handshake when
1018 ephemeral Diffie-Hellman (DHE) key exchange is used, for all "bind" lines
1019 which do not explicitely define theirs. It will be overridden by custom DH
1020 parameters found in a bind certificate file if any. If custom DH parameters
Cyril Bonté307ee1e2015-09-28 23:16:06 +02001021 are not specified either by using ssl-dh-param-file or by setting them
1022 directly in the certificate file, pre-generated DH parameters of the size
1023 specified by tune.ssl.default-dh-param will be used. Custom parameters are
1024 known to be more secure and therefore their use is recommended.
Remi Gacogne47783ef2015-05-29 15:53:22 +02001025 Custom DH parameters may be generated by using the OpenSSL command
1026 "openssl dhparam <size>", where size should be at least 2048, as 1024-bit DH
1027 parameters should not be considered secure anymore.
1028
Emeric Brun850efd52014-01-29 12:24:34 +01001029ssl-server-verify [none|required]
1030 The default behavior for SSL verify on servers side. If specified to 'none',
1031 servers certificates are not verified. The default is 'required' except if
1032 forced using cmdline option '-dV'.
1033
Willy Tarreauabb175f2012-09-24 12:43:26 +02001034stats socket [<address:port>|<path>] [param*]
1035 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
1036 Connections to this socket will return various statistics outputs and even
1037 allow some commands to be issued to change some runtime settings. Please
Willy Tarreau1af20c72017-06-23 16:01:14 +02001038 consult section 9.3 "Unix Socket commands" of Management Guide for more
Kevin Decherf949c7202015-10-13 23:26:44 +02001039 details.
Willy Tarreau6162db22009-10-10 17:13:00 +02001040
Willy Tarreauabb175f2012-09-24 12:43:26 +02001041 All parameters supported by "bind" lines are supported, for instance to
1042 restrict access to some users or their access rights. Please consult
1043 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +02001044
1045stats timeout <timeout, in milliseconds>
1046 The default timeout on the stats socket is set to 10 seconds. It is possible
1047 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +01001048 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +02001049
1050stats maxconn <connections>
1051 By default, the stats socket is limited to 10 concurrent connections. It is
1052 possible to change this value with "stats maxconn".
1053
Willy Tarreau6a06a402007-07-15 20:15:28 +02001054uid <number>
1055 Changes the process' user ID to <number>. It is recommended that the user ID
1056 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
1057 be started with superuser privileges in order to be able to switch to another
1058 one. See also "gid" and "user".
1059
1060ulimit-n <number>
1061 Sets the maximum number of per-process file-descriptors to <number>. By
1062 default, it is automatically computed, so it is recommended not to use this
1063 option.
1064
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001065unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
1066 [ group <group> ] [ gid <gid> ]
1067
1068 Fixes common settings to UNIX listening sockets declared in "bind" statements.
1069 This is mainly used to simplify declaration of those UNIX sockets and reduce
1070 the risk of errors, since those settings are most commonly required but are
1071 also process-specific. The <prefix> setting can be used to force all socket
1072 path to be relative to that directory. This might be needed to access another
1073 component's chroot. Note that those paths are resolved before haproxy chroots
1074 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
1075 all have the same meaning as their homonyms used by the "bind" statement. If
1076 both are specified, the "bind" statement has priority, meaning that the
1077 "unix-bind" settings may be seen as process-wide default settings.
1078
Willy Tarreau1d549722016-02-16 12:41:57 +01001079unsetenv [<name> ...]
1080 Removes environment variables specified in arguments. This can be useful to
1081 hide some sensitive information that are occasionally inherited from the
1082 user's environment during some operations. Variables which did not exist are
1083 silently ignored so that after the operation, it is certain that none of
1084 these variables remain. The changes immediately take effect so that the next
1085 line in the configuration file will not see these variables. See also
1086 "setenv", "presetenv", and "resetenv".
1087
Willy Tarreau6a06a402007-07-15 20:15:28 +02001088user <user name>
1089 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
1090 See also "uid" and "group".
1091
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02001092node <name>
1093 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
1094
1095 This statement is useful in HA configurations where two or more processes or
1096 servers share the same IP address. By setting a different node-name on all
1097 nodes, it becomes easy to immediately spot what server is handling the
1098 traffic.
1099
1100description <text>
1101 Add a text that describes the instance.
1102
1103 Please note that it is required to escape certain characters (# for example)
1104 and this text is inserted into a html page so you should avoid using
1105 "<" and ">" characters.
1106
Thomas Holmesdb04f192015-05-18 13:21:39 +0100110751degrees-data-file <file path>
1108 The path of the 51Degrees data file to provide device detection services. The
1109 file should be unzipped and accessible by HAProxy with relevavnt permissions.
1110
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001111 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001112 compiled with USE_51DEGREES.
1113
Ben Shillitof25e8e52016-12-02 14:25:37 +0000111451degrees-property-name-list [<string> ...]
Thomas Holmesdb04f192015-05-18 13:21:39 +01001115 A list of 51Degrees property names to be load from the dataset. A full list
1116 of names is available on the 51Degrees website:
1117 https://51degrees.com/resources/property-dictionary
1118
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001119 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001120 compiled with USE_51DEGREES.
1121
Dragan Dosen93b38d92015-06-29 16:43:25 +0200112251degrees-property-separator <char>
Thomas Holmesdb04f192015-05-18 13:21:39 +01001123 A char that will be appended to every property value in a response header
1124 containing 51Degrees results. If not set that will be set as ','.
1125
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001126 Please note that this option is only available when haproxy has been
1127 compiled with USE_51DEGREES.
1128
112951degrees-cache-size <number>
1130 Sets the size of the 51Degrees converter cache to <number> entries. This
1131 is an LRU cache which reminds previous device detections and their results.
1132 By default, this cache is disabled.
1133
1134 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001135 compiled with USE_51DEGREES.
1136
scientiamobiled0027ed2016-11-04 10:55:08 +01001137wurfl-data-file <file path>
1138 The path of the WURFL data file to provide device detection services. The
1139 file should be accessible by HAProxy with relevant permissions.
1140
1141 Please note that this option is only available when haproxy has been compiled
1142 with USE_WURFL=1.
1143
1144wurfl-information-list [<capability>]*
1145 A space-delimited list of WURFL capabilities, virtual capabilities, property
1146 names we plan to use in injected headers. A full list of capability and
1147 virtual capability names is available on the Scientiamobile website :
1148
1149 https://www.scientiamobile.com/wurflCapability
1150
1151 Valid WURFL properties are:
1152 - wurfl_id Contains the device ID of the matched device.
1153
1154 - wurfl_root_id Contains the device root ID of the matched
1155 device.
1156
1157 - wurfl_isdevroot Tells if the matched device is a root device.
1158 Possible values are "TRUE" or "FALSE".
1159
1160 - wurfl_useragent The original useragent coming with this
1161 particular web request.
1162
1163 - wurfl_api_version Contains a string representing the currently
1164 used Libwurfl API version.
1165
1166 - wurfl_engine_target Contains a string representing the currently
1167 set WURFL Engine Target. Possible values are
1168 "HIGH_ACCURACY", "HIGH_PERFORMANCE", "INVALID".
1169
1170 - wurfl_info A string containing information on the parsed
1171 wurfl.xml and its full path.
1172
1173 - wurfl_last_load_time Contains the UNIX timestamp of the last time
1174 WURFL has been loaded successfully.
1175
1176 - wurfl_normalized_useragent The normalized useragent.
1177
1178 - wurfl_useragent_priority The user agent priority used by WURFL.
1179
1180 Please note that this option is only available when haproxy has been compiled
1181 with USE_WURFL=1.
1182
1183wurfl-information-list-separator <char>
1184 A char that will be used to separate values in a response header containing
1185 WURFL results. If not set that a comma (',') will be used by default.
1186
1187 Please note that this option is only available when haproxy has been compiled
1188 with USE_WURFL=1.
1189
1190wurfl-patch-file [<file path>]
1191 A list of WURFL patch file paths. Note that patches are loaded during startup
1192 thus before the chroot.
1193
1194 Please note that this option is only available when haproxy has been compiled
1195 with USE_WURFL=1.
1196
1197wurfl-engine-mode { accuracy | performance }
1198 Sets the WURFL engine target. You can choose between 'accuracy' or
1199 'performance' targets. In performance mode, desktop web browser detection is
1200 done programmatically without referencing the WURFL data. As a result, most
1201 desktop web browsers are returned as generic_web_browser WURFL ID for
1202 performance. If either performance or accuracy are not defined, performance
1203 mode is enabled by default.
1204
1205 Please note that this option is only available when haproxy has been compiled
1206 with USE_WURFL=1.
1207
1208wurfl-cache-size <U>[,<D>]
1209 Sets the WURFL caching strategy. Here <U> is the Useragent cache size, and
1210 <D> is the internal device cache size. There are three possibilities here :
1211 - "0" : no cache is used.
1212 - <U> : the Single LRU cache is used, the size is expressed in elements.
1213 - <U>,<D> : the Double LRU cache is used, both sizes are in elements. This is
1214 the highest performing option.
1215
1216 Please note that this option is only available when haproxy has been compiled
1217 with USE_WURFL=1.
1218
1219wurfl-useragent-priority { plain | sideloaded_browser }
1220 Tells WURFL if it should prioritize use of the plain user agent ('plain')
1221 over the default sideloaded browser user agent ('sideloaded_browser').
1222
1223 Please note that this option is only available when haproxy has been compiled
1224 with USE_WURFL=1.
1225
Willy Tarreau6a06a402007-07-15 20:15:28 +02001226
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012273.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +02001228-----------------------
1229
Willy Tarreau1746eec2014-04-25 10:46:47 +02001230max-spread-checks <delay in milliseconds>
1231 By default, haproxy tries to spread the start of health checks across the
1232 smallest health check interval of all the servers in a farm. The principle is
1233 to avoid hammering services running on the same server. But when using large
1234 check intervals (10 seconds or more), the last servers in the farm take some
1235 time before starting to be tested, which can be a problem. This parameter is
1236 used to enforce an upper bound on delay between the first and the last check,
1237 even if the servers' check intervals are larger. When servers run with
1238 shorter intervals, their intervals will be respected though.
1239
Willy Tarreau6a06a402007-07-15 20:15:28 +02001240maxconn <number>
1241 Sets the maximum per-process number of concurrent connections to <number>. It
1242 is equivalent to the command-line argument "-n". Proxies will stop accepting
1243 connections when this limit is reached. The "ulimit-n" parameter is
Willy Tarreau8274e102014-06-19 15:31:25 +02001244 automatically adjusted according to this value. See also "ulimit-n". Note:
1245 the "select" poller cannot reliably use more than 1024 file descriptors on
1246 some platforms. If your platform only supports select and reports "select
1247 FAILED" on startup, you need to reduce maxconn until it works (slightly
Willy Tarreaud0256482015-01-15 21:45:22 +01001248 below 500 in general). If this value is not set, it will default to the value
1249 set in DEFAULT_MAXCONN at build time (reported in haproxy -vv) if no memory
1250 limit is enforced, or will be computed based on the memory limit, the buffer
1251 size, memory allocated to compression, SSL cache size, and use or not of SSL
1252 and the associated maxsslconn (which can also be automatic).
Willy Tarreau6a06a402007-07-15 20:15:28 +02001253
Willy Tarreau81c25d02011-09-07 15:17:21 +02001254maxconnrate <number>
1255 Sets the maximum per-process number of connections per second to <number>.
1256 Proxies will stop accepting connections when this limit is reached. It can be
1257 used to limit the global capacity regardless of each frontend capacity. It is
1258 important to note that this can only be used as a service protection measure,
1259 as there will not necessarily be a fair share between frontends when the
1260 limit is reached, so it's a good idea to also limit each frontend to some
1261 value close to its expected share. Also, lowering tune.maxaccept can improve
1262 fairness.
1263
William Lallemandd85f9172012-11-09 17:05:39 +01001264maxcomprate <number>
1265 Sets the maximum per-process input compression rate to <number> kilobytes
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001266 per second. For each session, if the maximum is reached, the compression
William Lallemandd85f9172012-11-09 17:05:39 +01001267 level will be decreased during the session. If the maximum is reached at the
1268 beginning of a session, the session will not compress at all. If the maximum
1269 is not reached, the compression level will be increased up to
1270 tune.comp.maxlevel. A value of zero means there is no limit, this is the
1271 default value.
1272
William Lallemand072a2bf2012-11-20 17:01:01 +01001273maxcompcpuusage <number>
1274 Sets the maximum CPU usage HAProxy can reach before stopping the compression
1275 for new requests or decreasing the compression level of current requests.
1276 It works like 'maxcomprate' but measures CPU usage instead of incoming data
1277 bandwidth. The value is expressed in percent of the CPU used by haproxy. In
1278 case of multiple processes (nbproc > 1), each process manages its individual
1279 usage. A value of 100 disable the limit. The default value is 100. Setting
1280 a lower value will prevent the compression work from slowing the whole
1281 process down and from introducing high latencies.
1282
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001283maxpipes <number>
1284 Sets the maximum per-process number of pipes to <number>. Currently, pipes
1285 are only used by kernel-based tcp splicing. Since a pipe contains two file
1286 descriptors, the "ulimit-n" value will be increased accordingly. The default
1287 value is maxconn/4, which seems to be more than enough for most heavy usages.
1288 The splice code dynamically allocates and releases pipes, and can fall back
1289 to standard copy, so setting this value too low may only impact performance.
1290
Willy Tarreau93e7c002013-10-07 18:51:07 +02001291maxsessrate <number>
1292 Sets the maximum per-process number of sessions per second to <number>.
1293 Proxies will stop accepting connections when this limit is reached. It can be
1294 used to limit the global capacity regardless of each frontend capacity. It is
1295 important to note that this can only be used as a service protection measure,
1296 as there will not necessarily be a fair share between frontends when the
1297 limit is reached, so it's a good idea to also limit each frontend to some
1298 value close to its expected share. Also, lowering tune.maxaccept can improve
1299 fairness.
1300
Willy Tarreau403edff2012-09-06 11:58:37 +02001301maxsslconn <number>
1302 Sets the maximum per-process number of concurrent SSL connections to
1303 <number>. By default there is no SSL-specific limit, which means that the
1304 global maxconn setting will apply to all connections. Setting this limit
1305 avoids having openssl use too much memory and crash when malloc returns NULL
1306 (since it unfortunately does not reliably check for such conditions). Note
1307 that the limit applies both to incoming and outgoing connections, so one
1308 connection which is deciphered then ciphered accounts for 2 SSL connections.
Willy Tarreaud0256482015-01-15 21:45:22 +01001309 If this value is not set, but a memory limit is enforced, this value will be
1310 automatically computed based on the memory limit, maxconn, the buffer size,
1311 memory allocated to compression, SSL cache size, and use of SSL in either
1312 frontends, backends or both. If neither maxconn nor maxsslconn are specified
1313 when there is a memory limit, haproxy will automatically adjust these values
1314 so that 100% of the connections can be made over SSL with no risk, and will
1315 consider the sides where it is enabled (frontend, backend, both).
Willy Tarreau403edff2012-09-06 11:58:37 +02001316
Willy Tarreaue43d5322013-10-07 20:01:52 +02001317maxsslrate <number>
1318 Sets the maximum per-process number of SSL sessions per second to <number>.
1319 SSL listeners will stop accepting connections when this limit is reached. It
1320 can be used to limit the global SSL CPU usage regardless of each frontend
1321 capacity. It is important to note that this can only be used as a service
1322 protection measure, as there will not necessarily be a fair share between
1323 frontends when the limit is reached, so it's a good idea to also limit each
1324 frontend to some value close to its expected share. It is also important to
1325 note that the sessions are accounted before they enter the SSL stack and not
1326 after, which also protects the stack against bad handshakes. Also, lowering
1327 tune.maxaccept can improve fairness.
1328
William Lallemand9d5f5482012-11-07 16:12:57 +01001329maxzlibmem <number>
1330 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
1331 When the maximum amount is reached, future sessions will not compress as long
1332 as RAM is unavailable. When sets to 0, there is no limit.
William Lallemande3a7d992012-11-20 11:25:20 +01001333 The default value is 0. The value is available in bytes on the UNIX socket
1334 with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is
1335 "ZlibMemUsage" in bytes.
1336
Willy Tarreau6a06a402007-07-15 20:15:28 +02001337noepoll
1338 Disables the use of the "epoll" event polling system on Linux. It is
1339 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +01001340 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001341
1342nokqueue
1343 Disables the use of the "kqueue" event polling system on BSD. It is
1344 equivalent to the command-line argument "-dk". The next polling system
1345 used will generally be "poll". See also "nopoll".
1346
1347nopoll
1348 Disables the use of the "poll" event polling system. It is equivalent to the
1349 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001350 It should never be needed to disable "poll" since it's available on all
Willy Tarreaue9f49e72012-11-11 17:42:00 +01001351 platforms supported by HAProxy. See also "nokqueue" and "noepoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001352
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001353nosplice
1354 Disables the use of kernel tcp splicing between sockets on Linux. It is
1355 equivalent to the command line argument "-dS". Data will then be copied
1356 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001357 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001358 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
1359 be used. This option makes it easier to globally disable kernel splicing in
1360 case of doubt. See also "option splice-auto", "option splice-request" and
1361 "option splice-response".
1362
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001363nogetaddrinfo
1364 Disables the use of getaddrinfo(3) for name resolving. It is equivalent to
1365 the command line argument "-dG". Deprecated gethostbyname(3) will be used.
1366
Lukas Tribusa0bcbdc2016-09-12 21:42:20 +00001367noreuseport
1368 Disables the use of SO_REUSEPORT - see socket(7). It is equivalent to the
1369 command line argument "-dR".
1370
Willy Tarreaufe255b72007-10-14 23:09:26 +02001371spread-checks <0..50, in percent>
Simon Hormand60d6912013-11-25 10:46:36 +09001372 Sometimes it is desirable to avoid sending agent and health checks to
1373 servers at exact intervals, for instance when many logical servers are
1374 located on the same physical server. With the help of this parameter, it
1375 becomes possible to add some randomness in the check interval between 0
1376 and +/- 50%. A value between 2 and 5 seems to show good results. The
1377 default value remains at 0.
Willy Tarreaufe255b72007-10-14 23:09:26 +02001378
Grant Zhang872f9c22017-01-21 01:10:18 +00001379ssl-engine <name> [algo <comma-seperated list of algorithms>]
1380 Sets the OpenSSL engine to <name>. List of valid values for <name> may be
1381 obtained using the command "openssl engine". This statement may be used
1382 multiple times, it will simply enable multiple crypto engines. Referencing an
1383 unsupported engine will prevent haproxy from starting. Note that many engines
1384 will lead to lower HTTPS performance than pure software with recent
1385 processors. The optional command "algo" sets the default algorithms an ENGINE
1386 will supply using the OPENSSL function ENGINE_set_default_string(). A value
1387 of "ALL" uses the engine for all cryptographic operations. If no list of
1388 algo is specified then the value of "ALL" is used. A comma-seperated list
1389 of different algorithms may be specified, including: RSA, DSA, DH, EC, RAND,
1390 CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. This is the same format that
1391 openssl configuration file uses:
1392 https://www.openssl.org/docs/man1.0.2/apps/config.html
1393
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00001394ssl-mode-async
1395 Adds SSL_MODE_ASYNC mode to the SSL context. This enables asynchronous TLS
Emeric Brun3854e012017-05-17 20:42:48 +02001396 I/O operations if asynchronous capable SSL engines are used. The current
Emeric Brunb5e42a82017-06-06 12:35:14 +00001397 implementation supports a maximum of 32 engines. The Openssl ASYNC API
1398 doesn't support moving read/write buffers and is not compliant with
1399 haproxy's buffer management. So the asynchronous mode is disabled on
1400 read/write operations (it is only enabled during initial and reneg
1401 handshakes).
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00001402
Willy Tarreau33cb0652014-12-23 22:52:37 +01001403tune.buffers.limit <number>
1404 Sets a hard limit on the number of buffers which may be allocated per process.
1405 The default value is zero which means unlimited. The minimum non-zero value
1406 will always be greater than "tune.buffers.reserve" and should ideally always
1407 be about twice as large. Forcing this value can be particularly useful to
1408 limit the amount of memory a process may take, while retaining a sane
1409 behaviour. When this limit is reached, sessions which need a buffer wait for
1410 another one to be released by another session. Since buffers are dynamically
1411 allocated and released, the waiting time is very short and not perceptible
1412 provided that limits remain reasonable. In fact sometimes reducing the limit
1413 may even increase performance by increasing the CPU cache's efficiency. Tests
1414 have shown good results on average HTTP traffic with a limit to 1/10 of the
1415 expected global maxconn setting, which also significantly reduces memory
1416 usage. The memory savings come from the fact that a number of connections
1417 will not allocate 2*tune.bufsize. It is best not to touch this value unless
1418 advised to do so by an haproxy core developer.
1419
Willy Tarreau1058ae72014-12-23 22:40:40 +01001420tune.buffers.reserve <number>
1421 Sets the number of buffers which are pre-allocated and reserved for use only
1422 during memory shortage conditions resulting in failed memory allocations. The
1423 minimum value is 2 and is also the default. There is no reason a user would
1424 want to change this value, it's mostly aimed at haproxy core developers.
1425
Willy Tarreau27a674e2009-08-17 07:23:33 +02001426tune.bufsize <number>
1427 Sets the buffer size to this size (in bytes). Lower values allow more
1428 sessions to coexist in the same amount of RAM, and higher values allow some
1429 applications with very large cookies to work. The default value is 16384 and
1430 can be changed at build time. It is strongly recommended not to change this
1431 from the default value, as very low values will break some services such as
1432 statistics, and values larger than default size will increase memory usage,
1433 possibly causing the system to run out of memory. At least the global maxconn
Willy Tarreau45a66cc2017-11-24 11:28:00 +01001434 parameter should be decreased by the same factor as this one is increased. In
1435 addition, use of HTTP/2 mandates that this value must be 16384 or more. If an
1436 HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +04001437 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
1438 than this size, haproxy will return HTTP 502 (Bad Gateway).
Willy Tarreau27a674e2009-08-17 07:23:33 +02001439
Willy Tarreau43961d52010-10-04 20:39:20 +02001440tune.chksize <number>
1441 Sets the check buffer size to this size (in bytes). Higher values may help
1442 find string or regex patterns in very large pages, though doing so may imply
1443 more memory and CPU usage. The default value is 16384 and can be changed at
1444 build time. It is not recommended to change this value, but to use better
1445 checks whenever possible.
1446
William Lallemandf3747832012-11-09 12:33:10 +01001447tune.comp.maxlevel <number>
1448 Sets the maximum compression level. The compression level affects CPU
1449 usage during compression. This value affects CPU usage during compression.
1450 Each session using compression initializes the compression algorithm with
1451 this value. The default value is 1.
1452
Willy Tarreaufe20e5b2017-07-27 11:42:14 +02001453tune.h2.header-table-size <number>
1454 Sets the HTTP/2 dynamic header table size. It defaults to 4096 bytes and
1455 cannot be larger than 65536 bytes. A larger value may help certain clients
1456 send more compact requests, depending on their capabilities. This amount of
1457 memory is consumed for each HTTP/2 connection. It is recommended not to
1458 change it.
1459
Willy Tarreaue6baec02017-07-27 11:45:11 +02001460tune.h2.initial-window-size <number>
1461 Sets the HTTP/2 initial window size, which is the number of bytes the client
1462 can upload before waiting for an acknowledgement from haproxy. This setting
1463 only affects payload contents (ie: the body of POST requests), not headers.
1464 The default value is 65535, which roughly allows up to 5 Mbps of upload
1465 bandwidth per client over a network showing a 100 ms ping time, or 500 Mbps
1466 over a 1-ms local network. It can make sense to increase this value to allow
1467 faster uploads, or to reduce it to increase fairness when dealing with many
1468 clients. It doesn't affect resource usage.
1469
Willy Tarreau5242ef82017-07-27 11:47:28 +02001470tune.h2.max-concurrent-streams <number>
1471 Sets the HTTP/2 maximum number of concurrent streams per connection (ie the
1472 number of outstanding requests on a single connection). The default value is
1473 100. A larger one may slightly improve page load time for complex sites when
1474 visited over high latency networks, but increases the amount of resources a
1475 single client may allocate. A value of zero disables the limit so a single
1476 client may create as many streams as allocatable by haproxy. It is highly
1477 recommended not to change this value.
1478
Willy Tarreau193b8c62012-11-22 00:17:38 +01001479tune.http.cookielen <number>
1480 Sets the maximum length of captured cookies. This is the maximum value that
1481 the "capture cookie xxx len yyy" will be allowed to take, and any upper value
1482 will automatically be truncated to this one. It is important not to set too
1483 high a value because all cookie captures still allocate this size whatever
1484 their configured value (they share a same pool). This value is per request
1485 per response, so the memory allocated is twice this value per connection.
1486 When not specified, the limit is set to 63 characters. It is recommended not
1487 to change this value.
1488
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001489tune.http.logurilen <number>
1490 Sets the maximum length of request uri in logs. This prevent to truncate long
1491 requests uris with valuable query strings in log lines. This is not related
1492 to syslog limits. If you increase this limit, you may also increase the
1493 'log ... len yyyy' parameter. Your syslog deamon may also need specific
1494 configuration directives too.
1495 The default value is 1024.
1496
Willy Tarreauac1932d2011-10-24 19:14:41 +02001497tune.http.maxhdr <number>
1498 Sets the maximum number of headers in a request. When a request comes with a
1499 number of headers greater than this value (including the first line), it is
1500 rejected with a "400 Bad Request" status code. Similarly, too large responses
1501 are blocked with "502 Bad Gateway". The default value is 101, which is enough
1502 for all usages, considering that the widely deployed Apache server uses the
1503 same limit. It can be useful to push this limit further to temporarily allow
Christopher Faulet50174f32017-06-21 16:31:35 +02001504 a buggy application to work by the time it gets fixed. The accepted range is
1505 1..32767. Keep in mind that each new header consumes 32bits of memory for
1506 each session, so don't push this limit too high.
Willy Tarreauac1932d2011-10-24 19:14:41 +02001507
Willy Tarreau7e312732014-02-12 16:35:14 +01001508tune.idletimer <timeout>
1509 Sets the duration after which haproxy will consider that an empty buffer is
1510 probably associated with an idle stream. This is used to optimally adjust
1511 some packet sizes while forwarding large and small data alternatively. The
1512 decision to use splice() or to send large buffers in SSL is modulated by this
1513 parameter. The value is in milliseconds between 0 and 65535. A value of zero
1514 means that haproxy will not try to detect idle streams. The default is 1000,
1515 which seems to correctly detect end user pauses (eg: read a page before
1516 clicking). There should be not reason for changing this value. Please check
1517 tune.ssl.maxrecord below.
1518
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001519tune.lua.forced-yield <number>
1520 This directive forces the Lua engine to execute a yield each <number> of
Tim Düsterhus4896c442016-11-29 02:15:19 +01001521 instructions executed. This permits interrupting a long script and allows the
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001522 HAProxy scheduler to process other tasks like accepting connections or
1523 forwarding traffic. The default value is 10000 instructions. If HAProxy often
1524 executes some Lua code but more reactivity is required, this value can be
1525 lowered. If the Lua code is quite long and its result is absolutely required
1526 to process the data, the <number> can be increased.
1527
Willy Tarreau32f61e22015-03-18 17:54:59 +01001528tune.lua.maxmem
1529 Sets the maximum amount of RAM in megabytes per process usable by Lua. By
1530 default it is zero which means unlimited. It is important to set a limit to
1531 ensure that a bug in a script will not result in the system running out of
1532 memory.
1533
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001534tune.lua.session-timeout <timeout>
1535 This is the execution timeout for the Lua sessions. This is useful for
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02001536 preventing infinite loops or spending too much time in Lua. This timeout
1537 counts only the pure Lua runtime. If the Lua does a sleep, the sleep is
1538 not taked in account. The default timeout is 4s.
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001539
1540tune.lua.task-timeout <timeout>
1541 Purpose is the same as "tune.lua.session-timeout", but this timeout is
1542 dedicated to the tasks. By default, this timeout isn't set because a task may
1543 remain alive during of the lifetime of HAProxy. For example, a task used to
1544 check servers.
1545
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02001546tune.lua.service-timeout <timeout>
1547 This is the execution timeout for the Lua services. This is useful for
1548 preventing infinite loops or spending too much time in Lua. This timeout
1549 counts only the pure Lua runtime. If the Lua does a sleep, the sleep is
1550 not taked in account. The default timeout is 4s.
1551
Willy Tarreaua0250ba2008-01-06 11:22:57 +01001552tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +01001553 Sets the maximum number of consecutive connections a process may accept in a
1554 row before switching to other work. In single process mode, higher numbers
1555 give better performance at high connection rates. However in multi-process
1556 modes, keeping a bit of fairness between processes generally is better to
1557 increase performance. This value applies individually to each listener, so
1558 that the number of processes a listener is bound to is taken into account.
1559 This value defaults to 64. In multi-process mode, it is divided by twice
1560 the number of processes the listener is bound to. Setting this value to -1
1561 completely disables the limitation. It should normally not be needed to tweak
1562 this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +01001563
1564tune.maxpollevents <number>
1565 Sets the maximum amount of events that can be processed at once in a call to
1566 the polling system. The default value is adapted to the operating system. It
1567 has been noticed that reducing it below 200 tends to slightly decrease
1568 latency at the expense of network bandwidth, and increasing it above 200
1569 tends to trade latency for slightly increased bandwidth.
1570
Willy Tarreau27a674e2009-08-17 07:23:33 +02001571tune.maxrewrite <number>
1572 Sets the reserved buffer space to this size in bytes. The reserved space is
1573 used for header rewriting or appending. The first reads on sockets will never
1574 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
1575 bufsize, though that does not make much sense since there are rarely large
1576 numbers of headers to add. Setting it too high prevents processing of large
1577 requests or responses. Setting it too low prevents addition of new headers
1578 to already large requests or to POST requests. It is generally wise to set it
1579 to about 1024. It is automatically readjusted to half of bufsize if it is
1580 larger than that. This means you don't have to worry about it when changing
1581 bufsize.
1582
Willy Tarreauf3045d22015-04-29 16:24:50 +02001583tune.pattern.cache-size <number>
1584 Sets the size of the pattern lookup cache to <number> entries. This is an LRU
1585 cache which reminds previous lookups and their results. It is used by ACLs
1586 and maps on slow pattern lookups, namely the ones using the "sub", "reg",
1587 "dir", "dom", "end", "bin" match methods as well as the case-insensitive
1588 strings. It applies to pattern expressions which means that it will be able
1589 to memorize the result of a lookup among all the patterns specified on a
1590 configuration line (including all those loaded from files). It automatically
1591 invalidates entries which are updated using HTTP actions or on the CLI. The
1592 default cache size is set to 10000 entries, which limits its footprint to
1593 about 5 MB on 32-bit systems and 8 MB on 64-bit systems. There is a very low
1594 risk of collision in this cache, which is in the order of the size of the
1595 cache divided by 2^64. Typically, at 10000 requests per second with the
1596 default cache size of 10000 entries, there's 1% chance that a brute force
1597 attack could cause a single collision after 60 years, or 0.1% after 6 years.
1598 This is considered much lower than the risk of a memory corruption caused by
1599 aging components. If this is not acceptable, the cache can be disabled by
1600 setting this parameter to 0.
1601
Willy Tarreaubd9a0a72011-10-23 21:14:29 +02001602tune.pipesize <number>
1603 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
1604 are the default size for the system. But sometimes when using TCP splicing,
1605 it can improve performance to increase pipe sizes, especially if it is
1606 suspected that pipes are not filled and that many calls to splice() are
1607 performed. This has an impact on the kernel's memory footprint, so this must
1608 not be changed if impacts are not understood.
1609
Willy Tarreaue803de22010-01-21 17:43:04 +01001610tune.rcvbuf.client <number>
1611tune.rcvbuf.server <number>
1612 Forces the kernel socket receive buffer size on the client or the server side
1613 to the specified value in bytes. This value applies to all TCP/HTTP frontends
1614 and backends. It should normally never be set, and the default size (0) lets
1615 the kernel autotune this value depending on the amount of available memory.
1616 However it can sometimes help to set it to very low values (eg: 4096) in
1617 order to save kernel memory by preventing it from buffering too large amounts
1618 of received data. Lower values will significantly increase CPU usage though.
1619
Willy Tarreaub22fc302015-12-14 12:04:35 +01001620tune.recv_enough <number>
1621 Haproxy uses some hints to detect that a short read indicates the end of the
1622 socket buffers. One of them is that a read returns more than <recv_enough>
1623 bytes, which defaults to 10136 (7 segments of 1448 each). This default value
1624 may be changed by this setting to better deal with workloads involving lots
1625 of short messages such as telnet or SSH sessions.
1626
Willy Tarreaue803de22010-01-21 17:43:04 +01001627tune.sndbuf.client <number>
1628tune.sndbuf.server <number>
1629 Forces the kernel socket send buffer size on the client or the server side to
1630 the specified value in bytes. This value applies to all TCP/HTTP frontends
1631 and backends. It should normally never be set, and the default size (0) lets
1632 the kernel autotune this value depending on the amount of available memory.
1633 However it can sometimes help to set it to very low values (eg: 4096) in
1634 order to save kernel memory by preventing it from buffering too large amounts
1635 of received data. Lower values will significantly increase CPU usage though.
1636 Another use case is to prevent write timeouts with extremely slow clients due
1637 to the kernel waiting for a large part of the buffer to be read before
1638 notifying haproxy again.
1639
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001640tune.ssl.cachesize <number>
Emeric Brunaf9619d2012-11-28 18:47:52 +01001641 Sets the size of the global SSL session cache, in a number of blocks. A block
1642 is large enough to contain an encoded session without peer certificate.
1643 An encoded session with peer certificate is stored in multiple blocks
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001644 depending on the size of the peer certificate. A block uses approximately
Emeric Brunaf9619d2012-11-28 18:47:52 +01001645 200 bytes of memory. The default value may be forced at build time, otherwise
1646 defaults to 20000. When the cache is full, the most idle entries are purged
1647 and reassigned. Higher values reduce the occurrence of such a purge, hence
1648 the number of CPU-intensive SSL handshakes by ensuring that all users keep
1649 their session as long as possible. All entries are pre-allocated upon startup
Emeric Brun22890a12012-12-28 14:41:32 +01001650 and are shared between all processes if "nbproc" is greater than 1. Setting
1651 this value to 0 disables the SSL session cache.
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001652
Emeric Brun8dc60392014-05-09 13:52:00 +02001653tune.ssl.force-private-cache
1654 This boolean disables SSL session cache sharing between all processes. It
1655 should normally not be used since it will force many renegotiations due to
1656 clients hitting a random process. But it may be required on some operating
1657 systems where none of the SSL cache synchronization method may be used. In
1658 this case, adding a first layer of hash-based load balancing before the SSL
1659 layer might limit the impact of the lack of session sharing.
1660
Emeric Brun4f65bff2012-11-16 15:11:00 +01001661tune.ssl.lifetime <timeout>
1662 Sets how long a cached SSL session may remain valid. This time is expressed
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001663 in seconds and defaults to 300 (5 min). It is important to understand that it
Emeric Brun4f65bff2012-11-16 15:11:00 +01001664 does not guarantee that sessions will last that long, because if the cache is
1665 full, the longest idle sessions will be purged despite their configured
1666 lifetime. The real usefulness of this setting is to prevent sessions from
1667 being used for too long.
1668
Willy Tarreaubfd59462013-02-21 07:46:09 +01001669tune.ssl.maxrecord <number>
1670 Sets the maximum amount of bytes passed to SSL_write() at a time. Default
1671 value 0 means there is no limit. Over SSL/TLS, the client can decipher the
1672 data only once it has received a full record. With large records, it means
1673 that clients might have to download up to 16kB of data before starting to
1674 process them. Limiting the value can improve page load times on browsers
1675 located over high latency or low bandwidth networks. It is suggested to find
1676 optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over
1677 Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled),
1678 keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and
1679 2859 gave good results during tests. Use "strace -e trace=write" to find the
Willy Tarreau7e312732014-02-12 16:35:14 +01001680 best value. Haproxy will automatically switch to this setting after an idle
1681 stream has been detected (see tune.idletimer above).
Willy Tarreaubfd59462013-02-21 07:46:09 +01001682
Remi Gacognef46cd6e2014-06-12 14:58:40 +02001683tune.ssl.default-dh-param <number>
1684 Sets the maximum size of the Diffie-Hellman parameters used for generating
1685 the ephemeral/temporary Diffie-Hellman key in case of DHE key exchange. The
1686 final size will try to match the size of the server's RSA (or DSA) key (e.g,
1687 a 2048 bits temporary DH key for a 2048 bits RSA key), but will not exceed
1688 this maximum value. Default value if 1024. Only 1024 or higher values are
1689 allowed. Higher values will increase the CPU load, and values greater than
1690 1024 bits are not supported by Java 7 and earlier clients. This value is not
Remi Gacogne47783ef2015-05-29 15:53:22 +02001691 used if static Diffie-Hellman parameters are supplied either directly
1692 in the certificate file or by using the ssl-dh-param-file parameter.
Remi Gacognef46cd6e2014-06-12 14:58:40 +02001693
Christopher Faulet31af49d2015-06-09 17:29:50 +02001694tune.ssl.ssl-ctx-cache-size <number>
1695 Sets the size of the cache used to store generated certificates to <number>
1696 entries. This is a LRU cache. Because generating a SSL certificate
1697 dynamically is expensive, they are cached. The default cache size is set to
1698 1000 entries.
1699
Thierry FOURNIER5bf77322017-02-25 12:45:22 +01001700tune.ssl.capture-cipherlist-size <number>
1701 Sets the maximum size of the buffer used for capturing client-hello cipher
1702 list. If the value is 0 (default value) the capture is disabled, otherwise
1703 a buffer is allocated for each SSL/TLS connection.
1704
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001705tune.vars.global-max-size <size>
Christopher Fauletff2613e2016-11-09 11:36:17 +01001706tune.vars.proc-max-size <size>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001707tune.vars.reqres-max-size <size>
1708tune.vars.sess-max-size <size>
1709tune.vars.txn-max-size <size>
Christopher Fauletff2613e2016-11-09 11:36:17 +01001710 These five tunes help to manage the maximum amount of memory used by the
1711 variables system. "global" limits the overall amount of memory available for
1712 all scopes. "proc" limits the memory for the process scope, "sess" limits the
1713 memory for the session scope, "txn" for the transaction scope, and "reqres"
1714 limits the memory for each request or response processing.
1715 Memory accounting is hierarchical, meaning more coarse grained limits include
1716 the finer grained ones: "proc" includes "sess", "sess" includes "txn", and
1717 "txn" includes "reqres".
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001718
Daniel Schneller0b547052016-03-21 20:46:57 +01001719 For example, when "tune.vars.sess-max-size" is limited to 100,
1720 "tune.vars.txn-max-size" and "tune.vars.reqres-max-size" cannot exceed
1721 100 either. If we create a variable "txn.var" that contains 100 bytes,
1722 all available space is consumed.
1723 Notice that exceeding the limits at runtime will not result in an error
1724 message, but values might be cut off or corrupted. So make sure to accurately
1725 plan for the amount of space needed to store all your variables.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001726
William Lallemanda509e4c2012-11-07 16:54:34 +01001727tune.zlib.memlevel <number>
1728 Sets the memLevel parameter in zlib initialization for each session. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001729 defines how much memory should be allocated for the internal compression
William Lallemanda509e4c2012-11-07 16:54:34 +01001730 state. A value of 1 uses minimum memory but is slow and reduces compression
1731 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
1732 between 1 and 9. The default value is 8.
1733
1734tune.zlib.windowsize <number>
1735 Sets the window size (the size of the history buffer) as a parameter of the
1736 zlib initialization for each session. Larger values of this parameter result
1737 in better compression at the expense of memory usage. Can be a value between
1738 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001739
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017403.3. Debugging
1741--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02001742
1743debug
1744 Enables debug mode which dumps to stdout all exchanges, and disables forking
1745 into background. It is the equivalent of the command-line argument "-d". It
1746 should never be used in a production configuration since it may prevent full
1747 system startup.
1748
1749quiet
1750 Do not display any message during startup. It is equivalent to the command-
1751 line argument "-q".
1752
Emeric Brunf099e792010-09-27 12:05:28 +02001753
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010017543.4. Userlists
1755--------------
1756It is possible to control access to frontend/backend/listen sections or to
1757http stats by allowing only authenticated and authorized users. To do this,
1758it is required to create at least one userlist and to define users.
1759
1760userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +01001761 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001762 used to store authentication & authorization data for independent customers.
1763
1764group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +01001765 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001766 attach users to this group by using a comma separated list of names
1767 proceeded by "users" keyword.
1768
Cyril Bontéf0c60612010-02-06 14:44:47 +01001769user <username> [password|insecure-password <password>]
1770 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001771 Adds user <username> to the current userlist. Both secure (encrypted) and
1772 insecure (unencrypted) passwords can be used. Encrypted passwords are
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01001773 evaluated using the crypt(3) function, so depending on the system's
1774 capabilities, different algorithms are supported. For example, modern Glibc
1775 based Linux systems support MD5, SHA-256, SHA-512, and, of course, the
1776 classic DES-based method of encrypting passwords.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001777
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01001778 Attention: Be aware that using encrypted passwords might cause significantly
1779 increased CPU usage, depending on the number of requests, and the algorithm
1780 used. For any of the hashed variants, the password for each request must
1781 be processed through the chosen algorithm, before it can be compared to the
1782 value specified in the config file. Most current algorithms are deliberately
1783 designed to be expensive to compute to achieve resistance against brute
1784 force attacks. They do not simply salt/hash the clear text password once,
1785 but thousands of times. This can quickly become a major factor in haproxy's
1786 overall CPU consumption!
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001787
1788 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +01001789 userlist L1
1790 group G1 users tiger,scott
1791 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001792
Cyril Bontéf0c60612010-02-06 14:44:47 +01001793 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
1794 user scott insecure-password elgato
1795 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001796
Cyril Bontéf0c60612010-02-06 14:44:47 +01001797 userlist L2
1798 group G1
1799 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001800
Cyril Bontéf0c60612010-02-06 14:44:47 +01001801 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
1802 user scott insecure-password elgato groups G1,G2
1803 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001804
1805 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001806
Emeric Brunf099e792010-09-27 12:05:28 +02001807
18083.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +02001809----------
Emeric Brun94900952015-06-11 18:25:54 +02001810It is possible to propagate entries of any data-types in stick-tables between
1811several haproxy instances over TCP connections in a multi-master fashion. Each
1812instance pushes its local updates and insertions to remote peers. The pushed
1813values overwrite remote ones without aggregation. Interrupted exchanges are
1814automatically detected and recovered from the last known point.
1815In addition, during a soft restart, the old process connects to the new one
1816using such a TCP connection to push all its entries before the new process
1817tries to connect to other peers. That ensures very fast replication during a
1818reload, it typically takes a fraction of a second even for large tables.
1819Note that Server IDs are used to identify servers remotely, so it is important
1820that configurations look similar or at least that the same IDs are forced on
1821each server on all participants.
Emeric Brunf099e792010-09-27 12:05:28 +02001822
1823peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001824 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +02001825 which is referenced by one or more stick-tables.
1826
Willy Tarreau77e4bd12015-05-01 20:02:17 +02001827disabled
1828 Disables a peers section. It disables both listening and any synchronization
1829 related to this section. This is provided to disable synchronization of stick
1830 tables without having to comment out all "peers" references.
1831
1832enable
1833 This re-enables a disabled peers section which was previously disabled.
1834
Emeric Brunf099e792010-09-27 12:05:28 +02001835peer <peername> <ip>:<port>
1836 Defines a peer inside a peers section.
1837 If <peername> is set to the local peer name (by default hostname, or forced
1838 using "-L" command line option), haproxy will listen for incoming remote peer
1839 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
1840 to join the remote peer, and <peername> is used at the protocol level to
1841 identify and validate the remote peer on the server side.
1842
1843 During a soft restart, local peer <ip>:<port> is used by the old instance to
1844 connect the new one and initiate a complete replication (teaching process).
1845
1846 It is strongly recommended to have the exact same peers declaration on all
1847 peers and to only rely on the "-L" command line argument to change the local
1848 peer name. This makes it easier to maintain coherent configuration files
1849 across all peers.
1850
William Lallemandb2f07452015-05-12 14:27:13 +02001851 You may want to reference some environment variables in the address
1852 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01001853
Cyril Bontédc4d9032012-04-08 21:57:39 +02001854 Example:
Emeric Brunf099e792010-09-27 12:05:28 +02001855 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001856 peer haproxy1 192.168.0.1:1024
1857 peer haproxy2 192.168.0.2:1024
1858 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +02001859
1860 backend mybackend
1861 mode tcp
1862 balance roundrobin
1863 stick-table type ip size 20k peers mypeers
1864 stick on src
1865
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001866 server srv1 192.168.0.30:80
1867 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +02001868
1869
Simon Horman51a1cf62015-02-03 13:00:44 +090018703.6. Mailers
1871------------
1872It is possible to send email alerts when the state of servers changes.
1873If configured email alerts are sent to each mailer that is configured
1874in a mailers section. Email is sent to mailers using SMTP.
1875
Pieter Baauw386a1272015-08-16 15:26:24 +02001876mailers <mailersect>
Simon Horman51a1cf62015-02-03 13:00:44 +09001877 Creates a new mailer list with the name <mailersect>. It is an
1878 independent section which is referenced by one or more proxies.
1879
1880mailer <mailername> <ip>:<port>
1881 Defines a mailer inside a mailers section.
1882
1883 Example:
1884 mailers mymailers
1885 mailer smtp1 192.168.0.1:587
1886 mailer smtp2 192.168.0.2:587
1887
1888 backend mybackend
1889 mode tcp
1890 balance roundrobin
1891
1892 email-alert mailers mymailers
1893 email-alert from test1@horms.org
1894 email-alert to test2@horms.org
1895
1896 server srv1 192.168.0.30:80
1897 server srv2 192.168.0.31:80
1898
Pieter Baauw235fcfc2016-02-13 15:33:40 +01001899timeout mail <time>
1900 Defines the time available for a mail/connection to be made and send to
1901 the mail-server. If not defined the default value is 10 seconds. To allow
1902 for at least two SYN-ACK packets to be send during initial TCP handshake it
1903 is advised to keep this value above 4 seconds.
1904
1905 Example:
1906 mailers mymailers
1907 timeout mail 20s
1908 mailer smtp1 192.168.0.1:587
Simon Horman51a1cf62015-02-03 13:00:44 +09001909
Willy Tarreauc57f0e22009-05-10 13:12:33 +020019104. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +02001911----------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001912
Willy Tarreau6a06a402007-07-15 20:15:28 +02001913Proxy configuration can be located in a set of sections :
William Lallemand6e62fb62015-04-28 16:55:23 +02001914 - defaults [<name>]
Willy Tarreau6a06a402007-07-15 20:15:28 +02001915 - frontend <name>
1916 - backend <name>
1917 - listen <name>
1918
1919A "defaults" section sets default parameters for all other sections following
1920its declaration. Those default parameters are reset by the next "defaults"
1921section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +01001922section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001923
1924A "frontend" section describes a set of listening sockets accepting client
1925connections.
1926
1927A "backend" section describes a set of servers to which the proxy will connect
1928to forward incoming connections.
1929
1930A "listen" section defines a complete proxy with its frontend and backend
1931parts combined in one section. It is generally useful for TCP-only traffic.
1932
Willy Tarreau0ba27502007-12-24 16:55:16 +01001933All proxy names must be formed from upper and lower case letters, digits,
1934'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
1935case-sensitive, which means that "www" and "WWW" are two different proxies.
1936
1937Historically, all proxy names could overlap, it just caused troubles in the
1938logs. Since the introduction of content switching, it is mandatory that two
1939proxies with overlapping capabilities (frontend/backend) have different names.
1940However, it is still permitted that a frontend and a backend share the same
1941name, as this configuration seems to be commonly encountered.
1942
1943Right now, two major proxy modes are supported : "tcp", also known as layer 4,
1944and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001945bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01001946protocol, and can interact with it by allowing, blocking, switching, adding,
1947modifying, or removing arbitrary contents in requests or responses, based on
1948arbitrary criteria.
1949
Willy Tarreau70dffda2014-01-30 03:07:23 +01001950In HTTP mode, the processing applied to requests and responses flowing over
1951a connection depends in the combination of the frontend's HTTP options and
1952the backend's. HAProxy supports 5 connection modes :
1953
1954 - KAL : keep alive ("option http-keep-alive") which is the default mode : all
1955 requests and responses are processed, and connections remain open but idle
1956 between responses and new requests.
1957
1958 - TUN: tunnel ("option http-tunnel") : this was the default mode for versions
1959 1.0 to 1.5-dev21 : only the first request and response are processed, and
1960 everything else is forwarded with no analysis at all. This mode should not
1961 be used as it creates lots of trouble with logging and HTTP processing.
1962
1963 - PCL: passive close ("option httpclose") : exactly the same as tunnel mode,
1964 but with "Connection: close" appended in both directions to try to make
1965 both ends close after the first request/response exchange.
1966
1967 - SCL: server close ("option http-server-close") : the server-facing
1968 connection is closed after the end of the response is received, but the
1969 client-facing connection remains open.
1970
1971 - FCL: forced close ("option forceclose") : the connection is actively closed
1972 after the end of the response.
1973
1974The effective mode that will be applied to a connection passing through a
1975frontend and a backend can be determined by both proxy modes according to the
1976following matrix, but in short, the modes are symmetric, keep-alive is the
1977weakest option and force close is the strongest.
1978
1979 Backend mode
1980
1981 | KAL | TUN | PCL | SCL | FCL
1982 ----+-----+-----+-----+-----+----
1983 KAL | KAL | TUN | PCL | SCL | FCL
1984 ----+-----+-----+-----+-----+----
1985 TUN | TUN | TUN | PCL | SCL | FCL
1986 Frontend ----+-----+-----+-----+-----+----
1987 mode PCL | PCL | PCL | PCL | FCL | FCL
1988 ----+-----+-----+-----+-----+----
1989 SCL | SCL | SCL | FCL | SCL | FCL
1990 ----+-----+-----+-----+-----+----
1991 FCL | FCL | FCL | FCL | FCL | FCL
1992
Willy Tarreau0ba27502007-12-24 16:55:16 +01001993
Willy Tarreau70dffda2014-01-30 03:07:23 +01001994
Willy Tarreauc57f0e22009-05-10 13:12:33 +020019954.1. Proxy keywords matrix
1996--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001997
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001998The following list of keywords is supported. Most of them may only be used in a
1999limited set of section types. Some of them are marked as "deprecated" because
2000they are inherited from an old syntax which may be confusing or functionally
2001limited, and there are new recommended keywords to replace them. Keywords
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002002marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002003option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02002004and must be disabled for a specific instance. Such options may also be prefixed
2005with "default" in order to restore default settings regardless of what has been
2006specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002007
Willy Tarreau6a06a402007-07-15 20:15:28 +02002008
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002009 keyword defaults frontend listen backend
2010------------------------------------+----------+----------+---------+---------
2011acl - X X X
Willy Tarreau294d0f02015-08-10 19:40:12 +02002012appsession - - - -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002013backlog X X X -
2014balance X - X X
2015bind - X X -
2016bind-process X X X X
Jarno Huuskonen8c8c3492016-12-28 18:50:29 +02002017block (deprecated) - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002018capture cookie - X X -
2019capture request header - X X -
2020capture response header - X X -
2021clitimeout (deprecated) X X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02002022compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002023contimeout (deprecated) X - X X
2024cookie X - X X
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02002025declare capture - X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002026default-server X - X X
2027default_backend X X X -
2028description - X X X
2029disabled X X X X
2030dispatch - - X X
Simon Horman51a1cf62015-02-03 13:00:44 +09002031email-alert from X X X X
Simon Horman64e34162015-02-06 11:11:57 +09002032email-alert level X X X X
Simon Horman51a1cf62015-02-03 13:00:44 +09002033email-alert mailers X X X X
2034email-alert myhostname X X X X
2035email-alert to X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002036enabled X X X X
2037errorfile X X X X
2038errorloc X X X X
2039errorloc302 X X X X
2040-- keyword -------------------------- defaults - frontend - listen -- backend -
2041errorloc303 X X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002042force-persist - X X X
Christopher Fauletc3fe5332016-04-07 15:30:10 +02002043filter - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002044fullconn X - X X
2045grace X X X X
2046hash-type X - X X
2047http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +01002048http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02002049http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002050http-request - X X X
Willy Tarreaue365c0b2013-06-11 16:06:12 +02002051http-response - X X X
Willy Tarreau30631952015-08-06 15:05:24 +02002052http-reuse X - X X
Baptiste Assmann2c42ef52013-10-09 21:57:02 +02002053http-send-name-header - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002054id - X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002055ignore-persist - X X X
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02002056load-server-state-from-file X - X X
William Lallemand0f99e342011-10-12 17:50:54 +02002057log (*) X X X X
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01002058log-format X X X -
Dragan Dosen7ad31542015-09-28 17:16:47 +02002059log-format-sd X X X -
Willy Tarreau094af4e2015-01-07 15:03:42 +01002060log-tag X X X X
Willy Tarreauc35362a2014-04-25 13:58:37 +02002061max-keep-alive-queue X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002062maxconn X X X -
2063mode X X X X
2064monitor fail - X X -
2065monitor-net X X X -
2066monitor-uri X X X -
2067option abortonclose (*) X - X X
2068option accept-invalid-http-request (*) X X X -
2069option accept-invalid-http-response (*) X - X X
2070option allbackups (*) X - X X
2071option checkcache (*) X - X X
2072option clitcpka (*) X X X -
2073option contstats (*) X X X -
2074option dontlog-normal (*) X X X -
2075option dontlognull (*) X X X -
2076option forceclose (*) X X X X
2077-- keyword -------------------------- defaults - frontend - listen -- backend -
2078option forwardfor X X X X
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02002079option http-buffer-request (*) X X X X
Willy Tarreau82649f92015-05-01 22:40:51 +02002080option http-ignore-probes (*) X X X -
Willy Tarreau16bfb022010-01-16 19:48:41 +01002081option http-keep-alive (*) X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02002082option http-no-delay (*) X X X X
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02002083option http-pretend-keepalive (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002084option http-server-close (*) X X X X
Willy Tarreau02bce8b2014-01-30 00:15:28 +01002085option http-tunnel (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002086option http-use-proxy-header (*) X X X -
2087option httpchk X - X X
2088option httpclose (*) X X X X
2089option httplog X X X X
2090option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002091option independent-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02002092option ldap-check X - X X
Simon Horman98637e52014-06-20 12:30:16 +09002093option external-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002094option log-health-checks (*) X - X X
2095option log-separate-errors (*) X X X -
2096option logasap (*) X X X -
2097option mysql-check X - X X
2098option nolinger (*) X X X X
2099option originalto X X X X
2100option persist (*) X - X X
Baptiste Assmann809e22a2015-10-12 20:22:55 +02002101option pgsql-check X - X X
2102option prefer-last-server (*) X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002103option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02002104option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002105option smtpchk X - X X
2106option socket-stats (*) X X X -
2107option splice-auto (*) X X X X
2108option splice-request (*) X X X X
2109option splice-response (*) X X X X
Christopher Fauletba7bc162016-11-07 21:07:38 +01002110option spop-check - - - X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002111option srvtcpka (*) X - X X
2112option ssl-hello-chk X - X X
2113-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreaued179852013-12-16 01:07:00 +01002114option tcp-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002115option tcp-smart-accept (*) X X X -
2116option tcp-smart-connect (*) X - X X
2117option tcpka X X X X
2118option tcplog X X X X
2119option transparent (*) X - X X
Simon Horman98637e52014-06-20 12:30:16 +09002120external-check command X - X X
2121external-check path X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002122persist rdp-cookie X - X X
2123rate-limit sessions X X X -
2124redirect - X X X
2125redisp (deprecated) X - X X
2126redispatch (deprecated) X - X X
2127reqadd - X X X
2128reqallow - X X X
2129reqdel - X X X
2130reqdeny - X X X
2131reqiallow - X X X
2132reqidel - X X X
2133reqideny - X X X
2134reqipass - X X X
2135reqirep - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002136reqitarpit - X X X
2137reqpass - X X X
2138reqrep - X X X
2139-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002140reqtarpit - X X X
2141retries X - X X
2142rspadd - X X X
2143rspdel - X X X
2144rspdeny - X X X
2145rspidel - X X X
2146rspideny - X X X
2147rspirep - X X X
2148rsprep - X X X
2149server - - X X
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02002150server-state-file-name X - X X
Frédéric Lécaillecb4502e2017-04-20 13:36:25 +02002151server-template - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002152source X - X X
2153srvtimeout (deprecated) X - X X
Baptiste Assmann5a549212015-10-12 20:30:24 +02002154stats admin - X X X
2155stats auth X X X X
2156stats enable X X X X
2157stats hide-version X X X X
2158stats http-request - X X X
2159stats realm X X X X
2160stats refresh X X X X
2161stats scope X X X X
2162stats show-desc X X X X
2163stats show-legends X X X X
2164stats show-node X X X X
2165stats uri X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002166-- keyword -------------------------- defaults - frontend - listen -- backend -
2167stick match - - X X
2168stick on - - X X
2169stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02002170stick store-response - - X X
Adam Spiers68af3c12017-04-06 16:31:39 +01002171stick-table - X X X
Willy Tarreau938c7fe2014-04-25 14:21:39 +02002172tcp-check connect - - X X
2173tcp-check expect - - X X
2174tcp-check send - - X X
2175tcp-check send-binary - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02002176tcp-request connection - X X -
2177tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02002178tcp-request inspect-delay - X X X
Willy Tarreau4f614292016-10-21 17:49:36 +02002179tcp-request session - X X -
Emeric Brun0a3b67f2010-09-24 15:34:53 +02002180tcp-response content - - X X
2181tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002182timeout check X - X X
2183timeout client X X X -
Willy Tarreau05cdd962014-05-10 14:30:07 +02002184timeout client-fin X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002185timeout clitimeout (deprecated) X X X -
2186timeout connect X - X X
2187timeout contimeout (deprecated) X - X X
2188timeout http-keep-alive X X X X
2189timeout http-request X X X X
2190timeout queue X - X X
2191timeout server X - X X
Willy Tarreau05cdd962014-05-10 14:30:07 +02002192timeout server-fin X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002193timeout srvtimeout (deprecated) X - X X
2194timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02002195timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002196transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01002197unique-id-format X X X -
2198unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002199use_backend - X X -
Willy Tarreau4a5cade2012-04-05 21:09:48 +02002200use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002201------------------------------------+----------+----------+---------+---------
2202 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02002203
Willy Tarreau0ba27502007-12-24 16:55:16 +01002204
Willy Tarreauc57f0e22009-05-10 13:12:33 +020022054.2. Alphabetically sorted keywords reference
2206---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01002207
2208This section provides a description of each keyword and its usage.
2209
2210
2211acl <aclname> <criterion> [flags] [operator] <value> ...
2212 Declare or complete an access list.
2213 May be used in sections : defaults | frontend | listen | backend
2214 no | yes | yes | yes
2215 Example:
2216 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
2217 acl invalid_src src_port 0:1023
2218 acl local_dst hdr(host) -i localhost
2219
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002220 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002221
2222
Cyril Bontéb21570a2009-11-29 20:04:48 +01002223appsession <cookie> len <length> timeout <holdtime>
2224 [request-learn] [prefix] [mode <path-parameters|query-string>]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002225 Define session stickiness on an existing application cookie.
2226 May be used in sections : defaults | frontend | listen | backend
2227 no | no | yes | yes
2228 Arguments :
2229 <cookie> this is the name of the cookie used by the application and which
2230 HAProxy will have to learn for each new session.
2231
Cyril Bontéb21570a2009-11-29 20:04:48 +01002232 <length> this is the max number of characters that will be memorized and
Willy Tarreau0ba27502007-12-24 16:55:16 +01002233 checked in each cookie value.
2234
2235 <holdtime> this is the time after which the cookie will be removed from
2236 memory if unused. If no unit is specified, this time is in
2237 milliseconds.
2238
Cyril Bontébf47aeb2009-10-15 00:15:40 +02002239 request-learn
2240 If this option is specified, then haproxy will be able to learn
2241 the cookie found in the request in case the server does not
2242 specify any in response. This is typically what happens with
2243 PHPSESSID cookies, or when haproxy's session expires before
2244 the application's session and the correct server is selected.
2245 It is recommended to specify this option to improve reliability.
2246
Cyril Bontéb21570a2009-11-29 20:04:48 +01002247 prefix When this option is specified, haproxy will match on the cookie
2248 prefix (or URL parameter prefix). The appsession value is the
2249 data following this prefix.
2250
2251 Example :
2252 appsession ASPSESSIONID len 64 timeout 3h prefix
2253
2254 This will match the cookie ASPSESSIONIDXXXX=XXXXX,
2255 the appsession value will be XXXX=XXXXX.
2256
2257 mode This option allows to change the URL parser mode.
2258 2 modes are currently supported :
2259 - path-parameters :
2260 The parser looks for the appsession in the path parameters
2261 part (each parameter is separated by a semi-colon), which is
2262 convenient for JSESSIONID for example.
2263 This is the default mode if the option is not set.
2264 - query-string :
2265 In this mode, the parser will look for the appsession in the
2266 query string.
2267
Willy Tarreau294d0f02015-08-10 19:40:12 +02002268 As of version 1.6, appsessions was removed. It is more flexible and more
2269 convenient to use stick-tables instead, and stick-tables support multi-master
2270 replication and data conservation across reloads, which appsessions did not.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002271
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01002272 See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
2273 "ignore-persist", "nbproc" and "bind-process".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002274
2275
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01002276backlog <conns>
2277 Give hints to the system about the approximate listen backlog desired size
2278 May be used in sections : defaults | frontend | listen | backend
2279 yes | yes | yes | no
2280 Arguments :
2281 <conns> is the number of pending connections. Depending on the operating
2282 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02002283 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01002284
2285 In order to protect against SYN flood attacks, one solution is to increase
2286 the system's SYN backlog size. Depending on the system, sometimes it is just
2287 tunable via a system parameter, sometimes it is not adjustable at all, and
2288 sometimes the system relies on hints given by the application at the time of
2289 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
2290 to the listen() syscall. On systems which can make use of this value, it can
2291 sometimes be useful to be able to specify a different value, hence this
2292 backlog parameter.
2293
2294 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
2295 used as a hint and the system accepts up to the smallest greater power of
2296 two, and never more than some limits (usually 32768).
2297
2298 See also : "maxconn" and the target operating system's tuning guide.
2299
2300
Willy Tarreau0ba27502007-12-24 16:55:16 +01002301balance <algorithm> [ <arguments> ]
Willy Tarreau226071e2014-04-10 11:55:45 +02002302balance url_param <param> [check_post]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002303 Define the load balancing algorithm to be used in a backend.
2304 May be used in sections : defaults | frontend | listen | backend
2305 yes | no | yes | yes
2306 Arguments :
2307 <algorithm> is the algorithm used to select a server when doing load
2308 balancing. This only applies when no persistence information
2309 is available, or when a connection is redispatched to another
2310 server. <algorithm> may be one of the following :
2311
2312 roundrobin Each server is used in turns, according to their weights.
2313 This is the smoothest and fairest algorithm when the server's
2314 processing time remains equally distributed. This algorithm
2315 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02002316 on the fly for slow starts for instance. It is limited by
Godbacha34bdc02013-07-22 07:44:53 +08002317 design to 4095 active servers per backend. Note that in some
Willy Tarreau9757a382009-10-03 12:56:50 +02002318 large farms, when a server becomes up after having been down
2319 for a very short time, it may sometimes take a few hundreds
2320 requests for it to be re-integrated into the farm and start
2321 receiving traffic. This is normal, though very rare. It is
2322 indicated here in case you would have the chance to observe
2323 it, so that you don't worry.
2324
2325 static-rr Each server is used in turns, according to their weights.
2326 This algorithm is as similar to roundrobin except that it is
2327 static, which means that changing a server's weight on the
2328 fly will have no effect. On the other hand, it has no design
2329 limitation on the number of servers, and when a server goes
2330 up, it is always immediately reintroduced into the farm, once
2331 the full map is recomputed. It also uses slightly less CPU to
2332 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01002333
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01002334 leastconn The server with the lowest number of connections receives the
2335 connection. Round-robin is performed within groups of servers
2336 of the same load to ensure that all servers will be used. Use
2337 of this algorithm is recommended where very long sessions are
2338 expected, such as LDAP, SQL, TSE, etc... but is not very well
2339 suited for protocols using short sessions such as HTTP. This
2340 algorithm is dynamic, which means that server weights may be
2341 adjusted on the fly for slow starts for instance.
2342
Willy Tarreauf09c6602012-02-13 17:12:08 +01002343 first The first server with available connection slots receives the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03002344 connection. The servers are chosen from the lowest numeric
Willy Tarreauf09c6602012-02-13 17:12:08 +01002345 identifier to the highest (see server parameter "id"), which
2346 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02002347 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01002348 not make sense to use this algorithm without setting maxconn.
2349 The purpose of this algorithm is to always use the smallest
2350 number of servers so that extra servers can be powered off
2351 during non-intensive hours. This algorithm ignores the server
2352 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02002353 or IMAP than HTTP, though it can be useful there too. In
2354 order to use this algorithm efficiently, it is recommended
2355 that a cloud controller regularly checks server usage to turn
2356 them off when unused, and regularly checks backend queue to
2357 turn new servers on when the queue inflates. Alternatively,
2358 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01002359
Willy Tarreau0ba27502007-12-24 16:55:16 +01002360 source The source IP address is hashed and divided by the total
2361 weight of the running servers to designate which server will
2362 receive the request. This ensures that the same client IP
2363 address will always reach the same server as long as no
2364 server goes down or up. If the hash result changes due to the
2365 number of running servers changing, many clients will be
2366 directed to a different server. This algorithm is generally
2367 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002368 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01002369 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002370 static by default, which means that changing a server's
2371 weight on the fly will have no effect, but this can be
2372 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002373
Oskar Stolc8dc41842012-05-19 10:19:54 +01002374 uri This algorithm hashes either the left part of the URI (before
2375 the question mark) or the whole URI (if the "whole" parameter
2376 is present) and divides the hash value by the total weight of
2377 the running servers. The result designates which server will
2378 receive the request. This ensures that the same URI will
2379 always be directed to the same server as long as no server
2380 goes up or down. This is used with proxy caches and
2381 anti-virus proxies in order to maximize the cache hit rate.
2382 Note that this algorithm may only be used in an HTTP backend.
2383 This algorithm is static by default, which means that
2384 changing a server's weight on the fly will have no effect,
2385 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002386
Oskar Stolc8dc41842012-05-19 10:19:54 +01002387 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02002388 "depth", both followed by a positive integer number. These
2389 options may be helpful when it is needed to balance servers
2390 based on the beginning of the URI only. The "len" parameter
2391 indicates that the algorithm should only consider that many
2392 characters at the beginning of the URI to compute the hash.
2393 Note that having "len" set to 1 rarely makes sense since most
2394 URIs start with a leading "/".
2395
2396 The "depth" parameter indicates the maximum directory depth
2397 to be used to compute the hash. One level is counted for each
2398 slash in the request. If both parameters are specified, the
2399 evaluation stops when either is reached.
2400
Willy Tarreau0ba27502007-12-24 16:55:16 +01002401 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002402 the query string of each HTTP GET request.
2403
2404 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02002405 request entity will be searched for the parameter argument,
2406 when it is not found in a query string after a question mark
Willy Tarreau226071e2014-04-10 11:55:45 +02002407 ('?') in the URL. The message body will only start to be
2408 analyzed once either the advertised amount of data has been
2409 received or the request buffer is full. In the unlikely event
2410 that chunked encoding is used, only the first chunk is
Cyril Bontédc4d9032012-04-08 21:57:39 +02002411 scanned. Parameter values separated by a chunk boundary, may
Willy Tarreau226071e2014-04-10 11:55:45 +02002412 be randomly balanced if at all. This keyword used to support
2413 an optional <max_wait> parameter which is now ignored.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002414
2415 If the parameter is found followed by an equal sign ('=') and
2416 a value, then the value is hashed and divided by the total
2417 weight of the running servers. The result designates which
2418 server will receive the request.
2419
2420 This is used to track user identifiers in requests and ensure
2421 that a same user ID will always be sent to the same server as
2422 long as no server goes up or down. If no value is found or if
2423 the parameter is not found, then a round robin algorithm is
2424 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002425 backend. This algorithm is static by default, which means
2426 that changing a server's weight on the fly will have no
2427 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002428
Cyril Bontédc4d9032012-04-08 21:57:39 +02002429 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
2430 request. Just as with the equivalent ACL 'hdr()' function,
2431 the header name in parenthesis is not case sensitive. If the
2432 header is absent or if it does not contain any value, the
2433 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01002434
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002435 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01002436 reducing the hash algorithm to the main domain part with some
2437 specific headers such as 'Host'. For instance, in the Host
2438 value "haproxy.1wt.eu", only "1wt" will be considered.
2439
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002440 This algorithm is static by default, which means that
2441 changing a server's weight on the fly will have no effect,
2442 but this can be changed using "hash-type".
2443
Emeric Brun736aa232009-06-30 17:56:00 +02002444 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02002445 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02002446 The RDP cookie <name> (or "mstshash" if omitted) will be
2447 looked up and hashed for each incoming TCP request. Just as
2448 with the equivalent ACL 'req_rdp_cookie()' function, the name
2449 is not case-sensitive. This mechanism is useful as a degraded
2450 persistence mode, as it makes it possible to always send the
2451 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002452 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02002453 used instead.
2454
2455 Note that for this to work, the frontend must ensure that an
2456 RDP cookie is already present in the request buffer. For this
2457 you must use 'tcp-request content accept' rule combined with
2458 a 'req_rdp_cookie_cnt' ACL.
2459
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002460 This algorithm is static by default, which means that
2461 changing a server's weight on the fly will have no effect,
2462 but this can be changed using "hash-type".
2463
Cyril Bontédc4d9032012-04-08 21:57:39 +02002464 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09002465
Willy Tarreau0ba27502007-12-24 16:55:16 +01002466 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02002467 algorithms. Right now, only "url_param" and "uri" support an
2468 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002469
Willy Tarreau3cd9af22009-03-15 14:06:41 +01002470 The load balancing algorithm of a backend is set to roundrobin when no other
2471 algorithm, mode nor option have been set. The algorithm may only be set once
2472 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002473
2474 Examples :
2475 balance roundrobin
2476 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002477 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01002478 balance hdr(User-Agent)
2479 balance hdr(host)
2480 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002481
2482 Note: the following caveats and limitations on using the "check_post"
2483 extension with "url_param" must be considered :
2484
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002485 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002486 to determine if the parameters will be found in the body or entity which
2487 may contain binary data. Therefore another method may be required to
2488 restrict consideration of POST requests that have no URL parameters in
2489 the body. (see acl reqideny http_end)
2490
2491 - using a <max_wait> value larger than the request buffer size does not
2492 make sense and is useless. The buffer size is set at build time, and
2493 defaults to 16 kB.
2494
2495 - Content-Encoding is not supported, the parameter search will probably
2496 fail; and load balancing will fall back to Round Robin.
2497
2498 - Expect: 100-continue is not supported, load balancing will fall back to
2499 Round Robin.
2500
Lukas Tribus23953682017-04-28 13:24:30 +00002501 - Transfer-Encoding (RFC7230 3.3.1) is only supported in the first chunk.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002502 If the entire parameter value is not present in the first chunk, the
2503 selection of server is undefined (actually, defined by how little
2504 actually appeared in the first chunk).
2505
2506 - This feature does not support generation of a 100, 411 or 501 response.
2507
2508 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002509 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002510 white space or control characters are found, indicating the end of what
2511 might be a URL parameter list. This is probably not a concern with SGML
2512 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002513
Willy Tarreau294d0f02015-08-10 19:40:12 +02002514 See also : "dispatch", "cookie", "transparent", "hash-type" and "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002515
2516
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002517bind [<address>]:<port_range> [, ...] [param*]
2518bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002519 Define one or several listening addresses and/or ports in a frontend.
2520 May be used in sections : defaults | frontend | listen | backend
2521 no | yes | yes | no
2522 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01002523 <address> is optional and can be a host name, an IPv4 address, an IPv6
2524 address, or '*'. It designates the address the frontend will
2525 listen on. If unset, all IPv4 addresses of the system will be
2526 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01002527 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreau24709282013-03-10 21:32:12 +01002528 Optionally, an address family prefix may be used before the
2529 address to force the family regardless of the address format,
2530 which can be useful to specify a path to a unix socket with
2531 no slash ('/'). Currently supported prefixes are :
2532 - 'ipv4@' -> address is always IPv4
2533 - 'ipv6@' -> address is always IPv6
2534 - 'unix@' -> address is a path to a local unix socket
Willy Tarreau70f72e02014-07-08 00:37:50 +02002535 - 'abns@' -> address is in abstract namespace (Linux only).
2536 Note: since abstract sockets are not "rebindable", they
2537 do not cope well with multi-process mode during
2538 soft-restart, so it is better to avoid them if
2539 nbproc is greater than 1. The effect is that if the
2540 new process fails to start, only one of the old ones
2541 will be able to rebind to the socket.
Willy Tarreau40aa0702013-03-10 23:51:38 +01002542 - 'fd@<n>' -> use file descriptor <n> inherited from the
2543 parent. The fd must be bound and may or may not already
2544 be listening.
William Lallemandb2f07452015-05-12 14:27:13 +02002545 You may want to reference some environment variables in the
2546 address parameter, see section 2.3 about environment
2547 variables.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01002548
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002549 <port_range> is either a unique TCP port, or a port range for which the
2550 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002551 above. The port is mandatory for TCP listeners. Note that in
2552 the case of an IPv6 address, the port is always the number
2553 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002554 - a numerical port (ex: '80')
2555 - a dash-delimited ports range explicitly stating the lower
2556 and upper bounds (ex: '2000-2100') which are included in
2557 the range.
2558
2559 Particular care must be taken against port ranges, because
2560 every <address:port> couple consumes one socket (= a file
2561 descriptor), so it's easy to consume lots of descriptors
2562 with a simple range, and to run out of sockets. Also, each
2563 <address:port> couple must be used only once among all
2564 instances running on a same system. Please note that binding
2565 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002566 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002567 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002568
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002569 <path> is a UNIX socket path beginning with a slash ('/'). This is
2570 alternative to the TCP listening port. Haproxy will then
2571 receive UNIX connections on the socket located at this place.
2572 The path must begin with a slash and by default is absolute.
2573 It can be relative to the prefix defined by "unix-bind" in
2574 the global section. Note that the total length of the prefix
2575 followed by the socket path cannot exceed some system limits
2576 for UNIX sockets, which commonly are set to 107 characters.
2577
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002578 <param*> is a list of parameters common to all sockets declared on the
2579 same line. These numerous parameters depend on OS and build
2580 options and have a complete section dedicated to them. Please
2581 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002582
Willy Tarreau0ba27502007-12-24 16:55:16 +01002583 It is possible to specify a list of address:port combinations delimited by
2584 commas. The frontend will then listen on all of these addresses. There is no
2585 fixed limit to the number of addresses and ports which can be listened on in
2586 a frontend, as well as there is no limit to the number of "bind" statements
2587 in a frontend.
2588
2589 Example :
2590 listen http_proxy
2591 bind :80,:443
2592 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002593 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01002594
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002595 listen http_https_proxy
2596 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02002597 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002598
Willy Tarreau24709282013-03-10 21:32:12 +01002599 listen http_https_proxy_explicit
2600 bind ipv6@:80
2601 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
2602 bind unix@ssl-frontend.sock user root mode 600 accept-proxy
2603
Willy Tarreaudad36a32013-03-11 01:20:04 +01002604 listen external_bind_app1
William Lallemandb2f07452015-05-12 14:27:13 +02002605 bind "fd@${FD_APP1}"
Willy Tarreaudad36a32013-03-11 01:20:04 +01002606
Willy Tarreau55dcaf62015-09-27 15:03:15 +02002607 Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
2608 sun_path length is used for the address length. Some other programs
2609 such as socat use the string length only by default. Pass the option
2610 ",unix-tightsocklen=0" to any abstract socket definition in socat to
2611 make it compatible with HAProxy's.
2612
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002613 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002614 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002615
2616
Christopher Fauletff4121f2017-11-22 16:38:49 +01002617bind-process [ all | odd | even | <process_num>[-[<process_num>]] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002618 Limit visibility of an instance to a certain set of processes numbers.
2619 May be used in sections : defaults | frontend | listen | backend
2620 yes | yes | yes | yes
2621 Arguments :
2622 all All process will see this instance. This is the default. It
2623 may be used to override a default value.
2624
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002625 odd This instance will be enabled on processes 1,3,5,...63. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002626 option may be combined with other numbers.
2627
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002628 even This instance will be enabled on processes 2,4,6,...64. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002629 option may be combined with other numbers. Do not use it
2630 with less than 2 processes otherwise some instances might be
2631 missing from all processes.
2632
Christopher Fauletff4121f2017-11-22 16:38:49 +01002633 process_num The instance will be enabled on this process number or range,
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002634 whose values must all be between 1 and 32 or 64 depending on
Christopher Fauletff4121f2017-11-22 16:38:49 +01002635 the machine's word size. Ranges can be partially defined. The
2636 higher bound can be omitted. In such case, it is replaced by
2637 the corresponding maximum value. If a proxy is bound to
2638 process numbers greater than the configured global.nbproc, it
2639 will either be forced to process #1 if a single process was
Willy Tarreau102df612014-05-07 23:56:38 +02002640 specified, or to all processes otherwise.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002641
2642 This keyword limits binding of certain instances to certain processes. This
2643 is useful in order not to have too many processes listening to the same
2644 ports. For instance, on a dual-core machine, it might make sense to set
2645 'nbproc 2' in the global section, then distributes the listeners among 'odd'
2646 and 'even' instances.
2647
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002648 At the moment, it is not possible to reference more than 32 or 64 processes
2649 using this keyword, but this should be more than enough for most setups.
2650 Please note that 'all' really means all processes regardless of the machine's
2651 word size, and is not limited to the first 32 or 64.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002652
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02002653 Each "bind" line may further be limited to a subset of the proxy's processes,
2654 please consult the "process" bind keyword in section 5.1.
2655
Willy Tarreaub369a042014-09-16 13:21:03 +02002656 When a frontend has no explicit "bind-process" line, it tries to bind to all
2657 the processes referenced by its "bind" lines. That means that frontends can
2658 easily adapt to their listeners' processes.
2659
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002660 If some backends are referenced by frontends bound to other processes, the
2661 backend automatically inherits the frontend's processes.
2662
2663 Example :
2664 listen app_ip1
2665 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02002666 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002667
2668 listen app_ip2
2669 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02002670 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002671
2672 listen management
2673 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02002674 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002675
Willy Tarreau110ecc12012-11-15 17:50:01 +01002676 listen management
2677 bind 10.0.0.4:80
2678 bind-process 1-4
2679
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02002680 See also : "nbproc" in global section, and "process" in section 5.1.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002681
2682
Jarno Huuskonen8c8c3492016-12-28 18:50:29 +02002683block { if | unless } <condition> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002684 Block a layer 7 request if/unless a condition is matched
2685 May be used in sections : defaults | frontend | listen | backend
2686 no | yes | yes | yes
2687
2688 The HTTP request will be blocked very early in the layer 7 processing
2689 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002690 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02002691 typically used to deny access to certain sensitive resources if some
Willy Tarreau0ba27502007-12-24 16:55:16 +01002692 conditions are met or not met. There is no fixed limit to the number of
Jarno Huuskonen95b012b2017-04-06 13:59:14 +03002693 "block" statements per instance. To block connections at layer 4 (without
2694 sending a 403 error) see "tcp-request connection reject" and
2695 "tcp-request content reject" rules.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002696
Jarno Huuskonen8c8c3492016-12-28 18:50:29 +02002697 This form is deprecated, do not use it in any new configuration, use the new
2698 "http-request deny" instead.
2699
Willy Tarreau0ba27502007-12-24 16:55:16 +01002700 Example:
2701 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
2702 acl invalid_src src_port 0:1023
2703 acl local_dst hdr(host) -i localhost
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +03002704 # block is deprecated. Use http-request deny instead:
2705 #block if invalid_src || local_dst
2706 http-request deny if invalid_src || local_dst
Willy Tarreau0ba27502007-12-24 16:55:16 +01002707
Jarno Huuskonen95b012b2017-04-06 13:59:14 +03002708 See also : section 7 about ACL usage, "http-request deny",
2709 "http-response deny", "tcp-request connection reject" and
2710 "tcp-request content reject".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002711
2712capture cookie <name> len <length>
2713 Capture and log a cookie in the request and in the response.
2714 May be used in sections : defaults | frontend | listen | backend
2715 no | yes | yes | no
2716 Arguments :
2717 <name> is the beginning of the name of the cookie to capture. In order
2718 to match the exact name, simply suffix the name with an equal
2719 sign ('='). The full name will appear in the logs, which is
2720 useful with application servers which adjust both the cookie name
2721 and value (eg: ASPSESSIONXXXXX).
2722
2723 <length> is the maximum number of characters to report in the logs, which
2724 include the cookie name, the equal sign and the value, all in the
2725 standard "name=value" form. The string will be truncated on the
2726 right if it exceeds <length>.
2727
2728 Only the first cookie is captured. Both the "cookie" request headers and the
2729 "set-cookie" response headers are monitored. This is particularly useful to
2730 check for application bugs causing session crossing or stealing between
2731 users, because generally the user's cookies can only change on a login page.
2732
2733 When the cookie was not presented by the client, the associated log column
2734 will report "-". When a request does not cause a cookie to be assigned by the
2735 server, a "-" is reported in the response column.
2736
2737 The capture is performed in the frontend only because it is necessary that
2738 the log format does not change for a given frontend depending on the
2739 backends. This may change in the future. Note that there can be only one
Willy Tarreau193b8c62012-11-22 00:17:38 +01002740 "capture cookie" statement in a frontend. The maximum capture length is set
2741 by the global "tune.http.cookielen" setting and defaults to 63 characters. It
2742 is not possible to specify a capture in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002743
2744 Example:
2745 capture cookie ASPSESSION len 32
2746
2747 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002748 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002749
2750
2751capture request header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01002752 Capture and log the last occurrence of the specified request header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002753 May be used in sections : defaults | frontend | listen | backend
2754 no | yes | yes | no
2755 Arguments :
2756 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002757 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01002758 appear in the requests, with the first letter of each word in
2759 upper case. The header name will not appear in the logs, only the
2760 value is reported, but the position in the logs is respected.
2761
2762 <length> is the maximum number of characters to extract from the value and
2763 report in the logs. The string will be truncated on the right if
2764 it exceeds <length>.
2765
Willy Tarreau4460d032012-11-21 23:37:37 +01002766 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01002767 value will be added to the logs between braces ('{}'). If multiple headers
2768 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002769 in the same order they were declared in the configuration. Non-existent
2770 headers will be logged just as an empty string. Common uses for request
2771 header captures include the "Host" field in virtual hosting environments, the
2772 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002773 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002774 environments to find where the request came from.
2775
2776 Note that when capturing headers such as "User-agent", some spaces may be
2777 logged, making the log analysis more difficult. Thus be careful about what
2778 you log if you know your log parser is not smart enough to rely on the
2779 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002780
Willy Tarreau0900abb2012-11-22 00:21:46 +01002781 There is no limit to the number of captured request headers nor to their
2782 length, though it is wise to keep them low to limit memory usage per session.
2783 In order to keep log format consistent for a same frontend, header captures
2784 can only be declared in a frontend. It is not possible to specify a capture
2785 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002786
2787 Example:
2788 capture request header Host len 15
2789 capture request header X-Forwarded-For len 15
Cyril Bontéd1b0f7c2015-10-26 22:37:39 +01002790 capture request header Referer len 15
Willy Tarreau0ba27502007-12-24 16:55:16 +01002791
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002792 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01002793 about logging.
2794
2795
2796capture response header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01002797 Capture and log the last occurrence of the specified response header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002798 May be used in sections : defaults | frontend | listen | backend
2799 no | yes | yes | no
2800 Arguments :
2801 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002802 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01002803 appear in the response, with the first letter of each word in
2804 upper case. The header name will not appear in the logs, only the
2805 value is reported, but the position in the logs is respected.
2806
2807 <length> is the maximum number of characters to extract from the value and
2808 report in the logs. The string will be truncated on the right if
2809 it exceeds <length>.
2810
Willy Tarreau4460d032012-11-21 23:37:37 +01002811 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01002812 result will be added to the logs between braces ('{}') after the captured
2813 request headers. If multiple headers are captured, they will be delimited by
2814 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002815 the configuration. Non-existent headers will be logged just as an empty
2816 string. Common uses for response header captures include the "Content-length"
2817 header which indicates how many bytes are expected to be returned, the
2818 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002819
Willy Tarreau0900abb2012-11-22 00:21:46 +01002820 There is no limit to the number of captured response headers nor to their
2821 length, though it is wise to keep them low to limit memory usage per session.
2822 In order to keep log format consistent for a same frontend, header captures
2823 can only be declared in a frontend. It is not possible to specify a capture
2824 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002825
2826 Example:
2827 capture response header Content-length len 9
2828 capture response header Location len 15
2829
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002830 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01002831 about logging.
2832
2833
Cyril Bontéf0c60612010-02-06 14:44:47 +01002834clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002835 Set the maximum inactivity time on the client side.
2836 May be used in sections : defaults | frontend | listen | backend
2837 yes | yes | yes | no
2838 Arguments :
2839 <timeout> is the timeout value is specified in milliseconds by default, but
2840 can be in any other unit if the number is suffixed by the unit,
2841 as explained at the top of this document.
2842
2843 The inactivity timeout applies when the client is expected to acknowledge or
2844 send data. In HTTP mode, this timeout is particularly important to consider
2845 during the first phase, when the client sends the request, and during the
2846 response while it is reading data sent by the server. The value is specified
2847 in milliseconds by default, but can be in any other unit if the number is
2848 suffixed by the unit, as specified at the top of this document. In TCP mode
2849 (and to a lesser extent, in HTTP mode), it is highly recommended that the
2850 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002851 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01002852 losses by specifying timeouts that are slightly above multiples of 3 seconds
2853 (eg: 4 or 5 seconds).
2854
2855 This parameter is specific to frontends, but can be specified once for all in
2856 "defaults" sections. This is in fact one of the easiest solutions not to
2857 forget about it. An unspecified timeout results in an infinite timeout, which
2858 is not recommended. Such a usage is accepted and works but reports a warning
2859 during startup because it may results in accumulation of expired sessions in
2860 the system if the system's timeouts are not configured either.
2861
2862 This parameter is provided for compatibility but is currently deprecated.
2863 Please use "timeout client" instead.
2864
Willy Tarreau036fae02008-01-06 13:24:40 +01002865 See also : "timeout client", "timeout http-request", "timeout server", and
2866 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002867
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002868compression algo <algorithm> ...
2869compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02002870compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02002871 Enable HTTP compression.
2872 May be used in sections : defaults | frontend | listen | backend
2873 yes | yes | yes | yes
2874 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002875 algo is followed by the list of supported compression algorithms.
2876 type is followed by the list of MIME types that will be compressed.
2877 offload makes haproxy work as a compression offloader only (see notes).
2878
2879 The currently supported algorithms are :
Willy Tarreauc91840a2015-03-28 17:00:39 +01002880 identity this is mostly for debugging, and it was useful for developing
2881 the compression feature. Identity does not apply any change on
2882 data.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002883
Willy Tarreauc91840a2015-03-28 17:00:39 +01002884 gzip applies gzip compression. This setting is only available when
Baptiste Assmannf085d632015-12-21 17:57:32 +01002885 support for zlib or libslz was built in.
Willy Tarreauc91840a2015-03-28 17:00:39 +01002886
2887 deflate same as "gzip", but with deflate algorithm and zlib format.
2888 Note that this algorithm has ambiguous support on many
2889 browsers and no support at all from recent ones. It is
2890 strongly recommended not to use it for anything else than
2891 experimentation. This setting is only available when support
Baptiste Assmannf085d632015-12-21 17:57:32 +01002892 for zlib or libslz was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002893
Willy Tarreauc91840a2015-03-28 17:00:39 +01002894 raw-deflate same as "deflate" without the zlib wrapper, and used as an
2895 alternative when the browser wants "deflate". All major
2896 browsers understand it and despite violating the standards,
2897 it is known to work better than "deflate", at least on MSIE
2898 and some versions of Safari. Do not use it in conjunction
2899 with "deflate", use either one or the other since both react
2900 to the same Accept-Encoding token. This setting is only
Baptiste Assmannf085d632015-12-21 17:57:32 +01002901 available when support for zlib or libslz was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002902
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04002903 Compression will be activated depending on the Accept-Encoding request
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002904 header. With identity, it does not take care of that header.
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04002905 If backend servers support HTTP compression, these directives
2906 will be no-op: haproxy will see the compressed response and will not
2907 compress again. If backend servers do not support HTTP compression and
2908 there is Accept-Encoding header in request, haproxy will compress the
2909 matching response.
Willy Tarreau70737d12012-10-27 00:34:28 +02002910
2911 The "offload" setting makes haproxy remove the Accept-Encoding header to
2912 prevent backend servers from compressing responses. It is strongly
2913 recommended not to do this because this means that all the compression work
2914 will be done on the single point where haproxy is located. However in some
2915 deployment scenarios, haproxy may be installed in front of a buggy gateway
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04002916 with broken HTTP compression implementation which can't be turned off.
2917 In that case haproxy can be used to prevent that gateway from emitting
2918 invalid payloads. In this case, simply removing the header in the
2919 configuration does not work because it applies before the header is parsed,
2920 so that prevents haproxy from compressing. The "offload" setting should
Willy Tarreauffea9fd2014-07-12 16:37:02 +02002921 then be used for such scenarios. Note: for now, the "offload" setting is
2922 ignored when set in a defaults section.
William Lallemand82fe75c2012-10-23 10:25:10 +02002923
William Lallemand05097442012-11-20 12:14:28 +01002924 Compression is disabled when:
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002925 * the request does not advertise a supported compression algorithm in the
2926 "Accept-Encoding" header
2927 * the response message is not HTTP/1.1
William Lallemandd3002612012-11-26 14:34:47 +01002928 * HTTP status code is not 200
William Lallemand8bb4e342013-12-10 17:28:48 +01002929 * response header "Transfer-Encoding" contains "chunked" (Temporary
2930 Workaround)
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002931 * response contain neither a "Content-Length" header nor a
2932 "Transfer-Encoding" whose last value is "chunked"
2933 * response contains a "Content-Type" header whose first value starts with
2934 "multipart"
2935 * the response contains the "no-transform" value in the "Cache-control"
2936 header
2937 * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7
2938 and later
2939 * The response contains a "Content-Encoding" header, indicating that the
2940 response is already compressed (see compression offload)
William Lallemand05097442012-11-20 12:14:28 +01002941
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002942 Note: The compression does not rewrite Etag headers, and does not emit the
2943 Warning header.
William Lallemand05097442012-11-20 12:14:28 +01002944
William Lallemand82fe75c2012-10-23 10:25:10 +02002945 Examples :
2946 compression algo gzip
2947 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01002948
Christopher Fauletc3fe5332016-04-07 15:30:10 +02002949
Cyril Bontéf0c60612010-02-06 14:44:47 +01002950contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002951 Set the maximum time to wait for a connection attempt to a server to succeed.
2952 May be used in sections : defaults | frontend | listen | backend
2953 yes | no | yes | yes
2954 Arguments :
2955 <timeout> is the timeout value is specified in milliseconds by default, but
2956 can be in any other unit if the number is suffixed by the unit,
2957 as explained at the top of this document.
2958
2959 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002960 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01002961 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01002962 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
2963 connect timeout also presets the queue timeout to the same value if this one
2964 has not been specified. Historically, the contimeout was also used to set the
2965 tarpit timeout in a listen section, which is not possible in a pure frontend.
2966
2967 This parameter is specific to backends, but can be specified once for all in
2968 "defaults" sections. This is in fact one of the easiest solutions not to
2969 forget about it. An unspecified timeout results in an infinite timeout, which
2970 is not recommended. Such a usage is accepted and works but reports a warning
2971 during startup because it may results in accumulation of failed sessions in
2972 the system if the system's timeouts are not configured either.
2973
2974 This parameter is provided for backwards compatibility but is currently
2975 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
2976 instead.
2977
2978 See also : "timeout connect", "timeout queue", "timeout tarpit",
2979 "timeout server", "contimeout".
2980
2981
Willy Tarreau55165fe2009-05-10 12:02:55 +02002982cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02002983 [ postonly ] [ preserve ] [ httponly ] [ secure ]
2984 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Olivier Houchard4e694042017-03-14 20:01:29 +01002985 [ dynamic ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002986 Enable cookie-based persistence in a backend.
2987 May be used in sections : defaults | frontend | listen | backend
2988 yes | no | yes | yes
2989 Arguments :
2990 <name> is the name of the cookie which will be monitored, modified or
2991 inserted in order to bring persistence. This cookie is sent to
2992 the client via a "Set-Cookie" header in the response, and is
2993 brought back by the client in a "Cookie" header in all requests.
2994 Special care should be taken to choose a name which does not
2995 conflict with any likely application cookie. Also, if the same
2996 backends are subject to be used by the same clients (eg:
2997 HTTP/HTTPS), care should be taken to use different cookie names
2998 between all backends if persistence between them is not desired.
2999
3000 rewrite This keyword indicates that the cookie will be provided by the
3001 server and that haproxy will have to modify its value to set the
3002 server's identifier in it. This mode is handy when the management
3003 of complex combinations of "Set-cookie" and "Cache-control"
3004 headers is left to the application. The application can then
3005 decide whether or not it is appropriate to emit a persistence
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003006 cookie. Since all responses should be monitored, this mode
3007 doesn't work in HTTP tunnel mode. Unless the application
3008 behaviour is very complex and/or broken, it is advised not to
3009 start with this mode for new deployments. This keyword is
3010 incompatible with "insert" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003011
3012 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02003013 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003014
Willy Tarreaua79094d2010-08-31 22:54:15 +02003015 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003016 server. When used without the "preserve" option, if the server
3017 emits a cookie with the same name, it will be remove before
3018 processing. For this reason, this mode can be used to upgrade
3019 existing configurations running in the "rewrite" mode. The cookie
3020 will only be a session cookie and will not be stored on the
3021 client's disk. By default, unless the "indirect" option is added,
3022 the server will see the cookies emitted by the client. Due to
3023 caching effects, it is generally wise to add the "nocache" or
3024 "postonly" keywords (see below). The "insert" keyword is not
3025 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003026
3027 prefix This keyword indicates that instead of relying on a dedicated
3028 cookie for the persistence, an existing one will be completed.
3029 This may be needed in some specific environments where the client
3030 does not support more than one single cookie and the application
3031 already needs it. In this case, whenever the server sets a cookie
3032 named <name>, it will be prefixed with the server's identifier
3033 and a delimiter. The prefix will be removed from all client
3034 requests so that the server still finds the cookie it emitted.
3035 Since all requests and responses are subject to being modified,
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003036 this mode doesn't work with tunnel mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02003037 not compatible with "rewrite" and "insert". Note: it is highly
3038 recommended not to use "indirect" with "prefix", otherwise server
3039 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003040
Willy Tarreaua79094d2010-08-31 22:54:15 +02003041 indirect When this option is specified, no cookie will be emitted to a
3042 client which already has a valid one for the server which has
3043 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003044 it will be removed, unless the "preserve" option is also set. In
3045 "insert" mode, this will additionally remove cookies from the
3046 requests transmitted to the server, making the persistence
3047 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02003048 Note: it is highly recommended not to use "indirect" with
3049 "prefix", otherwise server cookie updates would not be sent to
3050 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003051
3052 nocache This option is recommended in conjunction with the insert mode
3053 when there is a cache between the client and HAProxy, as it
3054 ensures that a cacheable response will be tagged non-cacheable if
3055 a cookie needs to be inserted. This is important because if all
3056 persistence cookies are added on a cacheable home page for
3057 instance, then all customers will then fetch the page from an
3058 outer cache and will all share the same persistence cookie,
3059 leading to one server receiving much more traffic than others.
3060 See also the "insert" and "postonly" options.
3061
3062 postonly This option ensures that cookie insertion will only be performed
3063 on responses to POST requests. It is an alternative to the
3064 "nocache" option, because POST responses are not cacheable, so
3065 this ensures that the persistence cookie will never get cached.
3066 Since most sites do not need any sort of persistence before the
3067 first POST which generally is a login request, this is a very
3068 efficient method to optimize caching without risking to find a
3069 persistence cookie in the cache.
3070 See also the "insert" and "nocache" options.
3071
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003072 preserve This option may only be used with "insert" and/or "indirect". It
3073 allows the server to emit the persistence cookie itself. In this
3074 case, if a cookie is found in the response, haproxy will leave it
3075 untouched. This is useful in order to end persistence after a
3076 logout request for instance. For this, the server just has to
3077 emit a cookie with an invalid value (eg: empty) or with a date in
3078 the past. By combining this mechanism with the "disable-on-404"
3079 check option, it is possible to perform a completely graceful
3080 shutdown because users will definitely leave the server after
3081 they logout.
3082
Willy Tarreau4992dd22012-05-31 21:02:17 +02003083 httponly This option tells haproxy to add an "HttpOnly" cookie attribute
3084 when a cookie is inserted. This attribute is used so that a
3085 user agent doesn't share the cookie with non-HTTP components.
3086 Please check RFC6265 for more information on this attribute.
3087
3088 secure This option tells haproxy to add a "Secure" cookie attribute when
3089 a cookie is inserted. This attribute is used so that a user agent
3090 never emits this cookie over non-secure channels, which means
3091 that a cookie learned with this flag will be presented only over
3092 SSL/TLS connections. Please check RFC6265 for more information on
3093 this attribute.
3094
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02003095 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003096 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01003097 name. If the domain begins with a dot, the browser is allowed to
3098 use it for any host ending with that name. It is also possible to
3099 specify several domain names by invoking this option multiple
3100 times. Some browsers might have small limits on the number of
3101 domains, so be careful when doing that. For the record, sending
3102 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02003103
Willy Tarreau996a92c2010-10-13 19:30:47 +02003104 maxidle This option allows inserted cookies to be ignored after some idle
3105 time. It only works with insert-mode cookies. When a cookie is
3106 sent to the client, the date this cookie was emitted is sent too.
3107 Upon further presentations of this cookie, if the date is older
3108 than the delay indicated by the parameter (in seconds), it will
3109 be ignored. Otherwise, it will be refreshed if needed when the
3110 response is sent to the client. This is particularly useful to
3111 prevent users who never close their browsers from remaining for
3112 too long on the same server (eg: after a farm size change). When
3113 this option is set and a cookie has no date, it is always
3114 accepted, but gets refreshed in the response. This maintains the
3115 ability for admins to access their sites. Cookies that have a
3116 date in the future further than 24 hours are ignored. Doing so
3117 lets admins fix timezone issues without risking kicking users off
3118 the site.
3119
3120 maxlife This option allows inserted cookies to be ignored after some life
3121 time, whether they're in use or not. It only works with insert
3122 mode cookies. When a cookie is first sent to the client, the date
3123 this cookie was emitted is sent too. Upon further presentations
3124 of this cookie, if the date is older than the delay indicated by
3125 the parameter (in seconds), it will be ignored. If the cookie in
3126 the request has no date, it is accepted and a date will be set.
3127 Cookies that have a date in the future further than 24 hours are
3128 ignored. Doing so lets admins fix timezone issues without risking
3129 kicking users off the site. Contrary to maxidle, this value is
3130 not refreshed, only the first visit date counts. Both maxidle and
3131 maxlife may be used at the time. This is particularly useful to
3132 prevent users who never close their browsers from remaining for
3133 too long on the same server (eg: after a farm size change). This
3134 is stronger than the maxidle method in that it forces a
3135 redispatch after some absolute delay.
3136
Olivier Houchard4e694042017-03-14 20:01:29 +01003137 dynamic Activate dynamic cookies. When used, a session cookie is
3138 dynamically created for each server, based on the IP and port
3139 of the server, and a secret key, specified in the
3140 "dynamic-cookie-key" backend directive.
3141 The cookie will be regenerated each time the IP address change,
3142 and is only generated for IPv4/IPv6.
3143
Willy Tarreau0ba27502007-12-24 16:55:16 +01003144 There can be only one persistence cookie per HTTP backend, and it can be
3145 declared in a defaults section. The value of the cookie will be the value
3146 indicated after the "cookie" keyword in a "server" statement. If no cookie
3147 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02003148
Willy Tarreau0ba27502007-12-24 16:55:16 +01003149 Examples :
3150 cookie JSESSIONID prefix
3151 cookie SRV insert indirect nocache
3152 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02003153 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01003154
Willy Tarreau294d0f02015-08-10 19:40:12 +02003155 See also : "balance source", "capture cookie", "server" and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003156
Willy Tarreau983e01e2010-01-11 18:42:06 +01003157
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02003158declare capture [ request | response ] len <length>
3159 Declares a capture slot.
3160 May be used in sections : defaults | frontend | listen | backend
3161 no | yes | yes | no
3162 Arguments:
3163 <length> is the length allowed for the capture.
3164
3165 This declaration is only available in the frontend or listen section, but the
3166 reserved slot can be used in the backends. The "request" keyword allocates a
3167 capture slot for use in the request, and "response" allocates a capture slot
3168 for use in the response.
3169
3170 See also: "capture-req", "capture-res" (sample converters),
Baptiste Assmann5ac425c2015-10-21 23:13:46 +02003171 "capture.req.hdr", "capture.res.hdr" (sample fetches),
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02003172 "http-request capture" and "http-response capture".
3173
3174
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003175default-server [param*]
3176 Change default options for a server in a backend
3177 May be used in sections : defaults | frontend | listen | backend
3178 yes | no | yes | yes
3179 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01003180 <param*> is a list of parameters for this server. The "default-server"
3181 keyword accepts an important number of options and has a complete
3182 section dedicated to it. Please refer to section 5 for more
3183 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003184
Willy Tarreau983e01e2010-01-11 18:42:06 +01003185 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003186 default-server inter 1000 weight 13
3187
3188 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01003189
Willy Tarreau983e01e2010-01-11 18:42:06 +01003190
Willy Tarreau0ba27502007-12-24 16:55:16 +01003191default_backend <backend>
3192 Specify the backend to use when no "use_backend" rule has been matched.
3193 May be used in sections : defaults | frontend | listen | backend
3194 yes | yes | yes | no
3195 Arguments :
3196 <backend> is the name of the backend to use.
3197
3198 When doing content-switching between frontend and backends using the
3199 "use_backend" keyword, it is often useful to indicate which backend will be
3200 used when no rule has matched. It generally is the dynamic backend which
3201 will catch all undetermined requests.
3202
Willy Tarreau0ba27502007-12-24 16:55:16 +01003203 Example :
3204
3205 use_backend dynamic if url_dyn
3206 use_backend static if url_css url_img extension_img
3207 default_backend dynamic
3208
Willy Tarreau98d04852015-05-26 12:18:29 +02003209 See also : "use_backend"
Willy Tarreau2769aa02007-12-27 18:26:09 +01003210
Willy Tarreau0ba27502007-12-24 16:55:16 +01003211
Baptiste Assmann27f51342013-10-09 06:51:49 +02003212description <string>
3213 Describe a listen, frontend or backend.
3214 May be used in sections : defaults | frontend | listen | backend
3215 no | yes | yes | yes
3216 Arguments : string
3217
3218 Allows to add a sentence to describe the related object in the HAProxy HTML
3219 stats page. The description will be printed on the right of the object name
3220 it describes.
3221 No need to backslash spaces in the <string> arguments.
3222
3223
Willy Tarreau0ba27502007-12-24 16:55:16 +01003224disabled
3225 Disable a proxy, frontend or backend.
3226 May be used in sections : defaults | frontend | listen | backend
3227 yes | yes | yes | yes
3228 Arguments : none
3229
3230 The "disabled" keyword is used to disable an instance, mainly in order to
3231 liberate a listening port or to temporarily disable a service. The instance
3232 will still be created and its configuration will be checked, but it will be
3233 created in the "stopped" state and will appear as such in the statistics. It
3234 will not receive any traffic nor will it send any health-checks or logs. It
3235 is possible to disable many instances at once by adding the "disabled"
3236 keyword in a "defaults" section.
3237
3238 See also : "enabled"
3239
3240
Willy Tarreau5ce94572010-06-07 14:35:41 +02003241dispatch <address>:<port>
3242 Set a default server address
3243 May be used in sections : defaults | frontend | listen | backend
3244 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003245 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02003246
3247 <address> is the IPv4 address of the default server. Alternatively, a
3248 resolvable hostname is supported, but this name will be resolved
3249 during start-up.
3250
3251 <ports> is a mandatory port specification. All connections will be sent
3252 to this port, and it is not permitted to use port offsets as is
3253 possible with normal servers.
3254
Willy Tarreau787aed52011-04-15 06:45:37 +02003255 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02003256 server can take the connection. In the past it was used to forward non
3257 persistent connections to an auxiliary load balancer. Due to its simple
3258 syntax, it has also been used for simple TCP relays. It is recommended not to
3259 use it for more clarity, and to use the "server" directive instead.
3260
3261 See also : "server"
3262
Olivier Houchard4e694042017-03-14 20:01:29 +01003263
3264dynamic-cookie-key <string>
3265 Set the dynamic cookie secret key for a backend.
3266 May be used in sections : defaults | frontend | listen | backend
3267 yes | no | yes | yes
3268 Arguments : The secret key to be used.
3269
3270 When dynamic cookies are enabled (see the "dynamic" directive for cookie),
3271 a dynamic cookie is created for each server (unless one is explicitely
3272 specified on the "server" line), using a hash of the IP address of the
3273 server, the TCP port, and the secret key.
3274 That way, we can ensure session persistence accross multiple load-balancers,
3275 even if servers are dynamically added or removed.
Willy Tarreau5ce94572010-06-07 14:35:41 +02003276
Willy Tarreau0ba27502007-12-24 16:55:16 +01003277enabled
3278 Enable a proxy, frontend or backend.
3279 May be used in sections : defaults | frontend | listen | backend
3280 yes | yes | yes | yes
3281 Arguments : none
3282
3283 The "enabled" keyword is used to explicitly enable an instance, when the
3284 defaults has been set to "disabled". This is very rarely used.
3285
3286 See also : "disabled"
3287
3288
3289errorfile <code> <file>
3290 Return a file contents instead of errors generated by HAProxy
3291 May be used in sections : defaults | frontend | listen | backend
3292 yes | yes | yes | yes
3293 Arguments :
3294 <code> is the HTTP status code. Currently, HAProxy is capable of
Olivier Houchard51a76d82017-10-02 16:12:07 +02003295 generating codes 200, 400, 403, 405, 408, 425, 429, 500, 502,
3296 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003297
3298 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003299 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01003300 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01003301 error pages, and to use absolute paths, since files are read
3302 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003303
3304 It is important to understand that this keyword is not meant to rewrite
3305 errors returned by the server, but errors detected and returned by HAProxy.
3306 This is why the list of supported errors is limited to a small set.
3307
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003308 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
3309
Willy Tarreau0ba27502007-12-24 16:55:16 +01003310 The files are returned verbatim on the TCP socket. This allows any trick such
3311 as redirections to another URL or site, as well as tricks to clean cookies,
3312 force enable or disable caching, etc... The package provides default error
3313 files returning the same contents as default errors.
3314
Willy Tarreau59140a22009-02-22 12:02:30 +01003315 The files should not exceed the configured buffer size (BUFSIZE), which
3316 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
3317 not to put any reference to local contents (eg: images) in order to avoid
3318 loops between the client and HAProxy when all servers are down, causing an
3319 error to be returned instead of an image. For better HTTP compliance, it is
3320 recommended that all header lines end with CR-LF and not LF alone.
3321
Willy Tarreau0ba27502007-12-24 16:55:16 +01003322 The files are read at the same time as the configuration and kept in memory.
3323 For this reason, the errors continue to be returned even when the process is
3324 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01003325 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01003326 403 status code and interrogating a blocked URL.
3327
3328 See also : "errorloc", "errorloc302", "errorloc303"
3329
Willy Tarreau59140a22009-02-22 12:02:30 +01003330 Example :
3331 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
Willy Tarreau989222a2016-01-15 10:26:26 +01003332 errorfile 408 /dev/null # work around Chrome pre-connect bug
Willy Tarreau59140a22009-02-22 12:02:30 +01003333 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
3334 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
3335
Willy Tarreau2769aa02007-12-27 18:26:09 +01003336
3337errorloc <code> <url>
3338errorloc302 <code> <url>
3339 Return an HTTP redirection to a URL instead of errors generated by HAProxy
3340 May be used in sections : defaults | frontend | listen | backend
3341 yes | yes | yes | yes
3342 Arguments :
3343 <code> is the HTTP status code. Currently, HAProxy is capable of
Olivier Houchard51a76d82017-10-02 16:12:07 +02003344 generating codes 200, 400, 403, 405, 408, 425, 429, 500, 502,
3345 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003346
3347 <url> it is the exact contents of the "Location" header. It may contain
3348 either a relative URI to an error page hosted on the same site,
3349 or an absolute URI designating an error page on another site.
3350 Special care should be given to relative URIs to avoid redirect
3351 loops if the URI itself may generate the same error (eg: 500).
3352
3353 It is important to understand that this keyword is not meant to rewrite
3354 errors returned by the server, but errors detected and returned by HAProxy.
3355 This is why the list of supported errors is limited to a small set.
3356
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003357 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
3358
Willy Tarreau2769aa02007-12-27 18:26:09 +01003359 Note that both keyword return the HTTP 302 status code, which tells the
3360 client to fetch the designated URL using the same HTTP method. This can be
3361 quite problematic in case of non-GET methods such as POST, because the URL
3362 sent to the client might not be allowed for something other than GET. To
Willy Tarreau989222a2016-01-15 10:26:26 +01003363 work around this problem, please use "errorloc303" which send the HTTP 303
Willy Tarreau2769aa02007-12-27 18:26:09 +01003364 status code, indicating to the client that the URL must be fetched with a GET
3365 request.
3366
3367 See also : "errorfile", "errorloc303"
3368
3369
3370errorloc303 <code> <url>
3371 Return an HTTP redirection to a URL instead of errors generated by HAProxy
3372 May be used in sections : defaults | frontend | listen | backend
3373 yes | yes | yes | yes
3374 Arguments :
3375 <code> is the HTTP status code. Currently, HAProxy is capable of
Olivier Houchard51a76d82017-10-02 16:12:07 +02003376 generating codes 200, 400, 403, 405, 408, 425, 429, 500, 502,
3377 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003378
3379 <url> it is the exact contents of the "Location" header. It may contain
3380 either a relative URI to an error page hosted on the same site,
3381 or an absolute URI designating an error page on another site.
3382 Special care should be given to relative URIs to avoid redirect
3383 loops if the URI itself may generate the same error (eg: 500).
3384
3385 It is important to understand that this keyword is not meant to rewrite
3386 errors returned by the server, but errors detected and returned by HAProxy.
3387 This is why the list of supported errors is limited to a small set.
3388
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003389 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
3390
Willy Tarreau2769aa02007-12-27 18:26:09 +01003391 Note that both keyword return the HTTP 303 status code, which tells the
3392 client to fetch the designated URL using the same HTTP GET method. This
3393 solves the usual problems associated with "errorloc" and the 302 code. It is
3394 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003395 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003396
3397 See also : "errorfile", "errorloc", "errorloc302"
3398
3399
Simon Horman51a1cf62015-02-03 13:00:44 +09003400email-alert from <emailaddr>
3401 Declare the from email address to be used in both the envelope and header
3402 of email alerts. This is the address that email alerts are sent from.
3403 May be used in sections: defaults | frontend | listen | backend
3404 yes | yes | yes | yes
3405
3406 Arguments :
3407
3408 <emailaddr> is the from email address to use when sending email alerts
3409
3410 Also requires "email-alert mailers" and "email-alert to" to be set
3411 and if so sending email alerts is enabled for the proxy.
3412
Simon Horman64e34162015-02-06 11:11:57 +09003413 See also : "email-alert level", "email-alert mailers",
Cyril Bonté307ee1e2015-09-28 23:16:06 +02003414 "email-alert myhostname", "email-alert to", section 3.6 about
3415 mailers.
Simon Horman64e34162015-02-06 11:11:57 +09003416
3417
3418email-alert level <level>
3419 Declare the maximum log level of messages for which email alerts will be
3420 sent. This acts as a filter on the sending of email alerts.
3421 May be used in sections: defaults | frontend | listen | backend
3422 yes | yes | yes | yes
3423
3424 Arguments :
3425
3426 <level> One of the 8 syslog levels:
3427 emerg alert crit err warning notice info debug
3428 The above syslog levels are ordered from lowest to highest.
3429
3430 By default level is alert
3431
3432 Also requires "email-alert from", "email-alert mailers" and
3433 "email-alert to" to be set and if so sending email alerts is enabled
3434 for the proxy.
3435
Simon Horman1421e212015-04-30 13:10:35 +09003436 Alerts are sent when :
3437
3438 * An un-paused server is marked as down and <level> is alert or lower
3439 * A paused server is marked as down and <level> is notice or lower
3440 * A server is marked as up or enters the drain state and <level>
3441 is notice or lower
3442 * "option log-health-checks" is enabled, <level> is info or lower,
3443 and a health check status update occurs
3444
Simon Horman64e34162015-02-06 11:11:57 +09003445 See also : "email-alert from", "email-alert mailers",
3446 "email-alert myhostname", "email-alert to",
Simon Horman51a1cf62015-02-03 13:00:44 +09003447 section 3.6 about mailers.
3448
3449
3450email-alert mailers <mailersect>
3451 Declare the mailers to be used when sending email alerts
3452 May be used in sections: defaults | frontend | listen | backend
3453 yes | yes | yes | yes
3454
3455 Arguments :
3456
3457 <mailersect> is the name of the mailers section to send email alerts.
3458
3459 Also requires "email-alert from" and "email-alert to" to be set
3460 and if so sending email alerts is enabled for the proxy.
3461
Simon Horman64e34162015-02-06 11:11:57 +09003462 See also : "email-alert from", "email-alert level", "email-alert myhostname",
3463 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09003464
3465
3466email-alert myhostname <hostname>
3467 Declare the to hostname address to be used when communicating with
3468 mailers.
3469 May be used in sections: defaults | frontend | listen | backend
3470 yes | yes | yes | yes
3471
3472 Arguments :
3473
Baptiste Assmann738bad92015-12-21 15:27:53 +01003474 <hostname> is the hostname to use when communicating with mailers
Simon Horman51a1cf62015-02-03 13:00:44 +09003475
3476 By default the systems hostname is used.
3477
3478 Also requires "email-alert from", "email-alert mailers" and
3479 "email-alert to" to be set and if so sending email alerts is enabled
3480 for the proxy.
3481
Simon Horman64e34162015-02-06 11:11:57 +09003482 See also : "email-alert from", "email-alert level", "email-alert mailers",
3483 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09003484
3485
3486email-alert to <emailaddr>
3487 Declare both the recipent address in the envelope and to address in the
3488 header of email alerts. This is the address that email alerts are sent to.
3489 May be used in sections: defaults | frontend | listen | backend
3490 yes | yes | yes | yes
3491
3492 Arguments :
3493
3494 <emailaddr> is the to email address to use when sending email alerts
3495
3496 Also requires "email-alert mailers" and "email-alert to" to be set
3497 and if so sending email alerts is enabled for the proxy.
3498
Simon Horman64e34162015-02-06 11:11:57 +09003499 See also : "email-alert from", "email-alert level", "email-alert mailers",
Simon Horman51a1cf62015-02-03 13:00:44 +09003500 "email-alert myhostname", section 3.6 about mailers.
3501
3502
Willy Tarreau4de91492010-01-22 19:10:05 +01003503force-persist { if | unless } <condition>
3504 Declare a condition to force persistence on down servers
3505 May be used in sections: defaults | frontend | listen | backend
3506 no | yes | yes | yes
3507
3508 By default, requests are not dispatched to down servers. It is possible to
3509 force this using "option persist", but it is unconditional and redispatches
3510 to a valid server if "option redispatch" is set. That leaves with very little
3511 possibilities to force some requests to reach a server which is artificially
3512 marked down for maintenance operations.
3513
3514 The "force-persist" statement allows one to declare various ACL-based
3515 conditions which, when met, will cause a request to ignore the down status of
3516 a server and still try to connect to it. That makes it possible to start a
3517 server, still replying an error to the health checks, and run a specially
3518 configured browser to test the service. Among the handy methods, one could
3519 use a specific source IP address, or a specific cookie. The cookie also has
3520 the advantage that it can easily be added/removed on the browser from a test
3521 page. Once the service is validated, it is then possible to open the service
3522 to the world by returning a valid response to health checks.
3523
3524 The forced persistence is enabled when an "if" condition is met, or unless an
3525 "unless" condition is met. The final redispatch is always disabled when this
3526 is used.
3527
Cyril Bonté0d4bf012010-04-25 23:21:46 +02003528 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02003529 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01003530
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003531
3532filter <name> [param*]
3533 Add the filter <name> in the filter list attached to the proxy.
3534 May be used in sections : defaults | frontend | listen | backend
3535 no | yes | yes | yes
3536 Arguments :
3537 <name> is the name of the filter. Officially supported filters are
3538 referenced in section 9.
3539
Tim Düsterhus4896c442016-11-29 02:15:19 +01003540 <param*> is a list of parameters accepted by the filter <name>. The
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003541 parsing of these parameters are the responsibility of the
Tim Düsterhus4896c442016-11-29 02:15:19 +01003542 filter. Please refer to the documentation of the corresponding
3543 filter (section 9) for all details on the supported parameters.
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003544
3545 Multiple occurrences of the filter line can be used for the same proxy. The
3546 same filter can be referenced many times if needed.
3547
3548 Example:
3549 listen
3550 bind *:80
3551
3552 filter trace name BEFORE-HTTP-COMP
3553 filter compression
3554 filter trace name AFTER-HTTP-COMP
3555
3556 compression algo gzip
3557 compression offload
3558
3559 server srv1 192.168.0.1:80
3560
3561 See also : section 9.
3562
Willy Tarreau4de91492010-01-22 19:10:05 +01003563
Willy Tarreau2769aa02007-12-27 18:26:09 +01003564fullconn <conns>
3565 Specify at what backend load the servers will reach their maxconn
3566 May be used in sections : defaults | frontend | listen | backend
3567 yes | no | yes | yes
3568 Arguments :
3569 <conns> is the number of connections on the backend which will make the
3570 servers use the maximal number of connections.
3571
Willy Tarreau198a7442008-01-17 12:05:32 +01003572 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01003573 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01003574 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01003575 load. The server will then always accept at least <minconn> connections,
3576 never more than <maxconn>, and the limit will be on the ramp between both
3577 values when the backend has less than <conns> concurrent connections. This
3578 makes it possible to limit the load on the servers during normal loads, but
3579 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003580 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003581
Willy Tarreaufbb78422011-06-05 15:38:35 +02003582 Since it's hard to get this value right, haproxy automatically sets it to
3583 10% of the sum of the maxconns of all frontends that may branch to this
Bertrand Jacquin702d44f2013-11-19 11:43:06 +01003584 backend (based on "use_backend" and "default_backend" rules). That way it's
3585 safe to leave it unset. However, "use_backend" involving dynamic names are
3586 not counted since there is no way to know if they could match or not.
Willy Tarreaufbb78422011-06-05 15:38:35 +02003587
Willy Tarreau2769aa02007-12-27 18:26:09 +01003588 Example :
3589 # The servers will accept between 100 and 1000 concurrent connections each
3590 # and the maximum of 1000 will be reached when the backend reaches 10000
3591 # connections.
3592 backend dynamic
3593 fullconn 10000
3594 server srv1 dyn1:80 minconn 100 maxconn 1000
3595 server srv2 dyn2:80 minconn 100 maxconn 1000
3596
3597 See also : "maxconn", "server"
3598
3599
3600grace <time>
3601 Maintain a proxy operational for some time after a soft stop
3602 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01003603 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01003604 Arguments :
3605 <time> is the time (by default in milliseconds) for which the instance
3606 will remain operational with the frontend sockets still listening
3607 when a soft-stop is received via the SIGUSR1 signal.
3608
3609 This may be used to ensure that the services disappear in a certain order.
3610 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003611 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01003612 needed by the equipment to detect the failure.
3613
3614 Note that currently, there is very little benefit in using this parameter,
3615 and it may in fact complicate the soft-reconfiguration process more than
3616 simplify it.
3617
Willy Tarreau0ba27502007-12-24 16:55:16 +01003618
Andrew Rodland17be45e2016-10-25 17:04:12 -04003619hash-balance-factor <factor>
3620 Specify the balancing factor for bounded-load consistent hashing
3621 May be used in sections : defaults | frontend | listen | backend
3622 yes | no | no | yes
3623 Arguments :
3624 <factor> is the control for the maximum number of concurrent requests to
3625 send to a server, expressed as a percentage of the average number
3626 of concurrent requests across all of the active servers.
3627
3628 Specifying a "hash-balance-factor" for a server with "hash-type consistent"
3629 enables an algorithm that prevents any one server from getting too many
3630 requests at once, even if some hash buckets receive many more requests than
3631 others. Setting <factor> to 0 (the default) disables the feature. Otherwise,
3632 <factor> is a percentage greater than 100. For example, if <factor> is 150,
3633 then no server will be allowed to have a load more than 1.5 times the average.
3634 If server weights are used, they will be respected.
3635
3636 If the first-choice server is disqualified, the algorithm will choose another
3637 server based on the request hash, until a server with additional capacity is
3638 found. A higher <factor> allows more imbalance between the servers, while a
3639 lower <factor> means that more servers will be checked on average, affecting
3640 performance. Reasonable values are from 125 to 200.
3641
3642 See also : "balance" and "hash-type".
3643
3644
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003645hash-type <method> <function> <modifier>
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003646 Specify a method to use for mapping hashes to servers
3647 May be used in sections : defaults | frontend | listen | backend
3648 yes | no | yes | yes
3649 Arguments :
Bhaskar98634f02013-10-29 23:30:51 -04003650 <method> is the method used to select a server from the hash computed by
3651 the <function> :
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003652
Bhaskar98634f02013-10-29 23:30:51 -04003653 map-based the hash table is a static array containing all alive servers.
3654 The hashes will be very smooth, will consider weights, but
3655 will be static in that weight changes while a server is up
3656 will be ignored. This means that there will be no slow start.
3657 Also, since a server is selected by its position in the array,
3658 most mappings are changed when the server count changes. This
3659 means that when a server goes up or down, or when a server is
3660 added to a farm, most connections will be redistributed to
3661 different servers. This can be inconvenient with caches for
3662 instance.
Willy Tarreau798a39c2010-11-24 15:04:29 +01003663
Bhaskar98634f02013-10-29 23:30:51 -04003664 consistent the hash table is a tree filled with many occurrences of each
3665 server. The hash key is looked up in the tree and the closest
3666 server is chosen. This hash is dynamic, it supports changing
3667 weights while the servers are up, so it is compatible with the
3668 slow start feature. It has the advantage that when a server
3669 goes up or down, only its associations are moved. When a
3670 server is added to the farm, only a few part of the mappings
3671 are redistributed, making it an ideal method for caches.
3672 However, due to its principle, the distribution will never be
3673 very smooth and it may sometimes be necessary to adjust a
3674 server's weight or its ID to get a more balanced distribution.
3675 In order to get the same distribution on multiple load
3676 balancers, it is important that all servers have the exact
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003677 same IDs. Note: consistent hash uses sdbm and avalanche if no
3678 hash function is specified.
Bhaskar98634f02013-10-29 23:30:51 -04003679
3680 <function> is the hash function to be used :
3681
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03003682 sdbm this function was created initially for sdbm (a public-domain
Bhaskar98634f02013-10-29 23:30:51 -04003683 reimplementation of ndbm) database library. It was found to do
3684 well in scrambling bits, causing better distribution of the keys
3685 and fewer splits. It also happens to be a good general hashing
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003686 function with good distribution, unless the total server weight
3687 is a multiple of 64, in which case applying the avalanche
3688 modifier may help.
Bhaskar98634f02013-10-29 23:30:51 -04003689
3690 djb2 this function was first proposed by Dan Bernstein many years ago
3691 on comp.lang.c. Studies have shown that for certain workload this
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003692 function provides a better distribution than sdbm. It generally
3693 works well with text-based inputs though it can perform extremely
3694 poorly with numeric-only input or when the total server weight is
3695 a multiple of 33, unless the avalanche modifier is also used.
3696
Willy Tarreaua0f42712013-11-14 14:30:35 +01003697 wt6 this function was designed for haproxy while testing other
3698 functions in the past. It is not as smooth as the other ones, but
3699 is much less sensible to the input data set or to the number of
3700 servers. It can make sense as an alternative to sdbm+avalanche or
3701 djb2+avalanche for consistent hashing or when hashing on numeric
3702 data such as a source IP address or a visitor identifier in a URL
3703 parameter.
3704
Willy Tarreau324f07f2015-01-20 19:44:50 +01003705 crc32 this is the most common CRC32 implementation as used in Ethernet,
3706 gzip, PNG, etc. It is slower than the other ones but may provide
3707 a better distribution or less predictable results especially when
3708 used on strings.
3709
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003710 <modifier> indicates an optional method applied after hashing the key :
3711
3712 avalanche This directive indicates that the result from the hash
3713 function above should not be used in its raw form but that
3714 a 4-byte full avalanche hash must be applied first. The
3715 purpose of this step is to mix the resulting bits from the
3716 previous hash in order to avoid any undesired effect when
3717 the input contains some limited values or when the number of
3718 servers is a multiple of one of the hash's components (64
3719 for SDBM, 33 for DJB2). Enabling avalanche tends to make the
3720 result less predictable, but it's also not as smooth as when
3721 using the original function. Some testing might be needed
3722 with some workloads. This hash is one of the many proposed
3723 by Bob Jenkins.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003724
Bhaskar98634f02013-10-29 23:30:51 -04003725 The default hash type is "map-based" and is recommended for most usages. The
3726 default function is "sdbm", the selection of a function should be based on
3727 the range of the values being hashed.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003728
Andrew Rodland17be45e2016-10-25 17:04:12 -04003729 See also : "balance", "hash-balance-factor", "server"
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003730
3731
Willy Tarreau0ba27502007-12-24 16:55:16 +01003732http-check disable-on-404
3733 Enable a maintenance mode upon HTTP/404 response to health-checks
3734 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01003735 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01003736 Arguments : none
3737
3738 When this option is set, a server which returns an HTTP code 404 will be
3739 excluded from further load-balancing, but will still receive persistent
3740 connections. This provides a very convenient method for Web administrators
3741 to perform a graceful shutdown of their servers. It is also important to note
3742 that a server which is detected as failed while it was in this mode will not
3743 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
3744 will immediately be reinserted into the farm. The status on the stats page
3745 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01003746 option only works in conjunction with the "httpchk" option. If this option
3747 is used with "http-check expect", then it has precedence over it so that 404
3748 responses will still be considered as soft-stop.
3749
3750 See also : "option httpchk", "http-check expect"
3751
3752
3753http-check expect [!] <match> <pattern>
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003754 Make HTTP health checks consider response contents or specific status codes
Willy Tarreaubd741542010-03-16 18:46:54 +01003755 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau1ee51a62011-08-19 20:04:17 +02003756 yes | no | yes | yes
Willy Tarreaubd741542010-03-16 18:46:54 +01003757 Arguments :
3758 <match> is a keyword indicating how to look for a specific pattern in the
3759 response. The keyword may be one of "status", "rstatus",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003760 "string", or "rstring". The keyword may be preceded by an
Willy Tarreaubd741542010-03-16 18:46:54 +01003761 exclamation mark ("!") to negate the match. Spaces are allowed
3762 between the exclamation mark and the keyword. See below for more
3763 details on the supported keywords.
3764
3765 <pattern> is the pattern to look for. It may be a string or a regular
3766 expression. If the pattern contains spaces, they must be escaped
3767 with the usual backslash ('\').
3768
3769 By default, "option httpchk" considers that response statuses 2xx and 3xx
3770 are valid, and that others are invalid. When "http-check expect" is used,
3771 it defines what is considered valid or invalid. Only one "http-check"
3772 statement is supported in a backend. If a server fails to respond or times
3773 out, the check obviously fails. The available matches are :
3774
3775 status <string> : test the exact string match for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003776 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01003777 response's status code is exactly this string. If the
3778 "status" keyword is prefixed with "!", then the response
3779 will be considered invalid if the status code matches.
3780
3781 rstatus <regex> : test a regular expression for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003782 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01003783 response's status code matches the expression. If the
3784 "rstatus" keyword is prefixed with "!", then the response
3785 will be considered invalid if the status code matches.
3786 This is mostly used to check for multiple codes.
3787
3788 string <string> : test the exact string match in the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003789 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01003790 response's body contains this exact string. If the
3791 "string" keyword is prefixed with "!", then the response
3792 will be considered invalid if the body contains this
3793 string. This can be used to look for a mandatory word at
3794 the end of a dynamic page, or to detect a failure when a
3795 specific error appears on the check page (eg: a stack
3796 trace).
3797
3798 rstring <regex> : test a regular expression on the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003799 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01003800 response's body matches this expression. If the "rstring"
3801 keyword is prefixed with "!", then the response will be
3802 considered invalid if the body matches the expression.
3803 This can be used to look for a mandatory word at the end
3804 of a dynamic page, or to detect a failure when a specific
3805 error appears on the check page (eg: a stack trace).
3806
3807 It is important to note that the responses will be limited to a certain size
3808 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
3809 Thus, too large responses may not contain the mandatory pattern when using
3810 "string" or "rstring". If a large response is absolutely required, it is
3811 possible to change the default max size by setting the global variable.
3812 However, it is worth keeping in mind that parsing very large responses can
3813 waste some CPU cycles, especially when regular expressions are used, and that
3814 it is always better to focus the checks on smaller resources.
3815
Cyril Bonté32602d22015-01-30 00:07:07 +01003816 Also "http-check expect" doesn't support HTTP keep-alive. Keep in mind that it
3817 will automatically append a "Connection: close" header, meaning that this
3818 header should not be present in the request provided by "option httpchk".
3819
Willy Tarreaubd741542010-03-16 18:46:54 +01003820 Last, if "http-check expect" is combined with "http-check disable-on-404",
3821 then this last one has precedence when the server responds with 404.
3822
3823 Examples :
3824 # only accept status 200 as valid
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01003825 http-check expect status 200
Willy Tarreaubd741542010-03-16 18:46:54 +01003826
3827 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01003828 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01003829
3830 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01003831 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01003832
3833 # check that we have a correct hexadecimal tag before /html
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03003834 http-check expect rstring <!--tag:[0-9a-f]*--></html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01003835
Willy Tarreaubd741542010-03-16 18:46:54 +01003836 See also : "option httpchk", "http-check disable-on-404"
Willy Tarreau2769aa02007-12-27 18:26:09 +01003837
3838
Willy Tarreauef781042010-01-27 11:53:01 +01003839http-check send-state
3840 Enable emission of a state header with HTTP health checks
3841 May be used in sections : defaults | frontend | listen | backend
3842 yes | no | yes | yes
3843 Arguments : none
3844
3845 When this option is set, haproxy will systematically send a special header
3846 "X-Haproxy-Server-State" with a list of parameters indicating to each server
3847 how they are seen by haproxy. This can be used for instance when a server is
3848 manipulated without access to haproxy and the operator needs to know whether
3849 haproxy still sees it up or not, or if the server is the last one in a farm.
3850
3851 The header is composed of fields delimited by semi-colons, the first of which
3852 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
3853 checks on the total number before transition, just as appears in the stats
3854 interface. Next headers are in the form "<variable>=<value>", indicating in
3855 no specific order some values available in the stats interface :
Joseph Lynch514061c2015-01-15 17:52:59 -08003856 - a variable "address", containing the address of the backend server.
3857 This corresponds to the <address> field in the server declaration. For
3858 unix domain sockets, it will read "unix".
3859
3860 - a variable "port", containing the port of the backend server. This
3861 corresponds to the <port> field in the server declaration. For unix
3862 domain sockets, it will read "unix".
3863
Willy Tarreauef781042010-01-27 11:53:01 +01003864 - a variable "name", containing the name of the backend followed by a slash
3865 ("/") then the name of the server. This can be used when a server is
3866 checked in multiple backends.
3867
3868 - a variable "node" containing the name of the haproxy node, as set in the
3869 global "node" variable, otherwise the system's hostname if unspecified.
3870
3871 - a variable "weight" indicating the weight of the server, a slash ("/")
3872 and the total weight of the farm (just counting usable servers). This
3873 helps to know if other servers are available to handle the load when this
3874 one fails.
3875
3876 - a variable "scur" indicating the current number of concurrent connections
3877 on the server, followed by a slash ("/") then the total number of
3878 connections on all servers of the same backend.
3879
3880 - a variable "qcur" indicating the current number of requests in the
3881 server's queue.
3882
3883 Example of a header received by the application server :
3884 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
3885 scur=13/22; qcur=0
3886
3887 See also : "option httpchk", "http-check disable-on-404"
3888
Willy Tarreau53275e82017-11-24 07:52:01 +01003889http-request { allow | auth [realm <realm>] | redirect <rule> | reject |
Jarno Huuskonen800d1762017-03-06 14:56:36 +02003890 tarpit [deny_status <status>] | deny [deny_status <status>] |
Willy Tarreauf4c43c12013-06-11 17:01:13 +02003891 add-header <name> <fmt> | set-header <name> <fmt> |
Thierry FOURNIER82bf70d2015-05-26 17:58:29 +02003892 capture <sample> [ len <length> | id <id> ] |
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02003893 del-header <name> | set-nice <nice> | set-log-level <level> |
Sasha Pachev218f0642014-06-16 12:05:59 -06003894 replace-header <name> <match-regex> <replace-fmt> |
3895 replace-value <name> <match-regex> <replace-fmt> |
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01003896 set-method <fmt> | set-path <fmt> | set-query <fmt> |
3897 set-uri <fmt> | set-tos <tos> | set-mark <mark> |
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02003898 add-acl(<file name>) <key fmt> |
3899 del-acl(<file name>) <key fmt> |
3900 del-map(<file name>) <key fmt> |
Baptiste Assmannbb7e86a2014-09-03 18:29:47 +02003901 set-map(<file name>) <key fmt> <value fmt> |
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02003902 set-var(<var name>) <expr> |
Christopher Faulet85d79c92016-11-09 16:54:56 +01003903 unset-var(<var name>) |
Thierry FOURNIER90da1912015-03-05 11:17:06 +01003904 { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] |
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02003905 sc-inc-gpc0(<sc-id>) |
Thierry FOURNIER236657b2015-08-19 08:25:14 +02003906 sc-set-gpt0(<sc-id>) <int> |
Willy Tarreau2d392c22015-08-24 01:43:45 +02003907 silent-drop |
William Lallemand86d0df02017-11-24 21:36:45 +01003908 send-spoe-group |
3909 cache-use
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02003910 }
Cyril Bontéf0c60612010-02-06 14:44:47 +01003911 [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01003912 Access control for Layer 7 requests
3913
3914 May be used in sections: defaults | frontend | listen | backend
3915 no | yes | yes | yes
3916
Willy Tarreau20b0de52012-12-24 15:45:22 +01003917 The http-request statement defines a set of rules which apply to layer 7
3918 processing. The rules are evaluated in their declaration order when they are
3919 met in a frontend, listen or backend section. Any rule may optionally be
3920 followed by an ACL-based condition, in which case it will only be evaluated
3921 if the condition is true.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01003922
Willy Tarreau20b0de52012-12-24 15:45:22 +01003923 The first keyword is the rule's action. Currently supported actions include :
3924 - "allow" : this stops the evaluation of the rules and lets the request
3925 pass the check. No further "http-request" rules are evaluated.
3926
3927 - "deny" : this stops the evaluation of the rules and immediately rejects
Willy Tarreaube1d34d2016-06-26 19:37:59 +02003928 the request and emits an HTTP 403 error, or optionally the status code
3929 specified as an argument to "deny_status". The list of permitted status
3930 codes is limited to those that can be overridden by the "errorfile"
3931 directive. No further "http-request" rules are evaluated.
Willy Tarreau20b0de52012-12-24 15:45:22 +01003932
Willy Tarreau53275e82017-11-24 07:52:01 +01003933 - "reject" : this stops the evaluation of the rules and immediately closes
3934 the connection without sending any response. It acts similarly to the
3935 "tcp-request content reject" rules. It can be useful to force an
3936 immediate connection closure on HTTP/2 connections.
3937
Willy Tarreauccbcc372012-12-27 12:37:57 +01003938 - "tarpit" : this stops the evaluation of the rules and immediately blocks
3939 the request without responding for a delay specified by "timeout tarpit"
3940 or "timeout connect" if the former is not set. After that delay, if the
Jarno Huuskonen800d1762017-03-06 14:56:36 +02003941 client is still connected, an HTTP error 500 (or optionally the status
3942 code specified as an argument to "deny_status") is returned so that the
Willy Tarreauccbcc372012-12-27 12:37:57 +01003943 client does not suspect it has been tarpitted. Logs will report the flags
3944 "PT". The goal of the tarpit rule is to slow down robots during an attack
3945 when they're limited on the number of concurrent requests. It can be very
3946 efficient against very dumb robots, and will significantly reduce the
3947 load on firewalls compared to a "deny" rule. But when facing "correctly"
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03003948 developed robots, it can make things worse by forcing haproxy and the
Willy Tarreau2d392c22015-08-24 01:43:45 +02003949 front firewall to support insane number of concurrent connections. See
3950 also the "silent-drop" action below.
Willy Tarreauccbcc372012-12-27 12:37:57 +01003951
Willy Tarreau20b0de52012-12-24 15:45:22 +01003952 - "auth" : this stops the evaluation of the rules and immediately responds
3953 with an HTTP 401 or 407 error code to invite the user to present a valid
3954 user name and password. No further "http-request" rules are evaluated. An
3955 optional "realm" parameter is supported, it sets the authentication realm
3956 that is returned with the response (typically the application's name).
3957
Willy Tarreau81499eb2012-12-27 12:19:02 +01003958 - "redirect" : this performs an HTTP redirection based on a redirect rule.
3959 This is exactly the same as the "redirect" statement except that it
3960 inserts a redirect rule which can be processed in the middle of other
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01003961 "http-request" rules and that these rules use the "log-format" strings.
3962 See the "redirect" keyword for the rule's syntax.
Willy Tarreau81499eb2012-12-27 12:19:02 +01003963
Willy Tarreau20b0de52012-12-24 15:45:22 +01003964 - "add-header" appends an HTTP header field whose name is specified in
3965 <name> and whose value is defined by <fmt> which follows the log-format
3966 rules (see Custom Log Format in section 8.2.4). This is particularly
3967 useful to pass connection-specific information to the server (eg: the
3968 client's SSL certificate), or to combine several headers into one. This
3969 rule is not final, so it is possible to add other similar rules. Note
3970 that header addition is performed immediately, so one rule might reuse
3971 the resulting header from a previous rule.
3972
3973 - "set-header" does the same as "add-header" except that the header name
3974 is first removed if it existed. This is useful when passing security
3975 information to the server, where the header must not be manipulated by
Willy Tarreau85603282015-01-21 20:39:27 +01003976 external users. Note that the new value is computed before the removal so
3977 it is possible to concatenate a value to an existing header.
Willy Tarreau20b0de52012-12-24 15:45:22 +01003978
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02003979 - "del-header" removes all HTTP header fields whose name is specified in
3980 <name>.
3981
Sasha Pachev218f0642014-06-16 12:05:59 -06003982 - "replace-header" matches the regular expression in all occurrences of
3983 header field <name> according to <match-regex>, and replaces them with
3984 the <replace-fmt> argument. Format characters are allowed in replace-fmt
3985 and work like in <fmt> arguments in "add-header". The match is only
3986 case-sensitive. It is important to understand that this action only
3987 considers whole header lines, regardless of the number of values they
3988 may contain. This usage is suited to headers naturally containing commas
3989 in their value, such as If-Modified-Since and so on.
3990
3991 Example:
3992
3993 http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2
3994
3995 applied to:
3996
3997 Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT;
3998
3999 outputs:
4000
4001 Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT;
4002
4003 assuming the backend IP is 192.168.1.20
4004
4005 - "replace-value" works like "replace-header" except that it matches the
4006 regex against every comma-delimited value of the header field <name>
4007 instead of the entire header. This is suited for all headers which are
4008 allowed to carry more than one value. An example could be the Accept
4009 header.
4010
4011 Example:
4012
4013 http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1
4014
4015 applied to:
4016
4017 X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37
4018
4019 outputs:
4020
4021 X-Forwarded-For: 172.16.10.1, 172.16.13.24, 10.0.0.37
4022
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004023 - "set-method" rewrites the request method with the result of the
4024 evaluation of format string <fmt>. There should be very few valid reasons
4025 for having to do so as this is more likely to break something than to fix
4026 it.
4027
4028 - "set-path" rewrites the request path with the result of the evaluation of
4029 format string <fmt>. The query string, if any, is left intact. If a
4030 scheme and authority is found before the path, they are left intact as
4031 well. If the request doesn't have a path ("*"), this one is replaced with
4032 the format. This can be used to prepend a directory component in front of
4033 a path for example. See also "set-query" and "set-uri".
4034
4035 Example :
4036 # prepend the host name before the path
4037 http-request set-path /%[hdr(host)]%[path]
4038
4039 - "set-query" rewrites the request's query string which appears after the
4040 first question mark ("?") with the result of the evaluation of format
4041 string <fmt>. The part prior to the question mark is left intact. If the
4042 request doesn't contain a question mark and the new value is not empty,
4043 then one is added at the end of the URI, followed by the new value. If
4044 a question mark was present, it will never be removed even if the value
4045 is empty. This can be used to add or remove parameters from the query
4046 string. See also "set-query" and "set-uri".
4047
4048 Example :
4049 # replace "%3D" with "=" in the query string
4050 http-request set-query %[query,regsub(%3D,=,g)]
4051
4052 - "set-uri" rewrites the request URI with the result of the evaluation of
4053 format string <fmt>. The scheme, authority, path and query string are all
4054 replaced at once. This can be used to rewrite hosts in front of proxies,
4055 or to perform complex modifications to the URI such as moving parts
4056 between the path and the query string. See also "set-path" and
4057 "set-query".
4058
Willy Tarreauf4c43c12013-06-11 17:01:13 +02004059 - "set-nice" sets the "nice" factor of the current request being processed.
4060 It only has effect against the other requests being processed at the same
4061 time. The default value is 0, unless altered by the "nice" setting on the
4062 "bind" line. The accepted range is -1024..1024. The higher the value, the
4063 nicest the request will be. Lower values will make the request more
4064 important than other ones. This can be useful to improve the speed of
4065 some requests, or lower the priority of non-important requests. Using
4066 this setting without prior experimentation can cause some major slowdown.
4067
Willy Tarreau9a355ec2013-06-11 17:45:46 +02004068 - "set-log-level" is used to change the log level of the current request
4069 when a certain condition is met. Valid levels are the 8 syslog levels
4070 (see the "log" keyword) plus the special level "silent" which disables
4071 logging for this request. This rule is not final so the last matching
4072 rule wins. This rule can be useful to disable health checks coming from
4073 another equipment.
4074
Willy Tarreau42cf39e2013-06-11 18:51:32 +02004075 - "set-tos" is used to set the TOS or DSCP field value of packets sent to
4076 the client to the value passed in <tos> on platforms which support this.
4077 This value represents the whole 8 bits of the IP TOS field, and can be
4078 expressed both in decimal or hexadecimal format (prefixed by "0x"). Note
4079 that only the 6 higher bits are used in DSCP or TOS, and the two lower
4080 bits are always 0. This can be used to adjust some routing behaviour on
4081 border routers based on some information from the request. See RFC 2474,
4082 2597, 3260 and 4594 for more information.
4083
Willy Tarreau51347ed2013-06-11 19:34:13 +02004084 - "set-mark" is used to set the Netfilter MARK on all packets sent to the
4085 client to the value passed in <mark> on platforms which support it. This
4086 value is an unsigned 32 bit value which can be matched by netfilter and
4087 by the routing table. It can be expressed both in decimal or hexadecimal
4088 format (prefixed by "0x"). This can be useful to force certain packets to
4089 take a different route (for example a cheaper network path for bulk
4090 downloads). This works on Linux kernels 2.6.32 and above and requires
4091 admin privileges.
4092
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004093 - "add-acl" is used to add a new entry into an ACL. The ACL must be loaded
4094 from a file (even a dummy empty file). The file name of the ACL to be
4095 updated is passed between parentheses. It takes one argument: <key fmt>,
4096 which follows log-format rules, to collect content of the new entry. It
4097 performs a lookup in the ACL before insertion, to avoid duplicated (or
4098 more) values. This lookup is done by a linear search and can be expensive
4099 with large lists! It is the equivalent of the "add acl" command from the
4100 stats socket, but can be triggered by an HTTP request.
4101
4102 - "del-acl" is used to delete an entry from an ACL. The ACL must be loaded
4103 from a file (even a dummy empty file). The file name of the ACL to be
4104 updated is passed between parentheses. It takes one argument: <key fmt>,
4105 which follows log-format rules, to collect content of the entry to delete.
4106 It is the equivalent of the "del acl" command from the stats socket, but
4107 can be triggered by an HTTP request.
4108
4109 - "del-map" is used to delete an entry from a MAP. The MAP must be loaded
4110 from a file (even a dummy empty file). The file name of the MAP to be
4111 updated is passed between parentheses. It takes one argument: <key fmt>,
4112 which follows log-format rules, to collect content of the entry to delete.
4113 It takes one argument: "file name" It is the equivalent of the "del map"
4114 command from the stats socket, but can be triggered by an HTTP request.
4115
4116 - "set-map" is used to add a new entry into a MAP. The MAP must be loaded
4117 from a file (even a dummy empty file). The file name of the MAP to be
4118 updated is passed between parentheses. It takes 2 arguments: <key fmt>,
4119 which follows log-format rules, used to collect MAP key, and <value fmt>,
4120 which follows log-format rules, used to collect content for the new entry.
4121 It performs a lookup in the MAP before insertion, to avoid duplicated (or
4122 more) values. This lookup is done by a linear search and can be expensive
4123 with large lists! It is the equivalent of the "set map" command from the
4124 stats socket, but can be triggered by an HTTP request.
4125
Thierry FOURNIER82bf70d2015-05-26 17:58:29 +02004126 - capture <sample> [ len <length> | id <id> ] :
Willy Tarreaua9083d02015-05-08 15:27:59 +02004127 captures sample expression <sample> from the request buffer, and converts
4128 it to a string of at most <len> characters. The resulting string is
4129 stored into the next request "capture" slot, so it will possibly appear
4130 next to some captured HTTP headers. It will then automatically appear in
4131 the logs, and it will be possible to extract it using sample fetch rules
4132 to feed it into headers or anything. The length should be limited given
4133 that this size will be allocated for each capture during the whole
4134 session life. Please check section 7.3 (Fetching samples) and "capture
4135 request header" for more information.
4136
Thierry FOURNIER82bf70d2015-05-26 17:58:29 +02004137 If the keyword "id" is used instead of "len", the action tries to store
4138 the captured string in a previously declared capture slot. This is useful
4139 to run captures in backends. The slot id can be declared by a previous
4140 directive "http-request capture" or with the "declare capture" keyword.
Baptiste Assmanne9544932015-11-03 23:31:35 +01004141 If the slot <id> doesn't exist, then HAProxy fails parsing the
4142 configuration to prevent unexpected behavior at run time.
Thierry FOURNIER82bf70d2015-05-26 17:58:29 +02004143
William Lallemand86d0df02017-11-24 21:36:45 +01004144 - cache-use <name> :
4145 See section 10.2 about cache setup.
4146
Willy Tarreau09448f72014-06-25 18:12:15 +02004147 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] :
4148 enables tracking of sticky counters from current request. These rules
4149 do not stop evaluation and do not change default action. Three sets of
4150 counters may be simultaneously tracked by the same connection. The first
4151 "track-sc0" rule executed enables tracking of the counters of the
4152 specified table as the first set. The first "track-sc1" rule executed
4153 enables tracking of the counters of the specified table as the second
4154 set. The first "track-sc2" rule executed enables tracking of the
4155 counters of the specified table as the third set. It is a recommended
4156 practice to use the first set of counters for the per-frontend counters
4157 and the second set for the per-backend ones. But this is just a
4158 guideline, all may be used everywhere.
4159
4160 These actions take one or two arguments :
4161 <key> is mandatory, and is a sample expression rule as described
4162 in section 7.3. It describes what elements of the incoming
4163 request or connection will be analysed, extracted, combined,
4164 and used to select which table entry to update the counters.
4165
4166 <table> is an optional table to be used instead of the default one,
4167 which is the stick-table declared in the current proxy. All
4168 the counters for the matches and updates for the key will
4169 then be performed in that table until the session ends.
4170
4171 Once a "track-sc*" rule is executed, the key is looked up in the table
4172 and if it is not found, an entry is allocated for it. Then a pointer to
4173 that entry is kept during all the session's life, and this entry's
4174 counters are updated as often as possible, every time the session's
4175 counters are updated, and also systematically when the session ends.
4176 Counters are only updated for events that happen after the tracking has
4177 been started. As an exception, connection counters and request counters
4178 are systematically updated so that they reflect useful information.
4179
4180 If the entry tracks concurrent connection counters, one connection is
4181 counted for as long as the entry is tracked, and the entry will not
4182 expire during that time. Tracking counters also provides a performance
4183 advantage over just checking the keys, because only one table lookup is
4184 performed for all ACL checks that make use of it.
4185
Thierry FOURNIER236657b2015-08-19 08:25:14 +02004186 - sc-set-gpt0(<sc-id>) <int> :
4187 This action sets the GPT0 tag according to the sticky counter designated
4188 by <sc-id> and the value of <int>. The expected result is a boolean. If
4189 an error occurs, this action silently fails and the actions evaluation
4190 continues.
4191
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02004192 - sc-inc-gpc0(<sc-id>):
4193 This action increments the GPC0 counter according with the sticky counter
4194 designated by <sc-id>. If an error occurs, this action silently fails and
4195 the actions evaluation continues.
4196
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004197 - set-var(<var-name>) <expr> :
4198 Is used to set the contents of a variable. The variable is declared
4199 inline.
4200
Daniel Schneller0b547052016-03-21 20:46:57 +01004201 <var-name> The name of the variable starts with an indication about
4202 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +01004203 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +01004204 "sess" : the variable is shared with the whole session
4205 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004206 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +01004207 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004208 processing
Daniel Schneller0b547052016-03-21 20:46:57 +01004209 "res" : the variable is shared only during response
4210 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004211 This prefix is followed by a name. The separator is a '.'.
Daniel Schneller0b547052016-03-21 20:46:57 +01004212 The name may only contain characters 'a-z', 'A-Z', '0-9'
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004213 and '_'.
4214
4215 <expr> Is a standard HAProxy expression formed by a sample-fetch
4216 followed by some converters.
4217
4218 Example:
4219
4220 http-request set-var(req.my_var) req.fhdr(user-agent),lower
4221
Christopher Faulet85d79c92016-11-09 16:54:56 +01004222 - unset-var(<var-name>) :
4223 Is used to unset a variable. See above for details about <var-name>.
4224
4225 Example:
4226
4227 http-request unset-var(req.my_var)
4228
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004229 - set-src <expr> :
4230 Is used to set the source IP address to the value of specified
4231 expression. Useful when a proxy in front of HAProxy rewrites source IP,
4232 but provides the correct IP in a HTTP header; or you want to mask
4233 source IP for privacy.
4234
4235 <expr> Is a standard HAProxy expression formed by a sample-fetch
4236 followed by some converters.
4237
4238 Example:
4239
4240 http-request set-src hdr(x-forwarded-for)
4241 http-request set-src src,ipmask(24)
4242
Willy Tarreau00005ce2016-10-21 15:07:45 +02004243 When possible, set-src preserves the original source port as long as the
4244 address family allows it, otherwise the source port is set to 0.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004245
William Lallemand44be6402016-05-25 01:51:35 +02004246 - set-src-port <expr> :
4247 Is used to set the source port address to the value of specified
4248 expression.
4249
4250 <expr> Is a standard HAProxy expression formed by a sample-fetch
4251 followed by some converters.
4252
4253 Example:
4254
4255 http-request set-src-port hdr(x-port)
4256 http-request set-src-port int(4000)
4257
Willy Tarreau00005ce2016-10-21 15:07:45 +02004258 When possible, set-src-port preserves the original source address as long
4259 as the address family supports a port, otherwise it forces the source
4260 address to IPv4 "0.0.0.0" before rewriting the port.
William Lallemand44be6402016-05-25 01:51:35 +02004261
William Lallemand13e9b0c2016-05-25 02:34:07 +02004262 - set-dst <expr> :
4263 Is used to set the destination IP address to the value of specified
4264 expression. Useful when a proxy in front of HAProxy rewrites destination
4265 IP, but provides the correct IP in a HTTP header; or you want to mask
4266 the IP for privacy. If you want to connect to the new address/port, use
4267 '0.0.0.0:0' as a server address in the backend.
4268
4269 <expr> Is a standard HAProxy expression formed by a sample-fetch
4270 followed by some converters.
4271
4272 Example:
4273
4274 http-request set-dst hdr(x-dst)
4275 http-request set-dst dst,ipmask(24)
4276
Willy Tarreau00005ce2016-10-21 15:07:45 +02004277 When possible, set-dst preserves the original destination port as long as
4278 the address family allows it, otherwise the destination port is set to 0.
4279
William Lallemand13e9b0c2016-05-25 02:34:07 +02004280 - set-dst-port <expr> :
4281 Is used to set the destination port address to the value of specified
4282 expression. If you want to connect to the new address/port, use
4283 '0.0.0.0:0' as a server address in the backend.
4284
4285 <expr> Is a standard HAProxy expression formed by a sample-fetch
4286 followed by some converters.
4287
4288 Example:
4289
4290 http-request set-dst-port hdr(x-port)
4291 http-request set-dst-port int(4000)
4292
Willy Tarreau00005ce2016-10-21 15:07:45 +02004293 When possible, set-dst-port preserves the original destination address as
4294 long as the address family supports a port, otherwise it forces the
4295 destination address to IPv4 "0.0.0.0" before rewriting the port.
4296
Willy Tarreau2d392c22015-08-24 01:43:45 +02004297 - "silent-drop" : this stops the evaluation of the rules and makes the
4298 client-facing connection suddenly disappear using a system-dependant way
4299 that tries to prevent the client from being notified. The effect it then
4300 that the client still sees an established connection while there's none
4301 on HAProxy. The purpose is to achieve a comparable effect to "tarpit"
4302 except that it doesn't use any local resource at all on the machine
4303 running HAProxy. It can resist much higher loads than "tarpit", and slow
4304 down stronger attackers. It is important to undestand the impact of using
4305 this mechanism. All stateful equipments placed between the client and
4306 HAProxy (firewalls, proxies, load balancers) will also keep the
4307 established connection for a long time and may suffer from this action.
4308 On modern Linux systems running with enough privileges, the TCP_REPAIR
4309 socket option is used to block the emission of a TCP reset. On other
4310 systems, the socket's TTL is reduced to 1 so that the TCP reset doesn't
4311 pass the first router, though it's still delivered to local networks. Do
4312 not use it unless you fully understand how it works.
4313
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004314
Olivier Houchardccaa7de2017-10-02 11:51:03 +02004315 - "wait-for-handshake" : this will delay the processing of the request
4316 until the SSL handshake happened. This is mostly useful to delay
4317 processing early data until we're sure they are valid.
4318
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004319 - send-spoe-group <engine-name> <group-name> :
4320 This action is used to trigger sending of a group of SPOE messages. To do
4321 so, the SPOE engine used to send messages must be defined, as well as the
4322 SPOE group to send. Of course, the SPOE engine must refer to an existing
4323 SPOE filter. If not engine name is provided on the SPOE filter line, the
4324 SPOE agent name must be used.
4325
4326 <engine-name> The SPOE engine name.
4327
4328 <group-name> The SPOE group name as specified in the engine
4329 configuration.
4330
Willy Tarreau20b0de52012-12-24 15:45:22 +01004331 There is no limit to the number of http-request statements per instance.
4332
4333 It is important to know that http-request rules are processed very early in
4334 the HTTP processing, just after "block" rules and before "reqdel" or "reqrep"
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08004335 or "reqadd" rules. That way, headers added by "add-header"/"set-header" are
4336 visible by almost all further ACL rules.
4337
4338 Using "reqadd"/"reqdel"/"reqrep" to manipulate request headers is discouraged
4339 in newer versions (>= 1.5). But if you need to use regular expression to
4340 delete headers, you can still use "reqdel". Also please use
4341 "http-request deny/allow/tarpit" instead of "reqdeny"/"reqpass"/"reqtarpit".
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004342
4343 Example:
Cyril Bonté78caf842010-03-10 22:41:43 +01004344 acl nagios src 192.168.129.3
4345 acl local_net src 192.168.0.0/16
4346 acl auth_ok http_auth(L1)
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004347
Cyril Bonté78caf842010-03-10 22:41:43 +01004348 http-request allow if nagios
4349 http-request allow if local_net auth_ok
4350 http-request auth realm Gimme if local_net auth_ok
4351 http-request deny
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004352
Cyril Bonté78caf842010-03-10 22:41:43 +01004353 Example:
4354 acl auth_ok http_auth_group(L1) G1
Cyril Bonté78caf842010-03-10 22:41:43 +01004355 http-request auth unless auth_ok
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004356
Willy Tarreau20b0de52012-12-24 15:45:22 +01004357 Example:
4358 http-request set-header X-Haproxy-Current-Date %T
4359 http-request set-header X-SSL %[ssl_fc]
Willy Tarreaufca42612015-08-27 17:15:05 +02004360 http-request set-header X-SSL-Session_ID %[ssl_fc_session_id,hex]
Willy Tarreau20b0de52012-12-24 15:45:22 +01004361 http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
4362 http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
4363 http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
4364 http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
4365 http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
4366 http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
4367
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004368 Example:
4369 acl key req.hdr(X-Add-Acl-Key) -m found
4370 acl add path /addacl
4371 acl del path /delacl
4372
4373 acl myhost hdr(Host) -f myhost.lst
4374
4375 http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add
4376 http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del
4377
4378 Example:
4379 acl value req.hdr(X-Value) -m found
4380 acl setmap path /setmap
4381 acl delmap path /delmap
4382
4383 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
4384
4385 http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value
4386 http-request del-map(map.lst) %[src] if delmap
4387
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02004388 See also : "stats http-request", section 3.4 about userlists and section 7
4389 about ACL usage.
Willy Tarreauef781042010-01-27 11:53:01 +01004390
Willy Tarreauf4c43c12013-06-11 17:01:13 +02004391http-response { allow | deny | add-header <name> <fmt> | set-nice <nice> |
Willy Tarreau51d861a2015-05-22 17:30:48 +02004392 capture <sample> id <id> | redirect <rule> |
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02004393 set-header <name> <fmt> | del-header <name> |
Sasha Pachev218f0642014-06-16 12:05:59 -06004394 replace-header <name> <regex-match> <replace-fmt> |
4395 replace-value <name> <regex-match> <replace-fmt> |
Robin H. Johnson52f5db22017-01-01 13:10:52 -08004396 set-status <status> [reason <str>] |
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004397 set-log-level <level> | set-mark <mark> | set-tos <tos> |
4398 add-acl(<file name>) <key fmt> |
4399 del-acl(<file name>) <key fmt> |
4400 del-map(<file name>) <key fmt> |
Thierry FOURNIER90da1912015-03-05 11:17:06 +01004401 set-map(<file name>) <key fmt> <value fmt> |
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004402 set-var(<var-name>) <expr> |
Christopher Faulet85d79c92016-11-09 16:54:56 +01004403 unset-var(<var-name>) |
Ruoshan Huange4edc6b2016-07-14 15:07:45 +08004404 { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] |
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02004405 sc-inc-gpc0(<sc-id>) |
Thierry FOURNIER236657b2015-08-19 08:25:14 +02004406 sc-set-gpt0(<sc-id>) <int> |
Willy Tarreau2d392c22015-08-24 01:43:45 +02004407 silent-drop |
William Lallemand86d0df02017-11-24 21:36:45 +01004408 send-spoe-group |
4409 cache-store
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004410 }
Lukas Tribus2dd1d1a2013-06-19 23:34:41 +02004411 [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004412 Access control for Layer 7 responses
4413
4414 May be used in sections: defaults | frontend | listen | backend
4415 no | yes | yes | yes
4416
4417 The http-response statement defines a set of rules which apply to layer 7
4418 processing. The rules are evaluated in their declaration order when they are
4419 met in a frontend, listen or backend section. Any rule may optionally be
4420 followed by an ACL-based condition, in which case it will only be evaluated
4421 if the condition is true. Since these rules apply on responses, the backend
4422 rules are applied first, followed by the frontend's rules.
4423
4424 The first keyword is the rule's action. Currently supported actions include :
4425 - "allow" : this stops the evaluation of the rules and lets the response
4426 pass the check. No further "http-response" rules are evaluated for the
4427 current section.
4428
4429 - "deny" : this stops the evaluation of the rules and immediately rejects
4430 the response and emits an HTTP 502 error. No further "http-response"
4431 rules are evaluated.
4432
4433 - "add-header" appends an HTTP header field whose name is specified in
4434 <name> and whose value is defined by <fmt> which follows the log-format
4435 rules (see Custom Log Format in section 8.2.4). This may be used to send
4436 a cookie to a client for example, or to pass some internal information.
4437 This rule is not final, so it is possible to add other similar rules.
4438 Note that header addition is performed immediately, so one rule might
4439 reuse the resulting header from a previous rule.
4440
4441 - "set-header" does the same as "add-header" except that the header name
4442 is first removed if it existed. This is useful when passing security
4443 information to the server, where the header must not be manipulated by
4444 external users.
4445
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02004446 - "del-header" removes all HTTP header fields whose name is specified in
4447 <name>.
4448
Sasha Pachev218f0642014-06-16 12:05:59 -06004449 - "replace-header" matches the regular expression in all occurrences of
4450 header field <name> according to <match-regex>, and replaces them with
4451 the <replace-fmt> argument. Format characters are allowed in replace-fmt
4452 and work like in <fmt> arguments in "add-header". The match is only
4453 case-sensitive. It is important to understand that this action only
4454 considers whole header lines, regardless of the number of values they
4455 may contain. This usage is suited to headers naturally containing commas
4456 in their value, such as Set-Cookie, Expires and so on.
4457
4458 Example:
4459
4460 http-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2
4461
4462 applied to:
4463
4464 Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT
4465
4466 outputs:
4467
4468 Set-Cookie: C=1;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT
4469
4470 assuming the backend IP is 192.168.1.20.
4471
4472 - "replace-value" works like "replace-header" except that it matches the
4473 regex against every comma-delimited value of the header field <name>
4474 instead of the entire header. This is suited for all headers which are
4475 allowed to carry more than one value. An example could be the Accept
4476 header.
4477
4478 Example:
4479
4480 http-response replace-value Cache-control ^public$ private
4481
4482 applied to:
4483
4484 Cache-Control: max-age=3600, public
4485
4486 outputs:
4487
4488 Cache-Control: max-age=3600, private
4489
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02004490 - "set-status" replaces the response status code with <status> which must
Robin H. Johnson52f5db22017-01-01 13:10:52 -08004491 be an integer between 100 and 999. Optionally, a custom reason text can be
4492 provided defined by <str>, or the default reason for the specified code
4493 will be used as a fallback.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02004494
4495 Example:
4496
4497 # return "431 Request Header Fields Too Large"
4498 http-response set-status 431
Robin H. Johnson52f5db22017-01-01 13:10:52 -08004499 # return "503 Slow Down", custom reason
4500 http-response set-status 503 reason "Slow Down".
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02004501
Willy Tarreauf4c43c12013-06-11 17:01:13 +02004502 - "set-nice" sets the "nice" factor of the current request being processed.
4503 It only has effect against the other requests being processed at the same
4504 time. The default value is 0, unless altered by the "nice" setting on the
4505 "bind" line. The accepted range is -1024..1024. The higher the value, the
4506 nicest the request will be. Lower values will make the request more
4507 important than other ones. This can be useful to improve the speed of
4508 some requests, or lower the priority of non-important requests. Using
4509 this setting without prior experimentation can cause some major slowdown.
4510
Willy Tarreau9a355ec2013-06-11 17:45:46 +02004511 - "set-log-level" is used to change the log level of the current request
4512 when a certain condition is met. Valid levels are the 8 syslog levels
4513 (see the "log" keyword) plus the special level "silent" which disables
4514 logging for this request. This rule is not final so the last matching
4515 rule wins. This rule can be useful to disable health checks coming from
4516 another equipment.
4517
Willy Tarreau42cf39e2013-06-11 18:51:32 +02004518 - "set-tos" is used to set the TOS or DSCP field value of packets sent to
4519 the client to the value passed in <tos> on platforms which support this.
4520 This value represents the whole 8 bits of the IP TOS field, and can be
4521 expressed both in decimal or hexadecimal format (prefixed by "0x"). Note
4522 that only the 6 higher bits are used in DSCP or TOS, and the two lower
4523 bits are always 0. This can be used to adjust some routing behaviour on
4524 border routers based on some information from the request. See RFC 2474,
4525 2597, 3260 and 4594 for more information.
4526
Willy Tarreau51347ed2013-06-11 19:34:13 +02004527 - "set-mark" is used to set the Netfilter MARK on all packets sent to the
4528 client to the value passed in <mark> on platforms which support it. This
4529 value is an unsigned 32 bit value which can be matched by netfilter and
4530 by the routing table. It can be expressed both in decimal or hexadecimal
4531 format (prefixed by "0x"). This can be useful to force certain packets to
4532 take a different route (for example a cheaper network path for bulk
4533 downloads). This works on Linux kernels 2.6.32 and above and requires
4534 admin privileges.
4535
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004536 - "add-acl" is used to add a new entry into an ACL. The ACL must be loaded
4537 from a file (even a dummy empty file). The file name of the ACL to be
4538 updated is passed between parentheses. It takes one argument: <key fmt>,
4539 which follows log-format rules, to collect content of the new entry. It
4540 performs a lookup in the ACL before insertion, to avoid duplicated (or
4541 more) values. This lookup is done by a linear search and can be expensive
4542 with large lists! It is the equivalent of the "add acl" command from the
4543 stats socket, but can be triggered by an HTTP response.
4544
4545 - "del-acl" is used to delete an entry from an ACL. The ACL must be loaded
4546 from a file (even a dummy empty file). The file name of the ACL to be
4547 updated is passed between parentheses. It takes one argument: <key fmt>,
4548 which follows log-format rules, to collect content of the entry to delete.
4549 It is the equivalent of the "del acl" command from the stats socket, but
4550 can be triggered by an HTTP response.
4551
4552 - "del-map" is used to delete an entry from a MAP. The MAP must be loaded
4553 from a file (even a dummy empty file). The file name of the MAP to be
4554 updated is passed between parentheses. It takes one argument: <key fmt>,
4555 which follows log-format rules, to collect content of the entry to delete.
4556 It takes one argument: "file name" It is the equivalent of the "del map"
4557 command from the stats socket, but can be triggered by an HTTP response.
4558
4559 - "set-map" is used to add a new entry into a MAP. The MAP must be loaded
4560 from a file (even a dummy empty file). The file name of the MAP to be
4561 updated is passed between parentheses. It takes 2 arguments: <key fmt>,
4562 which follows log-format rules, used to collect MAP key, and <value fmt>,
4563 which follows log-format rules, used to collect content for the new entry.
4564 It performs a lookup in the MAP before insertion, to avoid duplicated (or
4565 more) values. This lookup is done by a linear search and can be expensive
4566 with large lists! It is the equivalent of the "set map" command from the
4567 stats socket, but can be triggered by an HTTP response.
4568
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02004569 - capture <sample> id <id> :
4570 captures sample expression <sample> from the response buffer, and converts
4571 it to a string. The resulting string is stored into the next request
4572 "capture" slot, so it will possibly appear next to some captured HTTP
4573 headers. It will then automatically appear in the logs, and it will be
4574 possible to extract it using sample fetch rules to feed it into headers or
4575 anything. Please check section 7.3 (Fetching samples) and "capture
4576 response header" for more information.
4577
4578 The keyword "id" is the id of the capture slot which is used for storing
4579 the string. The capture slot must be defined in an associated frontend.
4580 This is useful to run captures in backends. The slot id can be declared by
4581 a previous directive "http-response capture" or with the "declare capture"
4582 keyword.
Baptiste Assmanne9544932015-11-03 23:31:35 +01004583 If the slot <id> doesn't exist, then HAProxy fails parsing the
4584 configuration to prevent unexpected behavior at run time.
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02004585
William Lallemand86d0df02017-11-24 21:36:45 +01004586 - cache-store <name> :
4587 See section 10.2 about cache setup.
4588
Willy Tarreau51d861a2015-05-22 17:30:48 +02004589 - "redirect" : this performs an HTTP redirection based on a redirect rule.
4590 This supports a format string similarly to "http-request redirect" rules,
4591 with the exception that only the "location" type of redirect is possible
4592 on the response. See the "redirect" keyword for the rule's syntax. When
4593 a redirect rule is applied during a response, connections to the server
4594 are closed so that no data can be forwarded from the server to the client.
4595
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004596 - set-var(<var-name>) expr:
4597 Is used to set the contents of a variable. The variable is declared
4598 inline.
4599
Daniel Schneller0b547052016-03-21 20:46:57 +01004600 <var-name> The name of the variable starts with an indication about
4601 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +01004602 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +01004603 "sess" : the variable is shared with the whole session
4604 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004605 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +01004606 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004607 processing
Daniel Schneller0b547052016-03-21 20:46:57 +01004608 "res" : the variable is shared only during response
4609 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004610 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +01004611 The name may only contain characters 'a-z', 'A-Z', '0-9',
4612 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004613
4614 <expr> Is a standard HAProxy expression formed by a sample-fetch
4615 followed by some converters.
4616
4617 Example:
4618
4619 http-response set-var(sess.last_redir) res.hdr(location)
4620
Christopher Faulet85d79c92016-11-09 16:54:56 +01004621 - unset-var(<var-name>) :
4622 Is used to unset a variable. See above for details about <var-name>.
4623
4624 Example:
4625
4626 http-response unset-var(sess.last_redir)
4627
Ruoshan Huange4edc6b2016-07-14 15:07:45 +08004628 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] :
4629 enables tracking of sticky counters from current response. Please refer to
4630 "http-request track-sc" for a complete description. The only difference
4631 from "http-request track-sc" is the <key> sample expression can only make
4632 use of samples in response (eg. res.*, status etc.) and samples below
4633 Layer 6 (eg. ssl related samples, see section 7.3.4). If the sample is
4634 not supported, haproxy will fail and warn while parsing the config.
4635
Thierry FOURNIER236657b2015-08-19 08:25:14 +02004636 - sc-set-gpt0(<sc-id>) <int> :
4637 This action sets the GPT0 tag according to the sticky counter designated
4638 by <sc-id> and the value of <int>. The expected result is a boolean. If
4639 an error occurs, this action silently fails and the actions evaluation
4640 continues.
4641
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02004642 - sc-inc-gpc0(<sc-id>):
4643 This action increments the GPC0 counter according with the sticky counter
4644 designated by <sc-id>. If an error occurs, this action silently fails and
4645 the actions evaluation continues.
4646
Willy Tarreau2d392c22015-08-24 01:43:45 +02004647 - "silent-drop" : this stops the evaluation of the rules and makes the
4648 client-facing connection suddenly disappear using a system-dependant way
4649 that tries to prevent the client from being notified. The effect it then
4650 that the client still sees an established connection while there's none
4651 on HAProxy. The purpose is to achieve a comparable effect to "tarpit"
4652 except that it doesn't use any local resource at all on the machine
4653 running HAProxy. It can resist much higher loads than "tarpit", and slow
4654 down stronger attackers. It is important to undestand the impact of using
4655 this mechanism. All stateful equipments placed between the client and
4656 HAProxy (firewalls, proxies, load balancers) will also keep the
4657 established connection for a long time and may suffer from this action.
4658 On modern Linux systems running with enough privileges, the TCP_REPAIR
4659 socket option is used to block the emission of a TCP reset. On other
4660 systems, the socket's TTL is reduced to 1 so that the TCP reset doesn't
4661 pass the first router, though it's still delivered to local networks. Do
4662 not use it unless you fully understand how it works.
4663
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004664 - send-spoe-group <engine-name> <group-name> :
4665 This action is used to trigger sending of a group of SPOE messages. To do
4666 so, the SPOE engine used to send messages must be defined, as well as the
4667 SPOE group to send. Of course, the SPOE engine must refer to an existing
4668 SPOE filter. If not engine name is provided on the SPOE filter line, the
4669 SPOE agent name must be used.
4670
4671 <engine-name> The SPOE engine name.
4672
4673 <group-name> The SPOE group name as specified in the engine
4674 configuration.
4675
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004676 There is no limit to the number of http-response statements per instance.
4677
Godbach09250262013-07-02 01:19:15 +08004678 It is important to know that http-response rules are processed very early in
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08004679 the HTTP processing, before "rspdel" or "rsprep" or "rspadd" rules. That way,
4680 headers added by "add-header"/"set-header" are visible by almost all further ACL
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004681 rules.
4682
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08004683 Using "rspadd"/"rspdel"/"rsprep" to manipulate request headers is discouraged
4684 in newer versions (>= 1.5). But if you need to use regular expression to
4685 delete headers, you can still use "rspdel". Also please use
4686 "http-response deny" instead of "rspdeny".
4687
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004688 Example:
4689 acl key_acl res.hdr(X-Acl-Key) -m found
4690
4691 acl myhost hdr(Host) -f myhost.lst
4692
4693 http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
4694 http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
4695
4696 Example:
4697 acl value res.hdr(X-Value) -m found
4698
4699 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
4700
4701 http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value
4702 http-response del-map(map.lst) %[src] if ! value
4703
Willy Tarreaue365c0b2013-06-11 16:06:12 +02004704 See also : "http-request", section 3.4 about userlists and section 7 about
4705 ACL usage.
4706
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02004707
Willy Tarreau30631952015-08-06 15:05:24 +02004708http-reuse { never | safe | aggressive | always }
4709 Declare how idle HTTP connections may be shared between requests
4710
4711 May be used in sections: defaults | frontend | listen | backend
4712 yes | no | yes | yes
4713
4714 By default, a connection established between haproxy and the backend server
4715 belongs to the session that initiated it. The downside is that between the
4716 response and the next request, the connection remains idle and is not used.
4717 In many cases for performance reasons it is desirable to make it possible to
4718 reuse these idle connections to serve other requests from different sessions.
4719 This directive allows to tune this behaviour.
4720
4721 The argument indicates the desired connection reuse strategy :
4722
4723 - "never" : idle connections are never shared between sessions. This is
4724 the default choice. It may be enforced to cancel a different
4725 strategy inherited from a defaults section or for
4726 troubleshooting. For example, if an old bogus application
4727 considers that multiple requests over the same connection come
4728 from the same client and it is not possible to fix the
4729 application, it may be desirable to disable connection sharing
4730 in a single backend. An example of such an application could
4731 be an old haproxy using cookie insertion in tunnel mode and
4732 not checking any request past the first one.
4733
4734 - "safe" : this is the recommended strategy. The first request of a
4735 session is always sent over its own connection, and only
4736 subsequent requests may be dispatched over other existing
4737 connections. This ensures that in case the server closes the
4738 connection when the request is being sent, the browser can
4739 decide to silently retry it. Since it is exactly equivalent to
4740 regular keep-alive, there should be no side effects.
4741
4742 - "aggressive" : this mode may be useful in webservices environments where
4743 all servers are not necessarily known and where it would be
4744 appreciable to deliver most first requests over existing
4745 connections. In this case, first requests are only delivered
4746 over existing connections that have been reused at least once,
4747 proving that the server correctly supports connection reuse.
4748 It should only be used when it's sure that the client can
4749 retry a failed request once in a while and where the benefit
4750 of aggressive connection reuse significantly outweights the
4751 downsides of rare connection failures.
4752
4753 - "always" : this mode is only recommended when the path to the server is
4754 known for never breaking existing connections quickly after
4755 releasing them. It allows the first request of a session to be
4756 sent to an existing connection. This can provide a significant
4757 performance increase over the "safe" strategy when the backend
4758 is a cache farm, since such components tend to show a
4759 consistent behaviour and will benefit from the connection
4760 sharing. It is recommended that the "http-keep-alive" timeout
4761 remains low in this mode so that no dead connections remain
4762 usable. In most cases, this will lead to the same performance
4763 gains as "aggressive" but with more risks. It should only be
4764 used when it improves the situation over "aggressive".
4765
4766 When http connection sharing is enabled, a great care is taken to respect the
4767 connection properties and compatiblities. Specifically :
4768 - connections made with "usesrc" followed by a client-dependant value
4769 ("client", "clientip", "hdr_ip") are marked private and never shared ;
4770
4771 - connections sent to a server with a TLS SNI extension are marked private
4772 and are never shared ;
4773
4774 - connections receiving a status code 401 or 407 expect some authentication
4775 to be sent in return. Due to certain bogus authentication schemes (such
4776 as NTLM) relying on the connection, these connections are marked private
4777 and are never shared ;
4778
4779 No connection pool is involved, once a session dies, the last idle connection
4780 it was attached to is deleted at the same time. This ensures that connections
4781 may not last after all sessions are closed.
4782
4783 Note: connection reuse improves the accuracy of the "server maxconn" setting,
4784 because almost no new connection will be established while idle connections
4785 remain available. This is particularly true with the "always" strategy.
4786
4787 See also : "option http-keep-alive", "server maxconn"
4788
4789
Mark Lamourinec2247f02012-01-04 13:02:01 -05004790http-send-name-header [<header>]
4791 Add the server name to a request. Use the header string given by <header>
4792
4793 May be used in sections: defaults | frontend | listen | backend
4794 yes | no | yes | yes
4795
4796 Arguments :
4797
4798 <header> The header string to use to send the server name
4799
4800 The "http-send-name-header" statement causes the name of the target
4801 server to be added to the headers of an HTTP request. The name
4802 is added with the header string proved.
4803
4804 See also : "server"
4805
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01004806id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02004807 Set a persistent ID to a proxy.
4808 May be used in sections : defaults | frontend | listen | backend
4809 no | yes | yes | yes
4810 Arguments : none
4811
4812 Set a persistent ID for the proxy. This ID must be unique and positive.
4813 An unused ID will automatically be assigned if unset. The first assigned
4814 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01004815
4816
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004817ignore-persist { if | unless } <condition>
4818 Declare a condition to ignore persistence
4819 May be used in sections: defaults | frontend | listen | backend
4820 no | yes | yes | yes
4821
4822 By default, when cookie persistence is enabled, every requests containing
4823 the cookie are unconditionally persistent (assuming the target server is up
4824 and running).
4825
4826 The "ignore-persist" statement allows one to declare various ACL-based
4827 conditions which, when met, will cause a request to ignore persistence.
4828 This is sometimes useful to load balance requests for static files, which
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03004829 often don't require persistence. This can also be used to fully disable
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004830 persistence for a specific User-Agent (for example, some web crawler bots).
4831
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004832 The persistence is ignored when an "if" condition is met, or unless an
4833 "unless" condition is met.
4834
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03004835 Example:
4836 acl url_static path_beg /static /images /img /css
4837 acl url_static path_end .gif .png .jpg .css .js
4838 ignore-persist if url_static
4839
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004840 See also : "force-persist", "cookie", and section 7 about ACL usage.
4841
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004842load-server-state-from-file { global | local | none }
4843 Allow seamless reload of HAProxy
4844 May be used in sections: defaults | frontend | listen | backend
4845 yes | no | yes | yes
4846
4847 This directive points HAProxy to a file where server state from previous
4848 running process has been saved. That way, when starting up, before handling
4849 traffic, the new process can apply old states to servers exactly has if no
4850 reload occured. The purpose of the "load-server-state-from-file" directive is
4851 to tell haproxy which file to use. For now, only 2 arguments to either prevent
4852 loading state or load states from a file containing all backends and servers.
4853 The state file can be generated by running the command "show servers state"
4854 over the stats socket and redirect output.
4855
4856 The format of the file is versionned and is very specific. To understand it,
4857 please read the documentation of the "show servers state" command (chapter
Willy Tarreau1af20c72017-06-23 16:01:14 +02004858 9.3 of Management Guide).
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004859
4860 Arguments:
4861 global load the content of the file pointed by the global directive
4862 named "server-state-file".
4863
4864 local load the content of the file pointed by the directive
4865 "server-state-file-name" if set. If not set, then the backend
4866 name is used as a file name.
4867
4868 none don't load any stat for this backend
4869
4870 Notes:
Willy Tarreaue5a60682016-11-09 14:54:53 +01004871 - server's IP address is preserved across reloads by default, but the
4872 order can be changed thanks to the server's "init-addr" setting. This
4873 means that an IP address change performed on the CLI at run time will
4874 be preserved, and that any change to the local resolver (eg: /etc/hosts)
4875 will possibly not have any effect if the state file is in use.
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004876
4877 - server's weight is applied from previous running process unless it has
4878 has changed between previous and new configuration files.
4879
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02004880 Example: Minimal configuration
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004881
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02004882 global
4883 stats socket /tmp/socket
4884 server-state-file /tmp/server_state
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004885
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02004886 defaults
4887 load-server-state-from-file global
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004888
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02004889 backend bk
4890 server s1 127.0.0.1:22 check weight 11
4891 server s2 127.0.0.1:22 check weight 12
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004892
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004893
4894 Then one can run :
4895
4896 socat /tmp/socket - <<< "show servers state" > /tmp/server_state
4897
4898 Content of the file /tmp/server_state would be like this:
4899
4900 1
4901 # <field names skipped for the doc example>
4902 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
4903 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
4904
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02004905 Example: Minimal configuration
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004906
4907 global
4908 stats socket /tmp/socket
4909 server-state-base /etc/haproxy/states
4910
4911 defaults
4912 load-server-state-from-file local
4913
4914 backend bk
4915 server s1 127.0.0.1:22 check weight 11
4916 server s2 127.0.0.1:22 check weight 12
4917
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02004918
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02004919 Then one can run :
4920
4921 socat /tmp/socket - <<< "show servers state bk" > /etc/haproxy/states/bk
4922
4923 Content of the file /etc/haproxy/states/bk would be like this:
4924
4925 1
4926 # <field names skipped for the doc example>
4927 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
4928 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
4929
4930 See also: "server-state-file", "server-state-file-name", and
4931 "show servers state"
4932
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004933
Willy Tarreau2769aa02007-12-27 18:26:09 +01004934log global
Willy Tarreau18324f52014-06-27 18:10:07 +02004935log <address> [len <length>] <facility> [<level> [<minlevel>]]
William Lallemand0f99e342011-10-12 17:50:54 +02004936no log
Willy Tarreau2769aa02007-12-27 18:26:09 +01004937 Enable per-instance logging of events and traffic.
4938 May be used in sections : defaults | frontend | listen | backend
4939 yes | yes | yes | yes
William Lallemand0f99e342011-10-12 17:50:54 +02004940
4941 Prefix :
4942 no should be used when the logger list must be flushed. For example,
4943 if you don't want to inherit from the default logger list. This
4944 prefix does not allow arguments.
4945
Willy Tarreau2769aa02007-12-27 18:26:09 +01004946 Arguments :
4947 global should be used when the instance's logging parameters are the
4948 same as the global ones. This is the most common usage. "global"
4949 replaces <address>, <facility> and <level> with those of the log
4950 entries found in the "global" section. Only one "log global"
4951 statement may be used per instance, and this form takes no other
4952 parameter.
4953
4954 <address> indicates where to send the logs. It takes the same format as
4955 for the "global" section's logs, and can be one of :
4956
4957 - An IPv4 address optionally followed by a colon (':') and a UDP
4958 port. If no port is specified, 514 is used by default (the
4959 standard syslog port).
4960
David du Colombier24bb5f52011-03-17 10:40:23 +01004961 - An IPv6 address followed by a colon (':') and optionally a UDP
4962 port. If no port is specified, 514 is used by default (the
4963 standard syslog port).
4964
Willy Tarreau2769aa02007-12-27 18:26:09 +01004965 - A filesystem path to a UNIX domain socket, keeping in mind
4966 considerations for chroot (be sure the path is accessible
4967 inside the chroot) and uid/gid (be sure the path is
4968 appropriately writeable).
4969
William Lallemandb2f07452015-05-12 14:27:13 +02004970 You may want to reference some environment variables in the
4971 address parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01004972
Willy Tarreau18324f52014-06-27 18:10:07 +02004973 <length> is an optional maximum line length. Log lines larger than this
4974 value will be truncated before being sent. The reason is that
4975 syslog servers act differently on log line length. All servers
4976 support the default value of 1024, but some servers simply drop
4977 larger lines while others do log them. If a server supports long
4978 lines, it may make sense to set this value here in order to avoid
4979 truncating long lines. Similarly, if a server drops long lines,
4980 it is preferable to truncate them before sending them. Accepted
4981 values are 80 to 65535 inclusive. The default value of 1024 is
4982 generally fine for all standard usages. Some specific cases of
4983 long captures or JSON-formated logs may require larger values.
4984
Willy Tarreau2769aa02007-12-27 18:26:09 +01004985 <facility> must be one of the 24 standard syslog facilities :
4986
4987 kern user mail daemon auth syslog lpr news
4988 uucp cron auth2 ftp ntp audit alert cron2
4989 local0 local1 local2 local3 local4 local5 local6 local7
4990
4991 <level> is optional and can be specified to filter outgoing messages. By
4992 default, all messages are sent. If a level is specified, only
4993 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02004994 will be sent. An optional minimum level can be specified. If it
4995 is set, logs emitted with a more severe level than this one will
4996 be capped to this level. This is used to avoid sending "emerg"
4997 messages on all terminals on some default syslog configurations.
4998 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01004999
5000 emerg alert crit err warning notice info debug
5001
William Lallemand0f99e342011-10-12 17:50:54 +02005002 It is important to keep in mind that it is the frontend which decides what to
5003 log from a connection, and that in case of content switching, the log entries
5004 from the backend will be ignored. Connections are logged at level "info".
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005005
5006 However, backend log declaration define how and where servers status changes
5007 will be logged. Level "notice" will be used to indicate a server going up,
5008 "warning" will be used for termination signals and definitive service
5009 termination, and "alert" will be used for when a server goes down.
5010
5011 Note : According to RFC3164, messages are truncated to 1024 bytes before
5012 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005013
5014 Example :
5015 log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02005016 log 127.0.0.1:514 local0 notice # only send important events
5017 log 127.0.0.1:514 local0 notice notice # same but limit output level
William Lallemandb2f07452015-05-12 14:27:13 +02005018 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
Willy Tarreaudad36a32013-03-11 01:20:04 +01005019
Willy Tarreau2769aa02007-12-27 18:26:09 +01005020
William Lallemand48940402012-01-30 16:47:22 +01005021log-format <string>
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01005022 Specifies the log format string to use for traffic logs
5023 May be used in sections: defaults | frontend | listen | backend
5024 yes | yes | yes | no
William Lallemand48940402012-01-30 16:47:22 +01005025
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01005026 This directive specifies the log format string that will be used for all logs
5027 resulting from traffic passing through the frontend using this line. If the
5028 directive is used in a defaults section, all subsequent frontends will use
5029 the same log format. Please see section 8.2.4 which covers the log format
5030 string in depth.
William Lallemand48940402012-01-30 16:47:22 +01005031
Guillaume de Lafond29f45602017-03-31 19:52:15 +02005032 "log-format" directive overrides previous "option tcplog", "log-format" and
5033 "option httplog" directives.
5034
Dragan Dosen7ad31542015-09-28 17:16:47 +02005035log-format-sd <string>
5036 Specifies the RFC5424 structured-data log format string
5037 May be used in sections: defaults | frontend | listen | backend
5038 yes | yes | yes | no
5039
5040 This directive specifies the RFC5424 structured-data log format string that
5041 will be used for all logs resulting from traffic passing through the frontend
5042 using this line. If the directive is used in a defaults section, all
5043 subsequent frontends will use the same log format. Please see section 8.2.4
5044 which covers the log format string in depth.
5045
5046 See https://tools.ietf.org/html/rfc5424#section-6.3 for more information
5047 about the RFC5424 structured-data part.
5048
5049 Note : This log format string will be used only for loggers that have set
5050 log format to "rfc5424".
5051
5052 Example :
5053 log-format-sd [exampleSDID@1234\ bytes=\"%B\"\ status=\"%ST\"]
5054
5055
Willy Tarreau094af4e2015-01-07 15:03:42 +01005056log-tag <string>
5057 Specifies the log tag to use for all outgoing logs
5058 May be used in sections: defaults | frontend | listen | backend
5059 yes | yes | yes | yes
5060
5061 Sets the tag field in the syslog header to this string. It defaults to the
5062 log-tag set in the global section, otherwise the program name as launched
5063 from the command line, which usually is "haproxy". Sometimes it can be useful
5064 to differentiate between multiple processes running on the same host, or to
5065 differentiate customer instances running in the same process. In the backend,
5066 logs about servers up/down will use this tag. As a hint, it can be convenient
5067 to set a log-tag related to a hosted customer in a defaults section then put
5068 all the frontends and backends for that customer, then start another customer
5069 in a new defaults section. See also the global "log-tag" directive.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005070
Willy Tarreauc35362a2014-04-25 13:58:37 +02005071max-keep-alive-queue <value>
5072 Set the maximum server queue size for maintaining keep-alive connections
5073 May be used in sections: defaults | frontend | listen | backend
5074 yes | no | yes | yes
5075
5076 HTTP keep-alive tries to reuse the same server connection whenever possible,
5077 but sometimes it can be counter-productive, for example if a server has a lot
5078 of connections while other ones are idle. This is especially true for static
5079 servers.
5080
5081 The purpose of this setting is to set a threshold on the number of queued
5082 connections at which haproxy stops trying to reuse the same server and prefers
5083 to find another one. The default value, -1, means there is no limit. A value
5084 of zero means that keep-alive requests will never be queued. For very close
5085 servers which can be reached with a low latency and which are not sensible to
5086 breaking keep-alive, a low value is recommended (eg: local static server can
5087 use a value of 10 or less). For remote servers suffering from a high latency,
5088 higher values might be needed to cover for the latency and/or the cost of
5089 picking a different server.
5090
5091 Note that this has no impact on responses which are maintained to the same
5092 server consecutively to a 401 response. They will still go to the same server
5093 even if they have to be queued.
5094
5095 See also : "option http-server-close", "option prefer-last-server", server
5096 "maxconn" and cookie persistence.
5097
5098
Willy Tarreau2769aa02007-12-27 18:26:09 +01005099maxconn <conns>
5100 Fix the maximum number of concurrent connections on a frontend
5101 May be used in sections : defaults | frontend | listen | backend
5102 yes | yes | yes | no
5103 Arguments :
5104 <conns> is the maximum number of concurrent connections the frontend will
5105 accept to serve. Excess connections will be queued by the system
5106 in the socket's listen queue and will be served once a connection
5107 closes.
5108
5109 If the system supports it, it can be useful on big sites to raise this limit
5110 very high so that haproxy manages connection queues, instead of leaving the
5111 clients with unanswered connection attempts. This value should not exceed the
5112 global maxconn. Also, keep in mind that a connection contains two buffers
Baptiste Assmann79fb45d2016-03-06 23:34:31 +01005113 of tune.bufsize (16kB by default) each, as well as some other data resulting
5114 in about 33 kB of RAM being consumed per established connection. That means
5115 that a medium system equipped with 1GB of RAM can withstand around
5116 20000-25000 concurrent connections if properly tuned.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005117
5118 Also, when <conns> is set to large values, it is possible that the servers
5119 are not sized to accept such loads, and for this reason it is generally wise
5120 to assign them some reasonable connection limits.
5121
Vincent Bernat6341be52012-06-27 17:18:30 +02005122 By default, this value is set to 2000.
5123
Willy Tarreau2769aa02007-12-27 18:26:09 +01005124 See also : "server", global section's "maxconn", "fullconn"
5125
5126
5127mode { tcp|http|health }
5128 Set the running mode or protocol of the instance
5129 May be used in sections : defaults | frontend | listen | backend
5130 yes | yes | yes | yes
5131 Arguments :
5132 tcp The instance will work in pure TCP mode. A full-duplex connection
5133 will be established between clients and servers, and no layer 7
5134 examination will be performed. This is the default mode. It
5135 should be used for SSL, SSH, SMTP, ...
5136
5137 http The instance will work in HTTP mode. The client request will be
5138 analyzed in depth before connecting to any server. Any request
5139 which is not RFC-compliant will be rejected. Layer 7 filtering,
5140 processing and switching will be possible. This is the mode which
5141 brings HAProxy most of its value.
5142
5143 health The instance will work in "health" mode. It will just reply "OK"
Willy Tarreau82569f92012-09-27 23:48:56 +02005144 to incoming connections and close the connection. Alternatively,
5145 If the "httpchk" option is set, "HTTP/1.0 200 OK" will be sent
5146 instead. Nothing will be logged in either case. This mode is used
5147 to reply to external components health checks. This mode is
5148 deprecated and should not be used anymore as it is possible to do
5149 the same and even better by combining TCP or HTTP modes with the
5150 "monitor" keyword.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005151
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005152 When doing content switching, it is mandatory that the frontend and the
5153 backend are in the same mode (generally HTTP), otherwise the configuration
5154 will be refused.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005155
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005156 Example :
Willy Tarreau2769aa02007-12-27 18:26:09 +01005157 defaults http_instances
5158 mode http
5159
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005160 See also : "monitor", "monitor-net"
Willy Tarreau2769aa02007-12-27 18:26:09 +01005161
Willy Tarreau0ba27502007-12-24 16:55:16 +01005162
Cyril Bontéf0c60612010-02-06 14:44:47 +01005163monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01005164 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01005165 May be used in sections : defaults | frontend | listen | backend
5166 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01005167 Arguments :
5168 if <cond> the monitor request will fail if the condition is satisfied,
5169 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005170 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01005171 are met, for instance a low number of servers both in a
5172 backend and its backup.
5173
5174 unless <cond> the monitor request will succeed only if the condition is
5175 satisfied, and will fail otherwise. Such a condition may be
5176 based on a test on the presence of a minimum number of active
5177 servers in a list of backends.
5178
5179 This statement adds a condition which can force the response to a monitor
5180 request to report a failure. By default, when an external component queries
5181 the URI dedicated to monitoring, a 200 response is returned. When one of the
5182 conditions above is met, haproxy will return 503 instead of 200. This is
5183 very useful to report a site failure to an external component which may base
5184 routing advertisements between multiple sites on the availability reported by
5185 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02005186 criterion. Note that "monitor fail" only works in HTTP mode. Both status
5187 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01005188
5189 Example:
5190 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01005191 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01005192 acl site_dead nbsrv(dynamic) lt 2
5193 acl site_dead nbsrv(static) lt 2
5194 monitor-uri /site_alive
5195 monitor fail if site_dead
5196
Willy Tarreauae94d4d2011-05-11 16:28:49 +02005197 See also : "monitor-net", "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01005198
5199
5200monitor-net <source>
5201 Declare a source network which is limited to monitor requests
5202 May be used in sections : defaults | frontend | listen | backend
5203 yes | yes | yes | no
5204 Arguments :
5205 <source> is the source IPv4 address or network which will only be able to
5206 get monitor responses to any request. It can be either an IPv4
5207 address, a host name, or an address followed by a slash ('/')
5208 followed by a mask.
5209
5210 In TCP mode, any connection coming from a source matching <source> will cause
5211 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005212 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01005213 forwarding the connection to a remote server.
5214
5215 In HTTP mode, a connection coming from a source matching <source> will be
5216 accepted, the following response will be sent without waiting for a request,
5217 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
5218 enough for any front-end HTTP probe to detect that the service is UP and
Willy Tarreau82569f92012-09-27 23:48:56 +02005219 running without forwarding the request to a backend server. Note that this
5220 response is sent in raw format, without any transformation. This is important
5221 as it means that it will not be SSL-encrypted on SSL listeners.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005222
Willy Tarreau82569f92012-09-27 23:48:56 +02005223 Monitor requests are processed very early, just after tcp-request connection
5224 ACLs which are the only ones able to block them. These connections are short
5225 lived and never wait for any data from the client. They cannot be logged, and
5226 it is the intended purpose. They are only used to report HAProxy's health to
5227 an upper component, nothing more. Please note that "monitor fail" rules do
5228 not apply to connections intercepted by "monitor-net".
Willy Tarreau2769aa02007-12-27 18:26:09 +01005229
Willy Tarreau95cd2832010-03-04 23:36:33 +01005230 Last, please note that only one "monitor-net" statement can be specified in
5231 a frontend. If more than one is found, only the last one will be considered.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005232
Willy Tarreau2769aa02007-12-27 18:26:09 +01005233 Example :
5234 # addresses .252 and .253 are just probing us.
5235 frontend www
5236 monitor-net 192.168.0.252/31
5237
5238 See also : "monitor fail", "monitor-uri"
5239
5240
5241monitor-uri <uri>
5242 Intercept a URI used by external components' monitor requests
5243 May be used in sections : defaults | frontend | listen | backend
5244 yes | yes | yes | no
5245 Arguments :
5246 <uri> is the exact URI which we want to intercept to return HAProxy's
5247 health status instead of forwarding the request.
5248
5249 When an HTTP request referencing <uri> will be received on a frontend,
5250 HAProxy will not forward it nor log it, but instead will return either
5251 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
5252 conditions defined with "monitor fail". This is normally enough for any
5253 front-end HTTP probe to detect that the service is UP and running without
5254 forwarding the request to a backend server. Note that the HTTP method, the
5255 version and all headers are ignored, but the request must at least be valid
5256 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
5257
Willy Tarreau721d8e02017-12-01 18:25:08 +01005258 Monitor requests are processed very early, just after the request is parsed
5259 and even before any "http-request" or "block" rulesets. The only rulesets
5260 applied before are the tcp-request ones. They cannot be logged either, and it
5261 is the intended purpose. They are only used to report HAProxy's health to an
5262 upper component, nothing more. However, it is possible to add any number of
5263 conditions using "monitor fail" and ACLs so that the result can be adjusted
5264 to whatever check can be imagined (most often the number of available servers
5265 in a backend).
Willy Tarreau2769aa02007-12-27 18:26:09 +01005266
5267 Example :
5268 # Use /haproxy_test to report haproxy's status
5269 frontend www
5270 mode http
5271 monitor-uri /haproxy_test
5272
5273 See also : "monitor fail", "monitor-net"
5274
Willy Tarreau0ba27502007-12-24 16:55:16 +01005275
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005276option abortonclose
5277no option abortonclose
5278 Enable or disable early dropping of aborted requests pending in queues.
5279 May be used in sections : defaults | frontend | listen | backend
5280 yes | no | yes | yes
5281 Arguments : none
5282
5283 In presence of very high loads, the servers will take some time to respond.
5284 The per-instance connection queue will inflate, and the response time will
5285 increase respective to the size of the queue times the average per-session
5286 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01005287 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005288 the queue, and slowing down other users, and the servers as well, because the
5289 request will eventually be served, then aborted at the first error
5290 encountered while delivering the response.
5291
5292 As there is no way to distinguish between a full STOP and a simple output
5293 close on the client side, HTTP agents should be conservative and consider
5294 that the client might only have closed its output channel while waiting for
5295 the response. However, this introduces risks of congestion when lots of users
5296 do the same, and is completely useless nowadays because probably no client at
5297 all will close the session while waiting for the response. Some HTTP agents
Willy Tarreaud72758d2010-01-12 10:42:19 +01005298 support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005299 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01005300 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005301 of being the single component to break rare but valid traffic is extremely
5302 low, which adds to the temptation to be able to abort a session early while
5303 still not served and not pollute the servers.
5304
5305 In HAProxy, the user can choose the desired behaviour using the option
5306 "abortonclose". By default (without the option) the behaviour is HTTP
5307 compliant and aborted requests will be served. But when the option is
5308 specified, a session with an incoming channel closed will be aborted while
5309 it is still possible, either pending in the queue for a connection slot, or
5310 during the connection establishment if the server has not yet acknowledged
5311 the connection request. This considerably reduces the queue size and the load
5312 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01005313 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005314
5315 If this option has been enabled in a "defaults" section, it can be disabled
5316 in a specific instance by prepending the "no" keyword before it.
5317
5318 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
5319
5320
Willy Tarreau4076a152009-04-02 15:18:36 +02005321option accept-invalid-http-request
5322no option accept-invalid-http-request
5323 Enable or disable relaxing of HTTP request parsing
5324 May be used in sections : defaults | frontend | listen | backend
5325 yes | yes | yes | no
5326 Arguments : none
5327
Willy Tarreau91852eb2015-05-01 13:26:00 +02005328 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02005329 means that invalid characters in header names are not permitted and cause an
5330 error to be returned to the client. This is the desired behaviour as such
5331 forbidden characters are essentially used to build attacks exploiting server
5332 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
5333 server will emit invalid header names for whatever reason (configuration,
5334 implementation) and the issue will not be immediately fixed. In such a case,
5335 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau422246e2012-01-07 23:54:13 +01005336 even if that does not make sense, by specifying this option. Similarly, the
5337 list of characters allowed to appear in a URI is well defined by RFC3986, and
5338 chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
5339 ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
5340 not allowed at all. Haproxy always blocks a number of them (0..32, 127). The
Willy Tarreau91852eb2015-05-01 13:26:00 +02005341 remaining ones are blocked by default unless this option is enabled. This
Willy Tarreau13317662015-05-01 13:47:08 +02005342 option also relaxes the test on the HTTP version, it allows HTTP/0.9 requests
5343 to pass through (no version specified) and multiple digits for both the major
5344 and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02005345
5346 This option should never be enabled by default as it hides application bugs
5347 and open security breaches. It should only be deployed after a problem has
5348 been confirmed.
5349
5350 When this option is enabled, erroneous header names will still be accepted in
5351 requests, but the complete request will be captured in order to permit later
Willy Tarreau422246e2012-01-07 23:54:13 +01005352 analysis using the "show errors" request on the UNIX stats socket. Similarly,
5353 requests containing invalid chars in the URI part will be logged. Doing this
Willy Tarreau4076a152009-04-02 15:18:36 +02005354 also helps confirming that the issue has been solved.
5355
5356 If this option has been enabled in a "defaults" section, it can be disabled
5357 in a specific instance by prepending the "no" keyword before it.
5358
5359 See also : "option accept-invalid-http-response" and "show errors" on the
5360 stats socket.
5361
5362
5363option accept-invalid-http-response
5364no option accept-invalid-http-response
5365 Enable or disable relaxing of HTTP response parsing
5366 May be used in sections : defaults | frontend | listen | backend
5367 yes | no | yes | yes
5368 Arguments : none
5369
Willy Tarreau91852eb2015-05-01 13:26:00 +02005370 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02005371 means that invalid characters in header names are not permitted and cause an
5372 error to be returned to the client. This is the desired behaviour as such
5373 forbidden characters are essentially used to build attacks exploiting server
5374 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
5375 server will emit invalid header names for whatever reason (configuration,
5376 implementation) and the issue will not be immediately fixed. In such a case,
5377 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau91852eb2015-05-01 13:26:00 +02005378 even if that does not make sense, by specifying this option. This option also
5379 relaxes the test on the HTTP version format, it allows multiple digits for
5380 both the major and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02005381
5382 This option should never be enabled by default as it hides application bugs
5383 and open security breaches. It should only be deployed after a problem has
5384 been confirmed.
5385
5386 When this option is enabled, erroneous header names will still be accepted in
5387 responses, but the complete response will be captured in order to permit
5388 later analysis using the "show errors" request on the UNIX stats socket.
5389 Doing this also helps confirming that the issue has been solved.
5390
5391 If this option has been enabled in a "defaults" section, it can be disabled
5392 in a specific instance by prepending the "no" keyword before it.
5393
5394 See also : "option accept-invalid-http-request" and "show errors" on the
5395 stats socket.
5396
5397
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005398option allbackups
5399no option allbackups
5400 Use either all backup servers at a time or only the first one
5401 May be used in sections : defaults | frontend | listen | backend
5402 yes | no | yes | yes
5403 Arguments : none
5404
5405 By default, the first operational backup server gets all traffic when normal
5406 servers are all down. Sometimes, it may be preferred to use multiple backups
5407 at once, because one will not be enough. When "option allbackups" is enabled,
5408 the load balancing will be performed among all backup servers when all normal
5409 ones are unavailable. The same load balancing algorithm will be used and the
5410 servers' weights will be respected. Thus, there will not be any priority
5411 order between the backup servers anymore.
5412
5413 This option is mostly used with static server farms dedicated to return a
5414 "sorry" page when an application is completely offline.
5415
5416 If this option has been enabled in a "defaults" section, it can be disabled
5417 in a specific instance by prepending the "no" keyword before it.
5418
5419
5420option checkcache
5421no option checkcache
Godbach7056a352013-12-11 20:01:07 +08005422 Analyze all server responses and block responses with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005423 May be used in sections : defaults | frontend | listen | backend
5424 yes | no | yes | yes
5425 Arguments : none
5426
5427 Some high-level frameworks set application cookies everywhere and do not
5428 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005429 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005430 high risk of session crossing or stealing between users traversing the same
5431 caches. In some situations, it is better to block the response than to let
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02005432 some sensitive session information go in the wild.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005433
5434 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005435 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01005436 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005437 response to check if there's a risk of caching a cookie on a client-side
5438 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01005439 to the client are :
5440 - all those without "Set-Cookie" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005441 - all those with a return code other than 200, 203, 206, 300, 301, 410,
Willy Tarreau198a7442008-01-17 12:05:32 +01005442 provided that the server has not set a "Cache-control: public" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005443 - all those that come from a POST request, provided that the server has not
5444 set a 'Cache-Control: public' header ;
5445 - those with a 'Pragma: no-cache' header
5446 - those with a 'Cache-control: private' header
5447 - those with a 'Cache-control: no-store' header
5448 - those with a 'Cache-control: max-age=0' header
5449 - those with a 'Cache-control: s-maxage=0' header
5450 - those with a 'Cache-control: no-cache' header
5451 - those with a 'Cache-control: no-cache="set-cookie"' header
5452 - those with a 'Cache-control: no-cache="set-cookie,' header
5453 (allowing other fields after set-cookie)
5454
5455 If a response doesn't respect these requirements, then it will be blocked
Willy Tarreau198a7442008-01-17 12:05:32 +01005456 just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005457 The session state shows "PH--" meaning that the proxy blocked the response
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005458 during headers processing. Additionally, an alert will be sent in the logs so
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005459 that admins are informed that there's something to be fixed.
5460
5461 Due to the high impact on the application, the application should be tested
5462 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01005463 good practice to always activate it during tests, even if it is not used in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005464 production, as it will report potentially dangerous application behaviours.
5465
5466 If this option has been enabled in a "defaults" section, it can be disabled
5467 in a specific instance by prepending the "no" keyword before it.
5468
5469
5470option clitcpka
5471no option clitcpka
5472 Enable or disable the sending of TCP keepalive packets on the client side
5473 May be used in sections : defaults | frontend | listen | backend
5474 yes | yes | yes | no
5475 Arguments : none
5476
5477 When there is a firewall or any session-aware component between a client and
5478 a server, and when the protocol involves very long sessions with long idle
5479 periods (eg: remote desktops), there is a risk that one of the intermediate
5480 components decides to expire a session which has remained idle for too long.
5481
5482 Enabling socket-level TCP keep-alives makes the system regularly send packets
5483 to the other end of the connection, leaving it active. The delay between
5484 keep-alive probes is controlled by the system only and depends both on the
5485 operating system and its tuning parameters.
5486
5487 It is important to understand that keep-alive packets are neither emitted nor
5488 received at the application level. It is only the network stacks which sees
5489 them. For this reason, even if one side of the proxy already uses keep-alives
5490 to maintain its connection alive, those keep-alive packets will not be
5491 forwarded to the other side of the proxy.
5492
5493 Please note that this has nothing to do with HTTP keep-alive.
5494
5495 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
5496 client side of a connection, which should help when session expirations are
5497 noticed between HAProxy and a client.
5498
5499 If this option has been enabled in a "defaults" section, it can be disabled
5500 in a specific instance by prepending the "no" keyword before it.
5501
5502 See also : "option srvtcpka", "option tcpka"
5503
5504
Willy Tarreau0ba27502007-12-24 16:55:16 +01005505option contstats
5506 Enable continuous traffic statistics updates
5507 May be used in sections : defaults | frontend | listen | backend
5508 yes | yes | yes | no
5509 Arguments : none
5510
5511 By default, counters used for statistics calculation are incremented
5512 only when a session finishes. It works quite well when serving small
5513 objects, but with big ones (for example large images or archives) or
5514 with A/V streaming, a graph generated from haproxy counters looks like
Willy Tarreaudef0d222016-11-08 22:03:00 +01005515 a hedgehog. With this option enabled counters get incremented frequently
5516 along the session, typically every 5 seconds, which is often enough to
5517 produce clean graphs. Recounting touches a hotpath directly so it is not
5518 not enabled by default, as it can cause a lot of wakeups for very large
5519 session counts and cause a small performance drop.
Willy Tarreau0ba27502007-12-24 16:55:16 +01005520
5521
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02005522option dontlog-normal
5523no option dontlog-normal
5524 Enable or disable logging of normal, successful connections
5525 May be used in sections : defaults | frontend | listen | backend
5526 yes | yes | yes | no
5527 Arguments : none
5528
5529 There are large sites dealing with several thousand connections per second
5530 and for which logging is a major pain. Some of them are even forced to turn
5531 logs off and cannot debug production issues. Setting this option ensures that
5532 normal connections, those which experience no error, no timeout, no retry nor
5533 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
5534 mode, the response status code is checked and return codes 5xx will still be
5535 logged.
5536
5537 It is strongly discouraged to use this option as most of the time, the key to
5538 complex issues is in the normal logs which will not be logged here. If you
5539 need to separate logs, see the "log-separate-errors" option instead.
5540
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005541 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02005542 logging.
5543
5544
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005545option dontlognull
5546no option dontlognull
5547 Enable or disable logging of null connections
5548 May be used in sections : defaults | frontend | listen | backend
5549 yes | yes | yes | no
5550 Arguments : none
5551
5552 In certain environments, there are components which will regularly connect to
5553 various systems to ensure that they are still alive. It can be the case from
5554 another load balancer as well as from monitoring systems. By default, even a
5555 simple port probe or scan will produce a log. If those connections pollute
5556 the logs too much, it is possible to enable option "dontlognull" to indicate
5557 that a connection on which no data has been transferred will not be logged,
Willy Tarreau0f228a02015-05-01 15:37:53 +02005558 which typically corresponds to those probes. Note that errors will still be
5559 returned to the client and accounted for in the stats. If this is not what is
5560 desired, option http-ignore-probes can be used instead.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005561
5562 It is generally recommended not to use this option in uncontrolled
5563 environments (eg: internet), otherwise scans and other malicious activities
5564 would not be logged.
5565
5566 If this option has been enabled in a "defaults" section, it can be disabled
5567 in a specific instance by prepending the "no" keyword before it.
5568
Willy Tarreau0f228a02015-05-01 15:37:53 +02005569 See also : "log", "http-ignore-probes", "monitor-net", "monitor-uri", and
5570 section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005571
5572
5573option forceclose
5574no option forceclose
5575 Enable or disable active connection closing after response is transferred.
5576 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaua31e5df2009-12-30 01:10:35 +01005577 yes | yes | yes | yes
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005578 Arguments : none
5579
5580 Some HTTP servers do not necessarily close the connections when they receive
5581 the "Connection: close" set by "option httpclose", and if the client does not
5582 close either, then the connection remains open till the timeout expires. This
5583 causes high number of simultaneous connections on the servers and shows high
5584 global session times in the logs.
5585
5586 When this happens, it is possible to use "option forceclose". It will
Willy Tarreau82eeaf22009-12-29 12:09:05 +01005587 actively close the outgoing server channel as soon as the server has finished
Cyril Bonté653dcd62014-02-20 00:13:15 +01005588 to respond and release some resources earlier than with "option httpclose".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005589
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005590 This option may also be combined with "option http-pretend-keepalive", which
5591 will disable sending of the "Connection: close" header, but will still cause
5592 the connection to be closed once the whole response is received.
5593
Cyril Bonté653dcd62014-02-20 00:13:15 +01005594 This option disables and replaces any previous "option httpclose", "option
5595 http-server-close", "option http-keep-alive", or "option http-tunnel".
Willy Tarreau02bce8b2014-01-30 00:15:28 +01005596
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005597 If this option has been enabled in a "defaults" section, it can be disabled
5598 in a specific instance by prepending the "no" keyword before it.
5599
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005600 See also : "option httpclose" and "option http-pretend-keepalive"
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005601
5602
Willy Tarreau87cf5142011-08-19 22:57:24 +02005603option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01005604 Enable insertion of the X-Forwarded-For header to requests sent to servers
5605 May be used in sections : defaults | frontend | listen | backend
5606 yes | yes | yes | yes
5607 Arguments :
5608 <network> is an optional argument used to disable this option for sources
5609 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02005610 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01005611 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01005612
5613 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
5614 their client address. This is sometimes annoying when the client's IP address
5615 is expected in server logs. To solve this problem, the well-known HTTP header
5616 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
5617 This header contains a value representing the client's IP address. Since this
5618 header is always appended at the end of the existing header list, the server
5619 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02005620 the server's manual to find how to enable use of this standard header. Note
5621 that only the last occurrence of the header must be used, since it is really
5622 possible that the client has already brought one.
5623
Willy Tarreaud72758d2010-01-12 10:42:19 +01005624 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02005625 the default "X-Forwarded-For". This can be useful where you might already
Willy Tarreaud72758d2010-01-12 10:42:19 +01005626 have a "X-Forwarded-For" header from a different application (eg: stunnel),
5627 and you need preserve it. Also if your backend server doesn't use the
Ross Westaf72a1d2008-08-03 10:51:45 +02005628 "X-Forwarded-For" header and requires different one (eg: Zeus Web Servers
5629 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01005630
5631 Sometimes, a same HAProxy instance may be shared between a direct client
5632 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
5633 used to decrypt HTTPS traffic). It is possible to disable the addition of the
5634 header for a known source address or network by adding the "except" keyword
5635 followed by the network address. In this case, any source IP matching the
5636 network will not cause an addition of this header. Most common uses are with
5637 private networks or 127.0.0.1.
5638
Willy Tarreau87cf5142011-08-19 22:57:24 +02005639 Alternatively, the keyword "if-none" states that the header will only be
5640 added if it is not present. This should only be used in perfectly trusted
5641 environment, as this might cause a security issue if headers reaching haproxy
5642 are under the control of the end-user.
5643
Willy Tarreauc27debf2008-01-06 08:57:02 +01005644 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02005645 least one of them uses it, the header will be added. Note that the backend's
5646 setting of the header subargument takes precedence over the frontend's if
Willy Tarreau87cf5142011-08-19 22:57:24 +02005647 both are defined. In the case of the "if-none" argument, if at least one of
5648 the frontend or the backend does not specify it, it wants the addition to be
5649 mandatory, so it wins.
Willy Tarreauc27debf2008-01-06 08:57:02 +01005650
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005651 Example :
Willy Tarreauc27debf2008-01-06 08:57:02 +01005652 # Public HTTP address also used by stunnel on the same machine
5653 frontend www
5654 mode http
5655 option forwardfor except 127.0.0.1 # stunnel already adds the header
5656
Ross Westaf72a1d2008-08-03 10:51:45 +02005657 # Those servers want the IP Address in X-Client
5658 backend www
5659 mode http
5660 option forwardfor header X-Client
5661
Willy Tarreau87cf5142011-08-19 22:57:24 +02005662 See also : "option httpclose", "option http-server-close",
Willy Tarreau70dffda2014-01-30 03:07:23 +01005663 "option forceclose", "option http-keep-alive"
Willy Tarreauc27debf2008-01-06 08:57:02 +01005664
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005665
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02005666option http-buffer-request
5667no option http-buffer-request
5668 Enable or disable waiting for whole HTTP request body before proceeding
5669 May be used in sections : defaults | frontend | listen | backend
5670 yes | yes | yes | yes
5671 Arguments : none
5672
5673 It is sometimes desirable to wait for the body of an HTTP request before
5674 taking a decision. This is what is being done by "balance url_param" for
5675 example. The first use case is to buffer requests from slow clients before
5676 connecting to the server. Another use case consists in taking the routing
5677 decision based on the request body's contents. This option placed in a
5678 frontend or backend forces the HTTP processing to wait until either the whole
5679 body is received, or the request buffer is full, or the first chunk is
5680 complete in case of chunked encoding. It can have undesired side effects with
Tim Düsterhus4896c442016-11-29 02:15:19 +01005681 some applications abusing HTTP by expecting unbuffered transmissions between
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02005682 the frontend and the backend, so this should definitely not be used by
5683 default.
5684
Baptiste Assmanneccdf432015-10-28 13:49:01 +01005685 See also : "option http-no-delay", "timeout http-request"
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02005686
5687
Willy Tarreau0f228a02015-05-01 15:37:53 +02005688option http-ignore-probes
5689no option http-ignore-probes
5690 Enable or disable logging of null connections and request timeouts
5691 May be used in sections : defaults | frontend | listen | backend
5692 yes | yes | yes | no
5693 Arguments : none
5694
5695 Recently some browsers started to implement a "pre-connect" feature
5696 consisting in speculatively connecting to some recently visited web sites
5697 just in case the user would like to visit them. This results in many
5698 connections being established to web sites, which end up in 408 Request
5699 Timeout if the timeout strikes first, or 400 Bad Request when the browser
5700 decides to close them first. These ones pollute the log and feed the error
5701 counters. There was already "option dontlognull" but it's insufficient in
5702 this case. Instead, this option does the following things :
5703 - prevent any 400/408 message from being sent to the client if nothing
5704 was received over a connection before it was closed ;
5705 - prevent any log from being emitted in this situation ;
5706 - prevent any error counter from being incremented
5707
5708 That way the empty connection is silently ignored. Note that it is better
5709 not to use this unless it is clear that it is needed, because it will hide
5710 real problems. The most common reason for not receiving a request and seeing
5711 a 408 is due to an MTU inconsistency between the client and an intermediary
5712 element such as a VPN, which blocks too large packets. These issues are
5713 generally seen with POST requests as well as GET with large cookies. The logs
5714 are often the only way to detect them.
5715
5716 If this option has been enabled in a "defaults" section, it can be disabled
5717 in a specific instance by prepending the "no" keyword before it.
5718
5719 See also : "log", "dontlognull", "errorfile", and section 8 about logging.
5720
5721
Willy Tarreau16bfb022010-01-16 19:48:41 +01005722option http-keep-alive
5723no option http-keep-alive
5724 Enable or disable HTTP keep-alive from client to server
5725 May be used in sections : defaults | frontend | listen | backend
5726 yes | yes | yes | yes
5727 Arguments : none
5728
Willy Tarreau70dffda2014-01-30 03:07:23 +01005729 By default HAProxy operates in keep-alive mode with regards to persistent
5730 connections: for each connection it processes each request and response, and
5731 leaves the connection idle on both sides between the end of a response and the
5732 start of a new request. This mode may be changed by several options such as
5733 "option http-server-close", "option forceclose", "option httpclose" or
5734 "option http-tunnel". This option allows to set back the keep-alive mode,
5735 which can be useful when another mode was used in a defaults section.
5736
5737 Setting "option http-keep-alive" enables HTTP keep-alive mode on the client-
5738 and server- sides. This provides the lowest latency on the client side (slow
Willy Tarreau16bfb022010-01-16 19:48:41 +01005739 network) and the fastest session reuse on the server side at the expense
5740 of maintaining idle connections to the servers. In general, it is possible
5741 with this option to achieve approximately twice the request rate that the
5742 "http-server-close" option achieves on small objects. There are mainly two
5743 situations where this option may be useful :
5744
5745 - when the server is non-HTTP compliant and authenticates the connection
5746 instead of requests (eg: NTLM authentication)
5747
5748 - when the cost of establishing the connection to the server is significant
5749 compared to the cost of retrieving the associated object from the server.
5750
5751 This last case can happen when the server is a fast static server of cache.
5752 In this case, the server will need to be properly tuned to support high enough
5753 connection counts because connections will last until the client sends another
5754 request.
5755
5756 If the client request has to go to another backend or another server due to
5757 content switching or the load balancing algorithm, the idle connection will
Willy Tarreau9420b122013-12-15 18:58:25 +01005758 immediately be closed and a new one re-opened. Option "prefer-last-server" is
5759 available to try optimize server selection so that if the server currently
5760 attached to an idle connection is usable, it will be used.
Willy Tarreau16bfb022010-01-16 19:48:41 +01005761
5762 In general it is preferred to use "option http-server-close" with application
5763 servers, and some static servers might benefit from "option http-keep-alive".
5764
5765 At the moment, logs will not indicate whether requests came from the same
5766 session or not. The accept date reported in the logs corresponds to the end
5767 of the previous request, and the request time corresponds to the time spent
5768 waiting for a new request. The keep-alive request time is still bound to the
5769 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
5770 not set.
5771
Cyril Bonté653dcd62014-02-20 00:13:15 +01005772 This option disables and replaces any previous "option httpclose", "option
5773 http-server-close", "option forceclose" or "option http-tunnel". When backend
Willy Tarreau70dffda2014-01-30 03:07:23 +01005774 and frontend options differ, all of these 4 options have precedence over
Cyril Bonté653dcd62014-02-20 00:13:15 +01005775 "option http-keep-alive".
Willy Tarreau16bfb022010-01-16 19:48:41 +01005776
5777 See also : "option forceclose", "option http-server-close",
Willy Tarreau9420b122013-12-15 18:58:25 +01005778 "option prefer-last-server", "option http-pretend-keepalive",
5779 "option httpclose", and "1.1. The HTTP transaction model".
Willy Tarreau16bfb022010-01-16 19:48:41 +01005780
5781
Willy Tarreau96e31212011-05-30 18:10:30 +02005782option http-no-delay
5783no option http-no-delay
5784 Instruct the system to favor low interactive delays over performance in HTTP
5785 May be used in sections : defaults | frontend | listen | backend
5786 yes | yes | yes | yes
5787 Arguments : none
5788
5789 In HTTP, each payload is unidirectional and has no notion of interactivity.
5790 Any agent is expected to queue data somewhat for a reasonably low delay.
5791 There are some very rare server-to-server applications that abuse the HTTP
5792 protocol and expect the payload phase to be highly interactive, with many
5793 interleaved data chunks in both directions within a single request. This is
5794 absolutely not supported by the HTTP specification and will not work across
5795 most proxies or servers. When such applications attempt to do this through
5796 haproxy, it works but they will experience high delays due to the network
5797 optimizations which favor performance by instructing the system to wait for
5798 enough data to be available in order to only send full packets. Typical
5799 delays are around 200 ms per round trip. Note that this only happens with
5800 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
5801 affected.
5802
5803 When "option http-no-delay" is present in either the frontend or the backend
5804 used by a connection, all such optimizations will be disabled in order to
5805 make the exchanges as fast as possible. Of course this offers no guarantee on
5806 the functionality, as it may break at any other place. But if it works via
5807 HAProxy, it will work as fast as possible. This option should never be used
5808 by default, and should never be used at all unless such a buggy application
5809 is discovered. The impact of using this option is an increase of bandwidth
5810 usage and CPU usage, which may significantly lower performance in high
5811 latency environments.
5812
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02005813 See also : "option http-buffer-request"
5814
Willy Tarreau96e31212011-05-30 18:10:30 +02005815
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005816option http-pretend-keepalive
5817no option http-pretend-keepalive
5818 Define whether haproxy will announce keepalive to the server or not
5819 May be used in sections : defaults | frontend | listen | backend
5820 yes | yes | yes | yes
5821 Arguments : none
5822
5823 When running with "option http-server-close" or "option forceclose", haproxy
5824 adds a "Connection: close" header to the request forwarded to the server.
5825 Unfortunately, when some servers see this header, they automatically refrain
5826 from using the chunked encoding for responses of unknown length, while this
5827 is totally unrelated. The immediate effect is that this prevents haproxy from
5828 maintaining the client connection alive. A second effect is that a client or
5829 a cache could receive an incomplete response without being aware of it, and
5830 consider the response complete.
5831
5832 By setting "option http-pretend-keepalive", haproxy will make the server
5833 believe it will keep the connection alive. The server will then not fall back
5834 to the abnormal undesired above. When haproxy gets the whole response, it
5835 will close the connection with the server just as it would do with the
5836 "forceclose" option. That way the client gets a normal response and the
5837 connection is correctly closed on the server side.
5838
5839 It is recommended not to enable this option by default, because most servers
5840 will more efficiently close the connection themselves after the last packet,
5841 and release its buffers slightly earlier. Also, the added packet on the
5842 network could slightly reduce the overall peak performance. However it is
5843 worth noting that when this option is enabled, haproxy will have slightly
5844 less work to do. So if haproxy is the bottleneck on the whole architecture,
5845 enabling this option might save a few CPU cycles.
5846
5847 This option may be set both in a frontend and in a backend. It is enabled if
5848 at least one of the frontend or backend holding a connection has it enabled.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04005849 This option may be combined with "option httpclose", which will cause
Willy Tarreau22a95342010-09-29 14:31:41 +02005850 keepalive to be announced to the server and close to be announced to the
5851 client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005852
5853 If this option has been enabled in a "defaults" section, it can be disabled
5854 in a specific instance by prepending the "no" keyword before it.
5855
Willy Tarreau16bfb022010-01-16 19:48:41 +01005856 See also : "option forceclose", "option http-server-close", and
5857 "option http-keep-alive"
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02005858
Willy Tarreauc27debf2008-01-06 08:57:02 +01005859
Willy Tarreaub608feb2010-01-02 22:47:18 +01005860option http-server-close
5861no option http-server-close
5862 Enable or disable HTTP connection closing on the server side
5863 May be used in sections : defaults | frontend | listen | backend
5864 yes | yes | yes | yes
5865 Arguments : none
5866
Willy Tarreau70dffda2014-01-30 03:07:23 +01005867 By default HAProxy operates in keep-alive mode with regards to persistent
5868 connections: for each connection it processes each request and response, and
5869 leaves the connection idle on both sides between the end of a response and
5870 the start of a new request. This mode may be changed by several options such
5871 as "option http-server-close", "option forceclose", "option httpclose" or
5872 "option http-tunnel". Setting "option http-server-close" enables HTTP
5873 connection-close mode on the server side while keeping the ability to support
5874 HTTP keep-alive and pipelining on the client side. This provides the lowest
5875 latency on the client side (slow network) and the fastest session reuse on
5876 the server side to save server resources, similarly to "option forceclose".
5877 It also permits non-keepalive capable servers to be served in keep-alive mode
Lukas Tribus23953682017-04-28 13:24:30 +00005878 to the clients if they conform to the requirements of RFC7230. Please note
Willy Tarreau70dffda2014-01-30 03:07:23 +01005879 that some servers do not always conform to those requirements when they see
5880 "Connection: close" in the request. The effect will be that keep-alive will
5881 never be used. A workaround consists in enabling "option
5882 http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01005883
5884 At the moment, logs will not indicate whether requests came from the same
5885 session or not. The accept date reported in the logs corresponds to the end
5886 of the previous request, and the request time corresponds to the time spent
5887 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01005888 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
5889 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01005890
5891 This option may be set both in a frontend and in a backend. It is enabled if
5892 at least one of the frontend or backend holding a connection has it enabled.
Cyril Bonté653dcd62014-02-20 00:13:15 +01005893 It disables and replaces any previous "option httpclose", "option forceclose",
5894 "option http-tunnel" or "option http-keep-alive". Please check section 4
Willy Tarreau70dffda2014-01-30 03:07:23 +01005895 ("Proxies") to see how this option combines with others when frontend and
5896 backend options differ.
Willy Tarreaub608feb2010-01-02 22:47:18 +01005897
5898 If this option has been enabled in a "defaults" section, it can be disabled
5899 in a specific instance by prepending the "no" keyword before it.
5900
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02005901 See also : "option forceclose", "option http-pretend-keepalive",
Willy Tarreau16bfb022010-01-16 19:48:41 +01005902 "option httpclose", "option http-keep-alive", and
5903 "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01005904
5905
Willy Tarreau02bce8b2014-01-30 00:15:28 +01005906option http-tunnel
5907no option http-tunnel
5908 Disable or enable HTTP connection processing after first transaction
5909 May be used in sections : defaults | frontend | listen | backend
5910 yes | yes | yes | yes
5911 Arguments : none
5912
Willy Tarreau70dffda2014-01-30 03:07:23 +01005913 By default HAProxy operates in keep-alive mode with regards to persistent
5914 connections: for each connection it processes each request and response, and
5915 leaves the connection idle on both sides between the end of a response and
5916 the start of a new request. This mode may be changed by several options such
5917 as "option http-server-close", "option forceclose", "option httpclose" or
5918 "option http-tunnel".
5919
5920 Option "http-tunnel" disables any HTTP processing past the first request and
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03005921 the first response. This is the mode which was used by default in versions
Willy Tarreau70dffda2014-01-30 03:07:23 +01005922 1.0 to 1.5-dev21. It is the mode with the lowest processing overhead, which
5923 is normally not needed anymore unless in very specific cases such as when
5924 using an in-house protocol that looks like HTTP but is not compatible, or
5925 just to log one request per client in order to reduce log size. Note that
5926 everything which works at the HTTP level, including header parsing/addition,
5927 cookie processing or content switching will only work for the first request
5928 and will be ignored after the first response.
Willy Tarreau02bce8b2014-01-30 00:15:28 +01005929
5930 If this option has been enabled in a "defaults" section, it can be disabled
5931 in a specific instance by prepending the "no" keyword before it.
5932
5933 See also : "option forceclose", "option http-server-close",
5934 "option httpclose", "option http-keep-alive", and
5935 "1.1. The HTTP transaction model".
5936
5937
Willy Tarreau88d349d2010-01-25 12:15:43 +01005938option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01005939no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01005940 Make use of non-standard Proxy-Connection header instead of Connection
5941 May be used in sections : defaults | frontend | listen | backend
5942 yes | yes | yes | no
5943 Arguments : none
5944
Lukas Tribus23953682017-04-28 13:24:30 +00005945 While RFC7230 explicitly states that HTTP/1.1 agents must use the
Willy Tarreau88d349d2010-01-25 12:15:43 +01005946 Connection header to indicate their wish of persistent or non-persistent
5947 connections, both browsers and proxies ignore this header for proxied
5948 connections and make use of the undocumented, non-standard Proxy-Connection
5949 header instead. The issue begins when trying to put a load balancer between
5950 browsers and such proxies, because there will be a difference between what
5951 haproxy understands and what the client and the proxy agree on.
5952
5953 By setting this option in a frontend, haproxy can automatically switch to use
5954 that non-standard header if it sees proxied requests. A proxied request is
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01005955 defined here as one where the URI begins with neither a '/' nor a '*'. This
5956 is incompatible with the HTTP tunnel mode. Note that this option can only be
5957 specified in a frontend and will affect the request along its whole life.
Willy Tarreau88d349d2010-01-25 12:15:43 +01005958
Willy Tarreau844a7e72010-01-31 21:46:18 +01005959 Also, when this option is set, a request which requires authentication will
5960 automatically switch to use proxy authentication headers if it is itself a
5961 proxied request. That makes it possible to check or enforce authentication in
5962 front of an existing proxy.
5963
Willy Tarreau88d349d2010-01-25 12:15:43 +01005964 This option should normally never be used, except in front of a proxy.
5965
5966 See also : "option httpclose", "option forceclose" and "option
5967 http-server-close".
5968
5969
Willy Tarreaud63335a2010-02-26 12:56:52 +01005970option httpchk
5971option httpchk <uri>
5972option httpchk <method> <uri>
5973option httpchk <method> <uri> <version>
5974 Enable HTTP protocol to check on the servers health
5975 May be used in sections : defaults | frontend | listen | backend
5976 yes | no | yes | yes
5977 Arguments :
5978 <method> is the optional HTTP method used with the requests. When not set,
5979 the "OPTIONS" method is used, as it generally requires low server
5980 processing and is easy to filter out from the logs. Any method
5981 may be used, though it is not recommended to invent non-standard
5982 ones.
5983
5984 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
5985 which is accessible by default on almost any server, but may be
5986 changed to any other URI. Query strings are permitted.
5987
5988 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
5989 but some servers might behave incorrectly in HTTP 1.0, so turning
5990 it to HTTP/1.1 may sometimes help. Note that the Host field is
5991 mandatory in HTTP/1.1, and as a trick, it is possible to pass it
5992 after "\r\n" following the version string.
5993
5994 By default, server health checks only consist in trying to establish a TCP
5995 connection. When "option httpchk" is specified, a complete HTTP request is
5996 sent once the TCP connection is established, and responses 2xx and 3xx are
5997 considered valid, while all other ones indicate a server failure, including
5998 the lack of any response.
5999
6000 The port and interval are specified in the server configuration.
6001
6002 This option does not necessarily require an HTTP backend, it also works with
6003 plain TCP backends. This is particularly useful to check simple scripts bound
6004 to some dedicated ports using the inetd daemon.
6005
6006 Examples :
6007 # Relay HTTPS traffic to Apache instance and check service availability
6008 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
6009 backend https_relay
6010 mode tcp
6011 option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www
6012 server apache1 192.168.1.1:443 check port 80
6013
Simon Hormanafc47ee2013-11-25 10:46:35 +09006014 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
6015 "option pgsql-check", "http-check" and the "check", "port" and
6016 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01006017
6018
Willy Tarreauc27debf2008-01-06 08:57:02 +01006019option httpclose
6020no option httpclose
6021 Enable or disable passive HTTP connection closing
6022 May be used in sections : defaults | frontend | listen | backend
6023 yes | yes | yes | yes
6024 Arguments : none
6025
Willy Tarreau70dffda2014-01-30 03:07:23 +01006026 By default HAProxy operates in keep-alive mode with regards to persistent
6027 connections: for each connection it processes each request and response, and
6028 leaves the connection idle on both sides between the end of a response and
6029 the start of a new request. This mode may be changed by several options such
Cyril Bonté653dcd62014-02-20 00:13:15 +01006030 as "option http-server-close", "option forceclose", "option httpclose" or
Willy Tarreau70dffda2014-01-30 03:07:23 +01006031 "option http-tunnel".
6032
6033 If "option httpclose" is set, HAProxy will work in HTTP tunnel mode and check
6034 if a "Connection: close" header is already set in each direction, and will
6035 add one if missing. Each end should react to this by actively closing the TCP
6036 connection after each transfer, thus resulting in a switch to the HTTP close
6037 mode. Any "Connection" header different from "close" will also be removed.
6038 Note that this option is deprecated since what it does is very cheap but not
6039 reliable. Using "option http-server-close" or "option forceclose" is strongly
6040 recommended instead.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006041
6042 It seldom happens that some servers incorrectly ignore this header and do not
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006043 close the connection even though they reply "Connection: close". For this
Willy Tarreau0dfdf192010-01-05 11:33:11 +01006044 reason, they are not compatible with older HTTP 1.0 browsers. If this happens
6045 it is possible to use the "option forceclose" which actively closes the
6046 request connection once the server responds. Option "forceclose" also
6047 releases the server connection earlier because it does not have to wait for
6048 the client to acknowledge it.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006049
6050 This option may be set both in a frontend and in a backend. It is enabled if
6051 at least one of the frontend or backend holding a connection has it enabled.
Cyril Bonté653dcd62014-02-20 00:13:15 +01006052 It disables and replaces any previous "option http-server-close",
6053 "option forceclose", "option http-keep-alive" or "option http-tunnel". Please
Willy Tarreau70dffda2014-01-30 03:07:23 +01006054 check section 4 ("Proxies") to see how this option combines with others when
6055 frontend and backend options differ.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006056
6057 If this option has been enabled in a "defaults" section, it can be disabled
6058 in a specific instance by prepending the "no" keyword before it.
6059
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02006060 See also : "option forceclose", "option http-server-close" and
6061 "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01006062
6063
Emeric Brun3a058f32009-06-30 18:26:00 +02006064option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01006065 Enable logging of HTTP request, session state and timers
6066 May be used in sections : defaults | frontend | listen | backend
6067 yes | yes | yes | yes
Emeric Brun3a058f32009-06-30 18:26:00 +02006068 Arguments :
6069 clf if the "clf" argument is added, then the output format will be
6070 the CLF format instead of HAProxy's default HTTP format. You can
6071 use this when you need to feed HAProxy's logs through a specific
6072 log analyser which only support the CLF format and which is not
6073 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006074
6075 By default, the log output format is very poor, as it only contains the
6076 source and destination addresses, and the instance name. By specifying
6077 "option httplog", each log line turns into a much richer format including,
6078 but not limited to, the HTTP request, the connection timers, the session
6079 status, the connections numbers, the captured headers and cookies, the
6080 frontend, backend and server name, and of course the source address and
6081 ports.
6082
6083 This option may be set either in the frontend or the backend.
6084
PiBa-NLbd556bf2014-12-11 21:31:54 +01006085 Specifying only "option httplog" will automatically clear the 'clf' mode
6086 if it was set by default.
Emeric Brun3a058f32009-06-30 18:26:00 +02006087
Guillaume de Lafond29f45602017-03-31 19:52:15 +02006088 "option httplog" overrides any previous "log-format" directive.
6089
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006090 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006091
Willy Tarreau55165fe2009-05-10 12:02:55 +02006092
6093option http_proxy
6094no option http_proxy
6095 Enable or disable plain HTTP proxy mode
6096 May be used in sections : defaults | frontend | listen | backend
6097 yes | yes | yes | yes
6098 Arguments : none
6099
6100 It sometimes happens that people need a pure HTTP proxy which understands
6101 basic proxy requests without caching nor any fancy feature. In this case,
6102 it may be worth setting up an HAProxy instance with the "option http_proxy"
6103 set. In this mode, no server is declared, and the connection is forwarded to
6104 the IP address and port found in the URL after the "http://" scheme.
6105
6106 No host address resolution is performed, so this only works when pure IP
6107 addresses are passed. Since this option's usage perimeter is rather limited,
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01006108 it will probably be used only by experts who know they need exactly it. This
6109 is incompatible with the HTTP tunnel mode.
Willy Tarreau55165fe2009-05-10 12:02:55 +02006110
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 Example :
6115 # this backend understands HTTP proxy requests and forwards them directly.
6116 backend direct_forward
6117 option httpclose
6118 option http_proxy
6119
6120 See also : "option httpclose"
6121
Willy Tarreau211ad242009-10-03 21:45:07 +02006122
Jamie Gloudon801a0a32012-08-25 00:18:33 -04006123option independent-streams
6124no option independent-streams
6125 Enable or disable independent timeout processing for both directions
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02006126 May be used in sections : defaults | frontend | listen | backend
6127 yes | yes | yes | yes
6128 Arguments : none
6129
6130 By default, when data is sent over a socket, both the write timeout and the
6131 read timeout for that socket are refreshed, because we consider that there is
6132 activity on that socket, and we have no other means of guessing if we should
6133 receive data or not.
6134
6135 While this default behaviour is desirable for almost all applications, there
6136 exists a situation where it is desirable to disable it, and only refresh the
6137 read timeout if there are incoming data. This happens on sessions with large
6138 timeouts and low amounts of exchanged data such as telnet session. If the
6139 server suddenly disappears, the output data accumulates in the system's
6140 socket buffers, both timeouts are correctly refreshed, and there is no way
6141 to know the server does not receive them, so we don't timeout. However, when
6142 the underlying protocol always echoes sent data, it would be enough by itself
6143 to detect the issue using the read timeout. Note that this problem does not
6144 happen with more verbose protocols because data won't accumulate long in the
6145 socket buffers.
6146
6147 When this option is set on the frontend, it will disable read timeout updates
6148 on data sent to the client. There probably is little use of this case. When
6149 the option is set on the backend, it will disable read timeout updates on
6150 data sent to the server. Doing so will typically break large HTTP posts from
6151 slow lines, so use it with caution.
6152
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006153 Note: older versions used to call this setting "option independent-streams"
Jamie Gloudon801a0a32012-08-25 00:18:33 -04006154 with a spelling mistake. This spelling is still supported but
6155 deprecated.
6156
Willy Tarreauce887fd2012-05-12 12:50:00 +02006157 See also : "timeout client", "timeout server" and "timeout tunnel"
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02006158
6159
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02006160option ldap-check
6161 Use LDAPv3 health checks for server testing
6162 May be used in sections : defaults | frontend | listen | backend
6163 yes | no | yes | yes
6164 Arguments : none
6165
6166 It is possible to test that the server correctly talks LDAPv3 instead of just
6167 testing that it accepts the TCP connection. When this option is set, an
6168 LDAPv3 anonymous simple bind message is sent to the server, and the response
6169 is analyzed to find an LDAPv3 bind response message.
6170
6171 The server is considered valid only when the LDAP response contains success
6172 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
6173
6174 Logging of bind requests is server dependent see your documentation how to
6175 configure it.
6176
6177 Example :
6178 option ldap-check
6179
6180 See also : "option httpchk"
6181
6182
Simon Horman98637e52014-06-20 12:30:16 +09006183option external-check
6184 Use external processes for server health checks
6185 May be used in sections : defaults | frontend | listen | backend
6186 yes | no | yes | yes
6187
6188 It is possible to test the health of a server using an external command.
6189 This is achieved by running the executable set using "external-check
6190 command".
6191
6192 Requires the "external-check" global to be set.
6193
6194 See also : "external-check", "external-check command", "external-check path"
6195
6196
Willy Tarreau211ad242009-10-03 21:45:07 +02006197option log-health-checks
6198no option log-health-checks
Willy Tarreaubef1b322014-05-13 21:01:39 +02006199 Enable or disable logging of health checks status updates
Willy Tarreau211ad242009-10-03 21:45:07 +02006200 May be used in sections : defaults | frontend | listen | backend
6201 yes | no | yes | yes
6202 Arguments : none
6203
Willy Tarreaubef1b322014-05-13 21:01:39 +02006204 By default, failed health check are logged if server is UP and successful
6205 health checks are logged if server is DOWN, so the amount of additional
6206 information is limited.
Willy Tarreau211ad242009-10-03 21:45:07 +02006207
Willy Tarreaubef1b322014-05-13 21:01:39 +02006208 When this option is enabled, any change of the health check status or to
6209 the server's health will be logged, so that it becomes possible to know
6210 that a server was failing occasional checks before crashing, or exactly when
6211 it failed to respond a valid HTTP status, then when the port started to
6212 reject connections, then when the server stopped responding at all.
6213
6214 Note that status changes not caused by health checks (eg: enable/disable on
6215 the CLI) are intentionally not logged by this option.
Willy Tarreau211ad242009-10-03 21:45:07 +02006216
Willy Tarreaubef1b322014-05-13 21:01:39 +02006217 See also: "option httpchk", "option ldap-check", "option mysql-check",
6218 "option pgsql-check", "option redis-check", "option smtpchk",
6219 "option tcp-check", "log" and section 8 about logging.
Willy Tarreau211ad242009-10-03 21:45:07 +02006220
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02006221
6222option log-separate-errors
6223no option log-separate-errors
6224 Change log level for non-completely successful connections
6225 May be used in sections : defaults | frontend | listen | backend
6226 yes | yes | yes | no
6227 Arguments : none
6228
6229 Sometimes looking for errors in logs is not easy. This option makes haproxy
6230 raise the level of logs containing potentially interesting information such
6231 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
6232 level changes from "info" to "err". This makes it possible to log them
6233 separately to a different file with most syslog daemons. Be careful not to
6234 remove them from the original file, otherwise you would lose ordering which
6235 provides very important information.
6236
6237 Using this option, large sites dealing with several thousand connections per
6238 second may log normal traffic to a rotating buffer and only archive smaller
6239 error logs.
6240
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006241 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02006242 logging.
6243
Willy Tarreauc27debf2008-01-06 08:57:02 +01006244
6245option logasap
6246no option logasap
6247 Enable or disable early logging of HTTP requests
6248 May be used in sections : defaults | frontend | listen | backend
6249 yes | yes | yes | no
6250 Arguments : none
6251
6252 By default, HTTP requests are logged upon termination so that the total
6253 transfer time and the number of bytes appear in the logs. When large objects
6254 are being transferred, it may take a while before the request appears in the
6255 logs. Using "option logasap", the request gets logged as soon as the server
6256 sends the complete headers. The only missing information in the logs will be
6257 the total number of bytes which will indicate everything except the amount
6258 of data transferred, and the total time which will not take the transfer
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006259 time into account. In such a situation, it's a good practice to capture the
Willy Tarreauc27debf2008-01-06 08:57:02 +01006260 "Content-Length" response header so that the logs at least indicate how many
6261 bytes are expected to be transferred.
6262
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006263 Examples :
6264 listen http_proxy 0.0.0.0:80
6265 mode http
6266 option httplog
6267 option logasap
6268 log 192.168.2.200 local3
6269
6270 >>> Feb 6 12:14:14 localhost \
6271 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
6272 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
6273 "GET /image.iso HTTP/1.0"
6274
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006275 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01006276 logging.
6277
6278
Nenad Merdanovic6639a7c2014-05-30 14:26:32 +02006279option mysql-check [ user <username> [ post-41 ] ]
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006280 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01006281 May be used in sections : defaults | frontend | listen | backend
6282 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006283 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006284 <username> This is the username which will be used when connecting to MySQL
6285 server.
Nenad Merdanovic6639a7c2014-05-30 14:26:32 +02006286 post-41 Send post v4.1 client compatible checks
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02006287
6288 If you specify a username, the check consists of sending two MySQL packet,
6289 one Client Authentication packet, and one QUIT packet, to correctly close
6290 MySQL session. We then parse the MySQL Handshake Initialisation packet and/or
6291 Error packet. It is a basic but useful test which does not produce error nor
6292 aborted connect on the server. However, it requires adding an authorization
6293 in the MySQL table, like this :
6294
6295 USE mysql;
6296 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
6297 FLUSH PRIVILEGES;
6298
6299 If you don't specify a username (it is deprecated and not recommended), the
6300 check only consists in parsing the Mysql Handshake Initialisation packet or
6301 Error packet, we don't send anything in this mode. It was reported that it
6302 can generate lockout if check is too frequent and/or if there is not enough
6303 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
6304 value as if a connection is established successfully within fewer than MySQL
6305 "max_connect_errors" attempts after a previous connection was interrupted,
6306 the error count for the host is cleared to zero. If HAProxy's server get
6307 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
6308
6309 Remember that this does not check database presence nor database consistency.
6310 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01006311
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02006312 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01006313
6314 Most often, an incoming MySQL server needs to see the client's IP address for
6315 various purposes, including IP privilege matching and connection logging.
6316 When possible, it is often wise to masquerade the client's IP address when
6317 connecting to the server using the "usesrc" argument of the "source" keyword,
Willy Tarreau29fbe512015-08-20 19:35:14 +02006318 which requires the transparent proxy feature to be compiled in, and the MySQL
6319 server to route the client via the machine hosting haproxy.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01006320
6321 See also: "option httpchk"
6322
6323
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006324option nolinger
6325no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006326 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006327 May be used in sections: defaults | frontend | listen | backend
6328 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006329 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006330
6331 When clients or servers abort connections in a dirty way (eg: they are
6332 physically disconnected), the session timeouts triggers and the session is
6333 closed. But it will remain in FIN_WAIT1 state for some time in the system,
6334 using some resources and possibly limiting the ability to establish newer
6335 connections.
6336
6337 When this happens, it is possible to activate "option nolinger" which forces
6338 the system to immediately remove any socket's pending data on close. Thus,
6339 the session is instantly purged from the system's tables. This usually has
6340 side effects such as increased number of TCP resets due to old retransmits
6341 getting immediately rejected. Some firewalls may sometimes complain about
6342 this too.
6343
6344 For this reason, it is not recommended to use this option when not absolutely
6345 needed. You know that you need it when you have thousands of FIN_WAIT1
6346 sessions on your system (TIME_WAIT ones do not count).
6347
6348 This option may be used both on frontends and backends, depending on the side
6349 where it is required. Use it on the frontend for clients, and on the backend
6350 for servers.
6351
6352 If this option has been enabled in a "defaults" section, it can be disabled
6353 in a specific instance by prepending the "no" keyword before it.
6354
6355
Willy Tarreau55165fe2009-05-10 12:02:55 +02006356option originalto [ except <network> ] [ header <name> ]
6357 Enable insertion of the X-Original-To header to requests sent to servers
6358 May be used in sections : defaults | frontend | listen | backend
6359 yes | yes | yes | yes
6360 Arguments :
6361 <network> is an optional argument used to disable this option for sources
6362 matching <network>
6363 <name> an optional argument to specify a different "X-Original-To"
6364 header name.
6365
6366 Since HAProxy can work in transparent mode, every request from a client can
6367 be redirected to the proxy and HAProxy itself can proxy every request to a
6368 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
6369 be lost. This is annoying when you want access rules based on destination ip
6370 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
6371 added by HAProxy to all requests sent to the server. This header contains a
6372 value representing the original destination IP address. Since this must be
6373 configured to always use the last occurrence of this header only. Note that
6374 only the last occurrence of the header must be used, since it is really
6375 possible that the client has already brought one.
6376
6377 The keyword "header" may be used to supply a different header name to replace
6378 the default "X-Original-To". This can be useful where you might already
6379 have a "X-Original-To" header from a different application, and you need
6380 preserve it. Also if your backend server doesn't use the "X-Original-To"
6381 header and requires different one.
6382
6383 Sometimes, a same HAProxy instance may be shared between a direct client
6384 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
6385 used to decrypt HTTPS traffic). It is possible to disable the addition of the
6386 header for a known source address or network by adding the "except" keyword
6387 followed by the network address. In this case, any source IP matching the
6388 network will not cause an addition of this header. Most common uses are with
6389 private networks or 127.0.0.1.
6390
6391 This option may be specified either in the frontend or in the backend. If at
6392 least one of them uses it, the header will be added. Note that the backend's
6393 setting of the header subargument takes precedence over the frontend's if
6394 both are defined.
6395
Willy Tarreau55165fe2009-05-10 12:02:55 +02006396 Examples :
6397 # Original Destination address
6398 frontend www
6399 mode http
6400 option originalto except 127.0.0.1
6401
6402 # Those servers want the IP Address in X-Client-Dst
6403 backend www
6404 mode http
6405 option originalto header X-Client-Dst
6406
Willy Tarreau87cf5142011-08-19 22:57:24 +02006407 See also : "option httpclose", "option http-server-close",
6408 "option forceclose"
Willy Tarreau55165fe2009-05-10 12:02:55 +02006409
6410
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006411option persist
6412no option persist
6413 Enable or disable forced persistence on down servers
6414 May be used in sections: defaults | frontend | listen | backend
6415 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006416 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006417
6418 When an HTTP request reaches a backend with a cookie which references a dead
6419 server, by default it is redispatched to another server. It is possible to
6420 force the request to be sent to the dead server first using "option persist"
6421 if absolutely needed. A common use case is when servers are under extreme
6422 load and spend their time flapping. In this case, the users would still be
6423 directed to the server they opened the session on, in the hope they would be
6424 correctly served. It is recommended to use "option redispatch" in conjunction
6425 with this option so that in the event it would not be possible to connect to
6426 the server at all (server definitely dead), the client would finally be
6427 redirected to another valid server.
6428
6429 If this option has been enabled in a "defaults" section, it can be disabled
6430 in a specific instance by prepending the "no" keyword before it.
6431
Willy Tarreau4de91492010-01-22 19:10:05 +01006432 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006433
6434
Willy Tarreau0c122822013-12-15 18:49:01 +01006435option pgsql-check [ user <username> ]
6436 Use PostgreSQL health checks for server testing
6437 May be used in sections : defaults | frontend | listen | backend
6438 yes | no | yes | yes
6439 Arguments :
6440 <username> This is the username which will be used when connecting to
6441 PostgreSQL server.
6442
6443 The check sends a PostgreSQL StartupMessage and waits for either
6444 Authentication request or ErrorResponse message. It is a basic but useful
6445 test which does not produce error nor aborted connect on the server.
6446 This check is identical with the "mysql-check".
6447
6448 See also: "option httpchk"
6449
6450
Willy Tarreau9420b122013-12-15 18:58:25 +01006451option prefer-last-server
6452no option prefer-last-server
6453 Allow multiple load balanced requests to remain on the same server
6454 May be used in sections: defaults | frontend | listen | backend
6455 yes | no | yes | yes
6456 Arguments : none
6457
6458 When the load balancing algorithm in use is not deterministic, and a previous
6459 request was sent to a server to which haproxy still holds a connection, it is
6460 sometimes desirable that subsequent requests on a same session go to the same
6461 server as much as possible. Note that this is different from persistence, as
6462 we only indicate a preference which haproxy tries to apply without any form
6463 of warranty. The real use is for keep-alive connections sent to servers. When
6464 this option is used, haproxy will try to reuse the same connection that is
6465 attached to the server instead of rebalancing to another server, causing a
6466 close of the connection. This can make sense for static file servers. It does
Willy Tarreau068621e2013-12-23 15:11:25 +01006467 not make much sense to use this in combination with hashing algorithms. Note,
6468 haproxy already automatically tries to stick to a server which sends a 401 or
6469 to a proxy which sends a 407 (authentication required). This is mandatory for
6470 use with the broken NTLM authentication challenge, and significantly helps in
6471 troubleshooting some faulty applications. Option prefer-last-server might be
6472 desirable in these environments as well, to avoid redistributing the traffic
6473 after every other response.
Willy Tarreau9420b122013-12-15 18:58:25 +01006474
6475 If this option has been enabled in a "defaults" section, it can be disabled
6476 in a specific instance by prepending the "no" keyword before it.
6477
6478 See also: "option http-keep-alive"
6479
6480
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006481option redispatch
Joseph Lynch726ab712015-05-11 23:25:34 -07006482option redispatch <interval>
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006483no option redispatch
6484 Enable or disable session redistribution in case of connection failure
6485 May be used in sections: defaults | frontend | listen | backend
6486 yes | no | yes | yes
Joseph Lynch726ab712015-05-11 23:25:34 -07006487 Arguments :
6488 <interval> The optional integer value that controls how often redispatches
6489 occur when retrying connections. Positive value P indicates a
6490 redispatch is desired on every Pth retry, and negative value
6491 N indicate a redispath is desired on the Nth retry prior to the
6492 last retry. For example, the default of -1 preserves the
6493 historical behaviour of redispatching on the last retry, a
6494 positive value of 1 would indicate a redispatch on every retry,
6495 and a positive value of 3 would indicate a redispatch on every
6496 third retry. You can disable redispatches with a value of 0.
6497
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006498
6499 In HTTP mode, if a server designated by a cookie is down, clients may
6500 definitely stick to it because they cannot flush the cookie, so they will not
6501 be able to access the service anymore.
6502
6503 Specifying "option redispatch" will allow the proxy to break their
6504 persistence and redistribute them to a working server.
6505
Joseph Lynch726ab712015-05-11 23:25:34 -07006506 It also allows to retry connections to another server in case of multiple
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006507 connection failures. Of course, it requires having "retries" set to a nonzero
6508 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01006509
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006510 This form is the preferred form, which replaces both the "redispatch" and
6511 "redisp" keywords.
6512
6513 If this option has been enabled in a "defaults" section, it can be disabled
6514 in a specific instance by prepending the "no" keyword before it.
6515
Willy Tarreau4de91492010-01-22 19:10:05 +01006516 See also : "redispatch", "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006517
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006518
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02006519option redis-check
6520 Use redis health checks for server testing
6521 May be used in sections : defaults | frontend | listen | backend
6522 yes | no | yes | yes
6523 Arguments : none
6524
6525 It is possible to test that the server correctly talks REDIS protocol instead
6526 of just testing that it accepts the TCP connection. When this option is set,
6527 a PING redis command is sent to the server, and the response is analyzed to
6528 find the "+PONG" response message.
6529
6530 Example :
6531 option redis-check
6532
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03006533 See also : "option httpchk", "option tcp-check", "tcp-check expect"
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02006534
6535
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006536option smtpchk
6537option smtpchk <hello> <domain>
6538 Use SMTP health checks for server testing
6539 May be used in sections : defaults | frontend | listen | backend
6540 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01006541 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006542 <hello> is an optional argument. It is the "hello" command to use. It can
6543 be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other
6544 values will be turned into the default command ("HELO").
6545
6546 <domain> is the domain name to present to the server. It may only be
6547 specified (and is mandatory) if the hello command has been
6548 specified. By default, "localhost" is used.
6549
6550 When "option smtpchk" is set, the health checks will consist in TCP
6551 connections followed by an SMTP command. By default, this command is
6552 "HELO localhost". The server's return code is analyzed and only return codes
6553 starting with a "2" will be considered as valid. All other responses,
6554 including a lack of response will constitute an error and will indicate a
6555 dead server.
6556
6557 This test is meant to be used with SMTP servers or relays. Depending on the
6558 request, it is possible that some servers do not log each connection attempt,
6559 so you may want to experiment to improve the behaviour. Using telnet on port
6560 25 is often easier than adjusting the configuration.
6561
6562 Most often, an incoming SMTP server needs to see the client's IP address for
6563 various purposes, including spam filtering, anti-spoofing and logging. When
6564 possible, it is often wise to masquerade the client's IP address when
6565 connecting to the server using the "usesrc" argument of the "source" keyword,
Willy Tarreau29fbe512015-08-20 19:35:14 +02006566 which requires the transparent proxy feature to be compiled in.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006567
6568 Example :
6569 option smtpchk HELO mydomain.org
6570
6571 See also : "option httpchk", "source"
6572
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006573
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02006574option socket-stats
6575no option socket-stats
6576
6577 Enable or disable collecting & providing separate statistics for each socket.
6578 May be used in sections : defaults | frontend | listen | backend
6579 yes | yes | yes | no
6580
6581 Arguments : none
6582
6583
Willy Tarreauff4f82d2009-02-06 11:28:13 +01006584option splice-auto
6585no option splice-auto
6586 Enable or disable automatic kernel acceleration on sockets in both directions
6587 May be used in sections : defaults | frontend | listen | backend
6588 yes | yes | yes | yes
6589 Arguments : none
6590
6591 When this option is enabled either on a frontend or on a backend, haproxy
6592 will automatically evaluate the opportunity to use kernel tcp splicing to
6593 forward data between the client and the server, in either direction. Haproxy
6594 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006595 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01006596 are not much aggressive in order to limit excessive use of splicing. This
6597 option requires splicing to be enabled at compile time, and may be globally
6598 disabled with the global option "nosplice". Since splice uses pipes, using it
6599 requires that there are enough spare pipes.
6600
6601 Important note: kernel-based TCP splicing is a Linux-specific feature which
6602 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
6603 transfer data between sockets without copying these data to user-space, thus
6604 providing noticeable performance gains and CPU cycles savings. Since many
6605 early implementations are buggy, corrupt data and/or are inefficient, this
6606 feature is not enabled by default, and it should be used with extreme care.
6607 While it is not possible to detect the correctness of an implementation,
6608 2.6.29 is the first version offering a properly working implementation. In
6609 case of doubt, splicing may be globally disabled using the global "nosplice"
6610 keyword.
6611
6612 Example :
6613 option splice-auto
6614
6615 If this option has been enabled in a "defaults" section, it can be disabled
6616 in a specific instance by prepending the "no" keyword before it.
6617
6618 See also : "option splice-request", "option splice-response", and global
6619 options "nosplice" and "maxpipes"
6620
6621
6622option splice-request
6623no option splice-request
6624 Enable or disable automatic kernel acceleration on sockets for requests
6625 May be used in sections : defaults | frontend | listen | backend
6626 yes | yes | yes | yes
6627 Arguments : none
6628
6629 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006630 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01006631 the client to the server. It might still use the recv/send scheme if there
6632 are no spare pipes left. This option requires splicing to be enabled at
6633 compile time, and may be globally disabled with the global option "nosplice".
6634 Since splice uses pipes, using it requires that there are enough spare pipes.
6635
6636 Important note: see "option splice-auto" for usage limitations.
6637
6638 Example :
6639 option splice-request
6640
6641 If this option has been enabled in a "defaults" section, it can be disabled
6642 in a specific instance by prepending the "no" keyword before it.
6643
6644 See also : "option splice-auto", "option splice-response", and global options
6645 "nosplice" and "maxpipes"
6646
6647
6648option splice-response
6649no option splice-response
6650 Enable or disable automatic kernel acceleration on sockets for responses
6651 May be used in sections : defaults | frontend | listen | backend
6652 yes | yes | yes | yes
6653 Arguments : none
6654
6655 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006656 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01006657 the server to the client. It might still use the recv/send scheme if there
6658 are no spare pipes left. This option requires splicing to be enabled at
6659 compile time, and may be globally disabled with the global option "nosplice".
6660 Since splice uses pipes, using it requires that there are enough spare pipes.
6661
6662 Important note: see "option splice-auto" for usage limitations.
6663
6664 Example :
6665 option splice-response
6666
6667 If this option has been enabled in a "defaults" section, it can be disabled
6668 in a specific instance by prepending the "no" keyword before it.
6669
6670 See also : "option splice-auto", "option splice-request", and global options
6671 "nosplice" and "maxpipes"
6672
6673
Christopher Fauletba7bc162016-11-07 21:07:38 +01006674option spop-check
6675 Use SPOP health checks for server testing
6676 May be used in sections : defaults | frontend | listen | backend
6677 no | no | no | yes
6678 Arguments : none
6679
6680 It is possible to test that the server correctly talks SPOP protocol instead
6681 of just testing that it accepts the TCP connection. When this option is set,
6682 a HELLO handshake is performed between HAProxy and the server, and the
6683 response is analyzed to check no error is reported.
6684
6685 Example :
6686 option spop-check
6687
6688 See also : "option httpchk"
6689
6690
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006691option srvtcpka
6692no option srvtcpka
6693 Enable or disable the sending of TCP keepalive packets on the server side
6694 May be used in sections : defaults | frontend | listen | backend
6695 yes | no | yes | yes
6696 Arguments : none
6697
6698 When there is a firewall or any session-aware component between a client and
6699 a server, and when the protocol involves very long sessions with long idle
6700 periods (eg: remote desktops), there is a risk that one of the intermediate
6701 components decides to expire a session which has remained idle for too long.
6702
6703 Enabling socket-level TCP keep-alives makes the system regularly send packets
6704 to the other end of the connection, leaving it active. The delay between
6705 keep-alive probes is controlled by the system only and depends both on the
6706 operating system and its tuning parameters.
6707
6708 It is important to understand that keep-alive packets are neither emitted nor
6709 received at the application level. It is only the network stacks which sees
6710 them. For this reason, even if one side of the proxy already uses keep-alives
6711 to maintain its connection alive, those keep-alive packets will not be
6712 forwarded to the other side of the proxy.
6713
6714 Please note that this has nothing to do with HTTP keep-alive.
6715
6716 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
6717 server side of a connection, which should help when session expirations are
6718 noticed between HAProxy and a server.
6719
6720 If this option has been enabled in a "defaults" section, it can be disabled
6721 in a specific instance by prepending the "no" keyword before it.
6722
6723 See also : "option clitcpka", "option tcpka"
6724
6725
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006726option ssl-hello-chk
6727 Use SSLv3 client hello health checks for server testing
6728 May be used in sections : defaults | frontend | listen | backend
6729 yes | no | yes | yes
6730 Arguments : none
6731
6732 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
6733 possible to test that the server correctly talks SSL instead of just testing
6734 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
6735 SSLv3 client hello messages are sent once the connection is established to
6736 the server, and the response is analyzed to find an SSL server hello message.
6737 The server is considered valid only when the response contains this server
6738 hello message.
6739
6740 All servers tested till there correctly reply to SSLv3 client hello messages,
6741 and most servers tested do not even log the requests containing only hello
6742 messages, which is appreciable.
6743
Willy Tarreau763a95b2012-10-04 23:15:39 +02006744 Note that this check works even when SSL support was not built into haproxy
6745 because it forges the SSL message. When SSL support is available, it is best
6746 to use native SSL health checks instead of this one.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006747
Willy Tarreau763a95b2012-10-04 23:15:39 +02006748 See also: "option httpchk", "check-ssl"
6749
Willy Tarreaua453bdd2008-01-08 19:50:52 +01006750
Willy Tarreaued179852013-12-16 01:07:00 +01006751option tcp-check
6752 Perform health checks using tcp-check send/expect sequences
6753 May be used in sections: defaults | frontend | listen | backend
6754 yes | no | yes | yes
6755
6756 This health check method is intended to be combined with "tcp-check" command
6757 lists in order to support send/expect types of health check sequences.
6758
6759 TCP checks currently support 4 modes of operations :
6760 - no "tcp-check" directive : the health check only consists in a connection
6761 attempt, which remains the default mode.
6762
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006763 - "tcp-check send" or "tcp-check send-binary" only is mentioned : this is
Willy Tarreaued179852013-12-16 01:07:00 +01006764 used to send a string along with a connection opening. With some
6765 protocols, it helps sending a "QUIT" message for example that prevents
6766 the server from logging a connection error for each health check. The
6767 check result will still be based on the ability to open the connection
6768 only.
6769
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006770 - "tcp-check expect" only is mentioned : this is used to test a banner.
Willy Tarreaued179852013-12-16 01:07:00 +01006771 The connection is opened and haproxy waits for the server to present some
6772 contents which must validate some rules. The check result will be based
6773 on the matching between the contents and the rules. This is suited for
6774 POP, IMAP, SMTP, FTP, SSH, TELNET.
6775
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006776 - both "tcp-check send" and "tcp-check expect" are mentioned : this is
Willy Tarreaued179852013-12-16 01:07:00 +01006777 used to test a hello-type protocol. Haproxy sends a message, the server
6778 responds and its response is analysed. the check result will be based on
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006779 the matching between the response contents and the rules. This is often
Willy Tarreaued179852013-12-16 01:07:00 +01006780 suited for protocols which require a binding or a request/response model.
6781 LDAP, MySQL, Redis and SSL are example of such protocols, though they
6782 already all have their dedicated checks with a deeper understanding of
6783 the respective protocols.
6784 In this mode, many questions may be sent and many answers may be
6785 analysed.
6786
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006787 A fifth mode can be used to insert comments in different steps of the
6788 script.
6789
6790 For each tcp-check rule you create, you can add a "comment" directive,
6791 followed by a string. This string will be reported in the log and stderr
6792 in debug mode. It is useful to make user-friendly error reporting.
6793 The "comment" is of course optional.
6794
6795
Willy Tarreaued179852013-12-16 01:07:00 +01006796 Examples :
6797 # perform a POP check (analyse only server's banner)
6798 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006799 tcp-check expect string +OK\ POP3\ ready comment POP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01006800
6801 # perform an IMAP check (analyse only server's banner)
6802 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006803 tcp-check expect string *\ OK\ IMAP4\ ready comment IMAP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01006804
6805 # look for the redis master server after ensuring it speaks well
6806 # redis protocol, then it exits properly.
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006807 # (send a command then analyse the response 3 times)
Willy Tarreaued179852013-12-16 01:07:00 +01006808 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006809 tcp-check comment PING\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01006810 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +02006811 tcp-check expect string +PONG
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006812 tcp-check comment role\ check
Willy Tarreaued179852013-12-16 01:07:00 +01006813 tcp-check send info\ replication\r\n
6814 tcp-check expect string role:master
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006815 tcp-check comment QUIT\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01006816 tcp-check send QUIT\r\n
6817 tcp-check expect string +OK
6818
6819 forge a HTTP request, then analyse the response
6820 (send many headers before analyzing)
6821 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006822 tcp-check comment forge\ and\ send\ HTTP\ request
Willy Tarreaued179852013-12-16 01:07:00 +01006823 tcp-check send HEAD\ /\ HTTP/1.1\r\n
6824 tcp-check send Host:\ www.mydomain.com\r\n
6825 tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n
6826 tcp-check send \r\n
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02006827 tcp-check expect rstring HTTP/1\..\ (2..|3..) comment check\ HTTP\ response
Willy Tarreaued179852013-12-16 01:07:00 +01006828
6829
6830 See also : "tcp-check expect", "tcp-check send"
6831
6832
Willy Tarreau9ea05a72009-06-14 12:07:01 +02006833option tcp-smart-accept
6834no option tcp-smart-accept
6835 Enable or disable the saving of one ACK packet during the accept sequence
6836 May be used in sections : defaults | frontend | listen | backend
6837 yes | yes | yes | no
6838 Arguments : none
6839
6840 When an HTTP connection request comes in, the system acknowledges it on
6841 behalf of HAProxy, then the client immediately sends its request, and the
6842 system acknowledges it too while it is notifying HAProxy about the new
6843 connection. HAProxy then reads the request and responds. This means that we
6844 have one TCP ACK sent by the system for nothing, because the request could
6845 very well be acknowledged by HAProxy when it sends its response.
6846
6847 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
6848 sending this useless ACK on platforms which support it (currently at least
6849 Linux). It must not cause any problem, because the system will send it anyway
6850 after 40 ms if the response takes more time than expected to come.
6851
6852 During complex network debugging sessions, it may be desirable to disable
6853 this optimization because delayed ACKs can make troubleshooting more complex
6854 when trying to identify where packets are delayed. It is then possible to
6855 fall back to normal behaviour by specifying "no option tcp-smart-accept".
6856
6857 It is also possible to force it for non-HTTP proxies by simply specifying
6858 "option tcp-smart-accept". For instance, it can make sense with some services
6859 such as SMTP where the server speaks first.
6860
6861 It is recommended to avoid forcing this option in a defaults section. In case
6862 of doubt, consider setting it back to automatic values by prepending the
6863 "default" keyword before it, or disabling it using the "no" keyword.
6864
Willy Tarreaud88edf22009-06-14 15:48:17 +02006865 See also : "option tcp-smart-connect"
6866
6867
6868option tcp-smart-connect
6869no option tcp-smart-connect
6870 Enable or disable the saving of one ACK packet during the connect sequence
6871 May be used in sections : defaults | frontend | listen | backend
6872 yes | no | yes | yes
6873 Arguments : none
6874
6875 On certain systems (at least Linux), HAProxy can ask the kernel not to
6876 immediately send an empty ACK upon a connection request, but to directly
6877 send the buffer request instead. This saves one packet on the network and
6878 thus boosts performance. It can also be useful for some servers, because they
6879 immediately get the request along with the incoming connection.
6880
6881 This feature is enabled when "option tcp-smart-connect" is set in a backend.
6882 It is not enabled by default because it makes network troubleshooting more
6883 complex.
6884
6885 It only makes sense to enable it with protocols where the client speaks first
6886 such as HTTP. In other situations, if there is no data to send in place of
6887 the ACK, a normal ACK is sent.
6888
6889 If this option has been enabled in a "defaults" section, it can be disabled
6890 in a specific instance by prepending the "no" keyword before it.
6891
6892 See also : "option tcp-smart-accept"
6893
Willy Tarreau9ea05a72009-06-14 12:07:01 +02006894
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006895option tcpka
6896 Enable or disable the sending of TCP keepalive packets on both sides
6897 May be used in sections : defaults | frontend | listen | backend
6898 yes | yes | yes | yes
6899 Arguments : none
6900
6901 When there is a firewall or any session-aware component between a client and
6902 a server, and when the protocol involves very long sessions with long idle
6903 periods (eg: remote desktops), there is a risk that one of the intermediate
6904 components decides to expire a session which has remained idle for too long.
6905
6906 Enabling socket-level TCP keep-alives makes the system regularly send packets
6907 to the other end of the connection, leaving it active. The delay between
6908 keep-alive probes is controlled by the system only and depends both on the
6909 operating system and its tuning parameters.
6910
6911 It is important to understand that keep-alive packets are neither emitted nor
6912 received at the application level. It is only the network stacks which sees
6913 them. For this reason, even if one side of the proxy already uses keep-alives
6914 to maintain its connection alive, those keep-alive packets will not be
6915 forwarded to the other side of the proxy.
6916
6917 Please note that this has nothing to do with HTTP keep-alive.
6918
6919 Using option "tcpka" enables the emission of TCP keep-alive probes on both
6920 the client and server sides of a connection. Note that this is meaningful
6921 only in "defaults" or "listen" sections. If this option is used in a
6922 frontend, only the client side will get keep-alives, and if this option is
6923 used in a backend, only the server side will get keep-alives. For this
6924 reason, it is strongly recommended to explicitly use "option clitcpka" and
6925 "option srvtcpka" when the configuration is split between frontends and
6926 backends.
6927
6928 See also : "option clitcpka", "option srvtcpka"
6929
Willy Tarreau844e3c52008-01-11 16:28:18 +01006930
6931option tcplog
6932 Enable advanced logging of TCP connections with session state and timers
6933 May be used in sections : defaults | frontend | listen | backend
6934 yes | yes | yes | yes
6935 Arguments : none
6936
6937 By default, the log output format is very poor, as it only contains the
6938 source and destination addresses, and the instance name. By specifying
6939 "option tcplog", each log line turns into a much richer format including, but
6940 not limited to, the connection timers, the session status, the connections
6941 numbers, the frontend, backend and server name, and of course the source
6942 address and ports. This option is useful for pure TCP proxies in order to
6943 find which of the client or server disconnects or times out. For normal HTTP
6944 proxies, it's better to use "option httplog" which is even more complete.
6945
6946 This option may be set either in the frontend or the backend.
6947
Guillaume de Lafond29f45602017-03-31 19:52:15 +02006948 "option tcplog" overrides any previous "log-format" directive.
6949
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006950 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006951
6952
Willy Tarreau844e3c52008-01-11 16:28:18 +01006953option transparent
6954no option transparent
6955 Enable client-side transparent proxying
6956 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01006957 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01006958 Arguments : none
6959
6960 This option was introduced in order to provide layer 7 persistence to layer 3
6961 load balancers. The idea is to use the OS's ability to redirect an incoming
6962 connection for a remote address to a local process (here HAProxy), and let
6963 this process know what address was initially requested. When this option is
6964 used, sessions without cookies will be forwarded to the original destination
6965 IP address of the incoming request (which should match that of another
6966 equipment), while requests with cookies will still be forwarded to the
6967 appropriate server.
6968
6969 Note that contrary to a common belief, this option does NOT make HAProxy
6970 present the client's IP to the server when establishing the connection.
6971
Willy Tarreaua1146052011-03-01 09:51:54 +01006972 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006973 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006974
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006975
Simon Horman98637e52014-06-20 12:30:16 +09006976external-check command <command>
6977 Executable to run when performing an external-check
6978 May be used in sections : defaults | frontend | listen | backend
6979 yes | no | yes | yes
6980
6981 Arguments :
6982 <command> is the external command to run
6983
Simon Horman98637e52014-06-20 12:30:16 +09006984 The arguments passed to the to the command are:
6985
Cyril Bonté777be862014-12-02 21:21:35 +01006986 <proxy_address> <proxy_port> <server_address> <server_port>
Simon Horman98637e52014-06-20 12:30:16 +09006987
Cyril Bonté777be862014-12-02 21:21:35 +01006988 The <proxy_address> and <proxy_port> are derived from the first listener
6989 that is either IPv4, IPv6 or a UNIX socket. In the case of a UNIX socket
6990 listener the proxy_address will be the path of the socket and the
6991 <proxy_port> will be the string "NOT_USED". In a backend section, it's not
6992 possible to determine a listener, and both <proxy_address> and <proxy_port>
6993 will have the string value "NOT_USED".
Simon Horman98637e52014-06-20 12:30:16 +09006994
Cyril Bonté72cda2a2014-12-27 22:28:39 +01006995 Some values are also provided through environment variables.
6996
6997 Environment variables :
6998 HAPROXY_PROXY_ADDR The first bind address if available (or empty if not
6999 applicable, for example in a "backend" section).
7000
7001 HAPROXY_PROXY_ID The backend id.
7002
7003 HAPROXY_PROXY_NAME The backend name.
7004
7005 HAPROXY_PROXY_PORT The first bind port if available (or empty if not
7006 applicable, for example in a "backend" section or
7007 for a UNIX socket).
7008
7009 HAPROXY_SERVER_ADDR The server address.
7010
7011 HAPROXY_SERVER_CURCONN The current number of connections on the server.
7012
7013 HAPROXY_SERVER_ID The server id.
7014
7015 HAPROXY_SERVER_MAXCONN The server max connections.
7016
7017 HAPROXY_SERVER_NAME The server name.
7018
7019 HAPROXY_SERVER_PORT The server port if available (or empty for a UNIX
7020 socket).
7021
7022 PATH The PATH environment variable used when executing
7023 the command may be set using "external-check path".
7024
Simon Horman98637e52014-06-20 12:30:16 +09007025 If the command executed and exits with a zero status then the check is
7026 considered to have passed, otherwise the check is considered to have
7027 failed.
7028
7029 Example :
7030 external-check command /bin/true
7031
7032 See also : "external-check", "option external-check", "external-check path"
7033
7034
7035external-check path <path>
7036 The value of the PATH environment variable used when running an external-check
7037 May be used in sections : defaults | frontend | listen | backend
7038 yes | no | yes | yes
7039
7040 Arguments :
7041 <path> is the path used when executing external command to run
7042
7043 The default path is "".
7044
7045 Example :
7046 external-check path "/usr/bin:/bin"
7047
7048 See also : "external-check", "option external-check",
7049 "external-check command"
7050
7051
Emeric Brun647caf12009-06-30 17:57:00 +02007052persist rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007053persist rdp-cookie(<name>)
Emeric Brun647caf12009-06-30 17:57:00 +02007054 Enable RDP cookie-based persistence
7055 May be used in sections : defaults | frontend | listen | backend
7056 yes | no | yes | yes
7057 Arguments :
7058 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02007059 default cookie name "msts" will be used. There currently is no
7060 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02007061
7062 This statement enables persistence based on an RDP cookie. The RDP cookie
7063 contains all information required to find the server in the list of known
7064 servers. So when this option is set in the backend, the request is analysed
7065 and if an RDP cookie is found, it is decoded. If it matches a known server
7066 which is still UP (or if "option persist" is set), then the connection is
7067 forwarded to this server.
7068
7069 Note that this only makes sense in a TCP backend, but for this to work, the
7070 frontend must have waited long enough to ensure that an RDP cookie is present
7071 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007072 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02007073 a single "listen" section.
7074
Willy Tarreau61e28f22010-05-16 22:31:05 +02007075 Also, it is important to understand that the terminal server will emit this
7076 RDP cookie only if it is configured for "token redirection mode", which means
7077 that the "IP address redirection" option is disabled.
7078
Emeric Brun647caf12009-06-30 17:57:00 +02007079 Example :
7080 listen tse-farm
7081 bind :3389
7082 # wait up to 5s for an RDP cookie in the request
7083 tcp-request inspect-delay 5s
7084 tcp-request content accept if RDP_COOKIE
7085 # apply RDP cookie persistence
7086 persist rdp-cookie
7087 # if server is unknown, let's balance on the same cookie.
Cyril Bontédc4d9032012-04-08 21:57:39 +02007088 # alternatively, "balance leastconn" may be useful too.
Emeric Brun647caf12009-06-30 17:57:00 +02007089 balance rdp-cookie
7090 server srv1 1.1.1.1:3389
7091 server srv2 1.1.1.2:3389
7092
Simon Hormanab814e02011-06-24 14:50:20 +09007093 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
7094 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02007095
7096
Willy Tarreau3a7d2072009-03-05 23:48:25 +01007097rate-limit sessions <rate>
7098 Set a limit on the number of new sessions accepted per second on a frontend
7099 May be used in sections : defaults | frontend | listen | backend
7100 yes | yes | yes | no
7101 Arguments :
7102 <rate> The <rate> parameter is an integer designating the maximum number
7103 of new sessions per second to accept on the frontend.
7104
7105 When the frontend reaches the specified number of new sessions per second, it
7106 stops accepting new connections until the rate drops below the limit again.
7107 During this time, the pending sessions will be kept in the socket's backlog
7108 (in system buffers) and haproxy will not even be aware that sessions are
7109 pending. When applying very low limit on a highly loaded service, it may make
7110 sense to increase the socket's backlog using the "backlog" keyword.
7111
7112 This feature is particularly efficient at blocking connection-based attacks
7113 or service abuse on fragile servers. Since the session rate is measured every
7114 millisecond, it is extremely accurate. Also, the limit applies immediately,
7115 no delay is needed at all to detect the threshold.
7116
7117 Example : limit the connection rate on SMTP to 10 per second max
7118 listen smtp
7119 mode tcp
7120 bind :25
7121 rate-limit sessions 10
Panagiotis Panagiotopoulos7282d8e2016-02-11 16:37:15 +02007122 server smtp1 127.0.0.1:1025
Willy Tarreau3a7d2072009-03-05 23:48:25 +01007123
Willy Tarreaua17c2d92011-07-25 08:16:20 +02007124 Note : when the maximum rate is reached, the frontend's status is not changed
7125 but its sockets appear as "WAITING" in the statistics if the
7126 "socket-stats" option is enabled.
Willy Tarreau3a7d2072009-03-05 23:48:25 +01007127
7128 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
7129
7130
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007131redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
7132redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
7133redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007134 Return an HTTP redirection if/unless a condition is matched
7135 May be used in sections : defaults | frontend | listen | backend
7136 no | yes | yes | yes
7137
7138 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01007139 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007140
Willy Tarreau0140f252008-11-19 21:07:09 +01007141 Arguments :
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007142 <loc> With "redirect location", the exact value in <loc> is placed into
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007143 the HTTP "Location" header. When used in an "http-request" rule,
7144 <loc> value follows the log-format rules and can include some
7145 dynamic values (see Custom Log Format in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007146
7147 <pfx> With "redirect prefix", the "Location" header is built from the
7148 concatenation of <pfx> and the complete URI path, including the
7149 query string, unless the "drop-query" option is specified (see
7150 below). As a special case, if <pfx> equals exactly "/", then
7151 nothing is inserted before the original URI. It allows one to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007152 redirect to the same URL (for instance, to insert a cookie). When
7153 used in an "http-request" rule, <pfx> value follows the log-format
7154 rules and can include some dynamic values (see Custom Log Format
7155 in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007156
7157 <sch> With "redirect scheme", then the "Location" header is built by
7158 concatenating <sch> with "://" then the first occurrence of the
7159 "Host" header, and then the URI path, including the query string
7160 unless the "drop-query" option is specified (see below). If no
7161 path is found or if the path is "*", then "/" is used instead. If
7162 no "Host" header is found, then an empty host component will be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007163 returned, which most recent browsers interpret as redirecting to
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007164 the same host. This directive is mostly used to redirect HTTP to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007165 HTTPS. When used in an "http-request" rule, <sch> value follows
7166 the log-format rules and can include some dynamic values (see
7167 Custom Log Format in section 8.2.4).
Willy Tarreau0140f252008-11-19 21:07:09 +01007168
7169 <code> The code is optional. It indicates which type of HTTP redirection
Willy Tarreaub67fdc42013-03-29 19:28:11 +01007170 is desired. Only codes 301, 302, 303, 307 and 308 are supported,
7171 with 302 used by default if no code is specified. 301 means
7172 "Moved permanently", and a browser may cache the Location. 302
Baptiste Assmannea849c02015-08-03 11:42:50 +02007173 means "Moved temporarily" and means that the browser should not
Willy Tarreaub67fdc42013-03-29 19:28:11 +01007174 cache the redirection. 303 is equivalent to 302 except that the
7175 browser will fetch the location with a GET method. 307 is just
7176 like 302 but makes it clear that the same method must be reused.
7177 Likewise, 308 replaces 301 if the same method must be used.
Willy Tarreau0140f252008-11-19 21:07:09 +01007178
7179 <option> There are several options which can be specified to adjust the
7180 expected behaviour of a redirection :
7181
7182 - "drop-query"
7183 When this keyword is used in a prefix-based redirection, then the
7184 location will be set without any possible query-string, which is useful
7185 for directing users to a non-secure page for instance. It has no effect
7186 with a location-type redirect.
7187
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01007188 - "append-slash"
7189 This keyword may be used in conjunction with "drop-query" to redirect
7190 users who use a URL not ending with a '/' to the same one with the '/'.
7191 It can be useful to ensure that search engines will only see one URL.
7192 For this, a return code 301 is preferred.
7193
Willy Tarreau0140f252008-11-19 21:07:09 +01007194 - "set-cookie NAME[=value]"
7195 A "Set-Cookie" header will be added with NAME (and optionally "=value")
7196 to the response. This is sometimes used to indicate that a user has
7197 been seen, for instance to protect against some types of DoS. No other
7198 cookie option is added, so the cookie will be a session cookie. Note
7199 that for a browser, a sole cookie name without an equal sign is
7200 different from a cookie with an equal sign.
7201
7202 - "clear-cookie NAME[=]"
7203 A "Set-Cookie" header will be added with NAME (and optionally "="), but
7204 with the "Max-Age" attribute set to zero. This will tell the browser to
7205 delete this cookie. It is useful for instance on logout pages. It is
7206 important to note that clearing the cookie "NAME" will not remove a
7207 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
7208 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007209
7210 Example: move the login URL only to HTTPS.
7211 acl clear dst_port 80
7212 acl secure dst_port 8080
7213 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01007214 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01007215 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01007216 acl cookie_set hdr_sub(cookie) SEEN=1
7217
7218 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01007219 redirect prefix https://mysite.com if login_page !secure
7220 redirect prefix http://mysite.com drop-query if login_page !uid_given
7221 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01007222 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007223
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01007224 Example: send redirects for request for articles without a '/'.
7225 acl missing_slash path_reg ^/article/[^/]*$
7226 redirect code 301 prefix / drop-query append-slash if missing_slash
7227
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007228 Example: redirect all HTTP traffic to HTTPS when SSL is handled by haproxy.
David BERARDe7153042012-11-03 00:11:31 +01007229 redirect scheme https if !{ ssl_fc }
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007230
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007231 Example: append 'www.' prefix in front of all hosts not having it
Coen Rosdorff596659b2016-04-11 11:33:49 +02007232 http-request redirect code 301 location \
7233 http://www.%[hdr(host)]%[capture.req.uri] \
7234 unless { hdr_beg(host) -i www }
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007235
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007236 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007237
7238
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007239redisp (deprecated)
7240redispatch (deprecated)
7241 Enable or disable session redistribution in case of connection failure
7242 May be used in sections: defaults | frontend | listen | backend
7243 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007244 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007245
7246 In HTTP mode, if a server designated by a cookie is down, clients may
7247 definitely stick to it because they cannot flush the cookie, so they will not
7248 be able to access the service anymore.
7249
7250 Specifying "redispatch" will allow the proxy to break their persistence and
7251 redistribute them to a working server.
7252
7253 It also allows to retry last connection to another server in case of multiple
7254 connection failures. Of course, it requires having "retries" set to a nonzero
7255 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01007256
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007257 This form is deprecated, do not use it in any new configuration, use the new
7258 "option redispatch" instead.
7259
7260 See also : "option redispatch"
7261
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007262
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01007263reqadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01007264 Add a header at the end of the HTTP request
7265 May be used in sections : defaults | frontend | listen | backend
7266 no | yes | yes | yes
7267 Arguments :
7268 <string> is the complete line to be added. Any space or known delimiter
7269 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007270 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01007271
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01007272 <cond> is an optional matching condition built from ACLs. It makes it
7273 possible to ignore this rule when other conditions are not met.
7274
Willy Tarreau303c0352008-01-17 19:01:39 +01007275 A new line consisting in <string> followed by a line feed will be added after
7276 the last header of an HTTP request.
7277
7278 Header transformations only apply to traffic which passes through HAProxy,
7279 and not to traffic generated by HAProxy, such as health-checks or error
7280 responses.
7281
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01007282 Example : add "X-Proto: SSL" to requests coming via port 81
7283 acl is-ssl dst_port 81
7284 reqadd X-Proto:\ SSL if is-ssl
7285
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007286 See also: "rspadd", "http-request", section 6 about HTTP header manipulation,
7287 and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007288
7289
Willy Tarreau5321c422010-01-28 20:35:13 +01007290reqallow <search> [{if | unless} <cond>]
7291reqiallow <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007292 Definitely allow an HTTP request if a line matches a regular expression
7293 May be used in sections : defaults | frontend | listen | backend
7294 no | yes | yes | yes
7295 Arguments :
7296 <search> is the regular expression applied to HTTP headers and to the
7297 request line. This is an extended regular expression. Parenthesis
7298 grouping is supported and no preliminary backslash is required.
7299 Any space or known delimiter must be escaped using a backslash
7300 ('\'). The pattern applies to a full line at a time. The
7301 "reqallow" keyword strictly matches case while "reqiallow"
7302 ignores case.
7303
Willy Tarreau5321c422010-01-28 20:35:13 +01007304 <cond> is an optional matching condition built from ACLs. It makes it
7305 possible to ignore this rule when other conditions are not met.
7306
Willy Tarreau303c0352008-01-17 19:01:39 +01007307 A request containing any line which matches extended regular expression
7308 <search> will mark the request as allowed, even if any later test would
7309 result in a deny. The test applies both to the request line and to request
7310 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01007311 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01007312
7313 It is easier, faster and more powerful to use ACLs to write access policies.
7314 Reqdeny, reqallow and reqpass should be avoided in new designs.
7315
7316 Example :
7317 # allow www.* but refuse *.local
7318 reqiallow ^Host:\ www\.
7319 reqideny ^Host:\ .*\.local
7320
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007321 See also: "reqdeny", "block", "http-request", section 6 about HTTP header
7322 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007323
7324
Willy Tarreau5321c422010-01-28 20:35:13 +01007325reqdel <search> [{if | unless} <cond>]
7326reqidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007327 Delete all headers matching a regular expression in an HTTP request
7328 May be used in sections : defaults | frontend | listen | backend
7329 no | yes | yes | yes
7330 Arguments :
7331 <search> is the regular expression applied to HTTP headers and to the
7332 request line. This is an extended regular expression. Parenthesis
7333 grouping is supported and no preliminary backslash is required.
7334 Any space or known delimiter must be escaped using a backslash
7335 ('\'). The pattern applies to a full line at a time. The "reqdel"
7336 keyword strictly matches case while "reqidel" ignores case.
7337
Willy Tarreau5321c422010-01-28 20:35:13 +01007338 <cond> is an optional matching condition built from ACLs. It makes it
7339 possible to ignore this rule when other conditions are not met.
7340
Willy Tarreau303c0352008-01-17 19:01:39 +01007341 Any header line matching extended regular expression <search> in the request
7342 will be completely deleted. Most common use of this is to remove unwanted
7343 and/or dangerous headers or cookies from a request before passing it to the
7344 next servers.
7345
7346 Header transformations only apply to traffic which passes through HAProxy,
7347 and not to traffic generated by HAProxy, such as health-checks or error
7348 responses. Keep in mind that header names are not case-sensitive.
7349
7350 Example :
7351 # remove X-Forwarded-For header and SERVER cookie
7352 reqidel ^X-Forwarded-For:.*
7353 reqidel ^Cookie:.*SERVER=
7354
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007355 See also: "reqadd", "reqrep", "rspdel", "http-request", section 6 about
7356 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007357
7358
Willy Tarreau5321c422010-01-28 20:35:13 +01007359reqdeny <search> [{if | unless} <cond>]
7360reqideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007361 Deny an HTTP request if a line matches a regular expression
7362 May be used in sections : defaults | frontend | listen | backend
7363 no | yes | yes | yes
7364 Arguments :
7365 <search> is the regular expression applied to HTTP headers and to the
7366 request line. This is an extended regular expression. Parenthesis
7367 grouping is supported and no preliminary backslash is required.
7368 Any space or known delimiter must be escaped using a backslash
7369 ('\'). The pattern applies to a full line at a time. The
7370 "reqdeny" keyword strictly matches case while "reqideny" ignores
7371 case.
7372
Willy Tarreau5321c422010-01-28 20:35:13 +01007373 <cond> is an optional matching condition built from ACLs. It makes it
7374 possible to ignore this rule when other conditions are not met.
7375
Willy Tarreau303c0352008-01-17 19:01:39 +01007376 A request containing any line which matches extended regular expression
7377 <search> will mark the request as denied, even if any later test would
7378 result in an allow. The test applies both to the request line and to request
7379 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01007380 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01007381
Willy Tarreauced27012008-01-17 20:35:34 +01007382 A denied request will generate an "HTTP 403 forbidden" response once the
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01007383 complete request has been parsed. This is consistent with what is practiced
Willy Tarreaud72758d2010-01-12 10:42:19 +01007384 using ACLs.
Willy Tarreauced27012008-01-17 20:35:34 +01007385
Willy Tarreau303c0352008-01-17 19:01:39 +01007386 It is easier, faster and more powerful to use ACLs to write access policies.
7387 Reqdeny, reqallow and reqpass should be avoided in new designs.
7388
7389 Example :
7390 # refuse *.local, then allow www.*
7391 reqideny ^Host:\ .*\.local
7392 reqiallow ^Host:\ www\.
7393
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007394 See also: "reqallow", "rspdeny", "block", "http-request", section 6 about
7395 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007396
7397
Willy Tarreau5321c422010-01-28 20:35:13 +01007398reqpass <search> [{if | unless} <cond>]
7399reqipass <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007400 Ignore any HTTP request line matching a regular expression in next rules
7401 May be used in sections : defaults | frontend | listen | backend
7402 no | yes | yes | yes
7403 Arguments :
7404 <search> is the regular expression applied to HTTP headers and to the
7405 request line. This is an extended regular expression. Parenthesis
7406 grouping is supported and no preliminary backslash is required.
7407 Any space or known delimiter must be escaped using a backslash
7408 ('\'). The pattern applies to a full line at a time. The
7409 "reqpass" keyword strictly matches case while "reqipass" ignores
7410 case.
7411
Willy Tarreau5321c422010-01-28 20:35:13 +01007412 <cond> is an optional matching condition built from ACLs. It makes it
7413 possible to ignore this rule when other conditions are not met.
7414
Willy Tarreau303c0352008-01-17 19:01:39 +01007415 A request containing any line which matches extended regular expression
7416 <search> will skip next rules, without assigning any deny or allow verdict.
7417 The test applies both to the request line and to request headers. Keep in
7418 mind that URLs in request line are case-sensitive while header names are not.
7419
7420 It is easier, faster and more powerful to use ACLs to write access policies.
7421 Reqdeny, reqallow and reqpass should be avoided in new designs.
7422
7423 Example :
7424 # refuse *.local, then allow www.*, but ignore "www.private.local"
7425 reqipass ^Host:\ www.private\.local
7426 reqideny ^Host:\ .*\.local
7427 reqiallow ^Host:\ www\.
7428
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007429 See also: "reqallow", "reqdeny", "block", "http-request", section 6 about
7430 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007431
7432
Willy Tarreau5321c422010-01-28 20:35:13 +01007433reqrep <search> <string> [{if | unless} <cond>]
7434reqirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007435 Replace a regular expression with a string in an HTTP request line
7436 May be used in sections : defaults | frontend | listen | backend
7437 no | yes | yes | yes
7438 Arguments :
7439 <search> is the regular expression applied to HTTP headers and to the
7440 request line. This is an extended regular expression. Parenthesis
7441 grouping is supported and no preliminary backslash is required.
7442 Any space or known delimiter must be escaped using a backslash
7443 ('\'). The pattern applies to a full line at a time. The "reqrep"
7444 keyword strictly matches case while "reqirep" ignores case.
7445
7446 <string> is the complete line to be added. Any space or known delimiter
7447 must be escaped using a backslash ('\'). References to matched
7448 pattern groups are possible using the common \N form, with N
7449 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007450 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01007451
Willy Tarreau5321c422010-01-28 20:35:13 +01007452 <cond> is an optional matching condition built from ACLs. It makes it
7453 possible to ignore this rule when other conditions are not met.
7454
Willy Tarreau303c0352008-01-17 19:01:39 +01007455 Any line matching extended regular expression <search> in the request (both
7456 the request line and header lines) will be completely replaced with <string>.
7457 Most common use of this is to rewrite URLs or domain names in "Host" headers.
7458
7459 Header transformations only apply to traffic which passes through HAProxy,
7460 and not to traffic generated by HAProxy, such as health-checks or error
7461 responses. Note that for increased readability, it is suggested to add enough
7462 spaces between the request and the response. Keep in mind that URLs in
7463 request line are case-sensitive while header names are not.
7464
7465 Example :
7466 # replace "/static/" with "/" at the beginning of any request path.
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04007467 reqrep ^([^\ :]*)\ /static/(.*) \1\ /\2
Willy Tarreau303c0352008-01-17 19:01:39 +01007468 # replace "www.mydomain.com" with "www" in the host name.
7469 reqirep ^Host:\ www.mydomain.com Host:\ www
7470
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007471 See also: "reqadd", "reqdel", "rsprep", "tune.bufsize", "http-request",
7472 section 6 about HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007473
7474
Willy Tarreau5321c422010-01-28 20:35:13 +01007475reqtarpit <search> [{if | unless} <cond>]
7476reqitarpit <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007477 Tarpit an HTTP request containing a line matching a regular expression
7478 May be used in sections : defaults | frontend | listen | backend
7479 no | yes | yes | yes
7480 Arguments :
7481 <search> is the regular expression applied to HTTP headers and to the
7482 request line. This is an extended regular expression. Parenthesis
7483 grouping is supported and no preliminary backslash is required.
7484 Any space or known delimiter must be escaped using a backslash
7485 ('\'). The pattern applies to a full line at a time. The
7486 "reqtarpit" keyword strictly matches case while "reqitarpit"
7487 ignores case.
7488
Willy Tarreau5321c422010-01-28 20:35:13 +01007489 <cond> is an optional matching condition built from ACLs. It makes it
7490 possible to ignore this rule when other conditions are not met.
7491
Willy Tarreau303c0352008-01-17 19:01:39 +01007492 A request containing any line which matches extended regular expression
7493 <search> will be tarpitted, which means that it will connect to nowhere, will
Willy Tarreauced27012008-01-17 20:35:34 +01007494 be kept open for a pre-defined time, then will return an HTTP error 500 so
7495 that the attacker does not suspect it has been tarpitted. The status 500 will
7496 be reported in the logs, but the completion flags will indicate "PT". The
Willy Tarreau303c0352008-01-17 19:01:39 +01007497 delay is defined by "timeout tarpit", or "timeout connect" if the former is
7498 not set.
7499
7500 The goal of the tarpit is to slow down robots attacking servers with
7501 identifiable requests. Many robots limit their outgoing number of connections
7502 and stay connected waiting for a reply which can take several minutes to
7503 come. Depending on the environment and attack, it may be particularly
7504 efficient at reducing the load on the network and firewalls.
7505
Willy Tarreau5321c422010-01-28 20:35:13 +01007506 Examples :
Willy Tarreau303c0352008-01-17 19:01:39 +01007507 # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but
7508 # block all others.
7509 reqipass ^User-Agent:\.*(Mozilla|MSIE)
7510 reqitarpit ^User-Agent:
7511
Willy Tarreau5321c422010-01-28 20:35:13 +01007512 # block bad guys
7513 acl badguys src 10.1.0.3 172.16.13.20/28
7514 reqitarpit . if badguys
7515
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007516 See also: "reqallow", "reqdeny", "reqpass", "http-request", section 6
7517 about HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007518
7519
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02007520retries <value>
7521 Set the number of retries to perform on a server after a connection failure
7522 May be used in sections: defaults | frontend | listen | backend
7523 yes | no | yes | yes
7524 Arguments :
7525 <value> is the number of times a connection attempt should be retried on
7526 a server when a connection either is refused or times out. The
7527 default value is 3.
7528
7529 It is important to understand that this value applies to the number of
7530 connection attempts, not full requests. When a connection has effectively
7531 been established to a server, there will be no more retry.
7532
7533 In order to avoid immediate reconnections to a server which is restarting,
Joseph Lynch726ab712015-05-11 23:25:34 -07007534 a turn-around timer of min("timeout connect", one second) is applied before
7535 a retry occurs.
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02007536
7537 When "option redispatch" is set, the last retry may be performed on another
7538 server even if a cookie references a different server.
7539
7540 See also : "option redispatch"
7541
7542
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007543rspadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01007544 Add a header at the end of the HTTP response
7545 May be used in sections : defaults | frontend | listen | backend
7546 no | yes | yes | yes
7547 Arguments :
7548 <string> is the complete line to be added. Any space or known delimiter
7549 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007550 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01007551
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007552 <cond> is an optional matching condition built from ACLs. It makes it
7553 possible to ignore this rule when other conditions are not met.
7554
Willy Tarreau303c0352008-01-17 19:01:39 +01007555 A new line consisting in <string> followed by a line feed will be added after
7556 the last header of an HTTP response.
7557
7558 Header transformations only apply to traffic which passes through HAProxy,
7559 and not to traffic generated by HAProxy, such as health-checks or error
7560 responses.
7561
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007562 See also: "rspdel" "reqadd", "http-response", section 6 about HTTP header
7563 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007564
7565
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007566rspdel <search> [{if | unless} <cond>]
7567rspidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007568 Delete all headers matching a regular expression in an HTTP response
7569 May be used in sections : defaults | frontend | listen | backend
7570 no | yes | yes | yes
7571 Arguments :
7572 <search> is the regular expression applied to HTTP headers and to the
7573 response line. This is an extended regular expression, so
7574 parenthesis grouping is supported and no preliminary backslash
7575 is required. Any space or known delimiter must be escaped using
7576 a backslash ('\'). The pattern applies to a full line at a time.
7577 The "rspdel" keyword strictly matches case while "rspidel"
7578 ignores case.
7579
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007580 <cond> is an optional matching condition built from ACLs. It makes it
7581 possible to ignore this rule when other conditions are not met.
7582
Willy Tarreau303c0352008-01-17 19:01:39 +01007583 Any header line matching extended regular expression <search> in the response
7584 will be completely deleted. Most common use of this is to remove unwanted
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02007585 and/or sensitive headers or cookies from a response before passing it to the
Willy Tarreau303c0352008-01-17 19:01:39 +01007586 client.
7587
7588 Header transformations only apply to traffic which passes through HAProxy,
7589 and not to traffic generated by HAProxy, such as health-checks or error
7590 responses. Keep in mind that header names are not case-sensitive.
7591
7592 Example :
7593 # remove the Server header from responses
Willy Tarreau5e80e022013-05-25 08:31:25 +02007594 rspidel ^Server:.*
Willy Tarreau303c0352008-01-17 19:01:39 +01007595
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007596 See also: "rspadd", "rsprep", "reqdel", "http-response", section 6 about
7597 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007598
7599
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007600rspdeny <search> [{if | unless} <cond>]
7601rspideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007602 Block an HTTP response if a line matches a regular expression
7603 May be used in sections : defaults | frontend | listen | backend
7604 no | yes | yes | yes
7605 Arguments :
7606 <search> is the regular expression applied to HTTP headers and to the
7607 response line. This is an extended regular expression, so
7608 parenthesis grouping is supported and no preliminary backslash
7609 is required. Any space or known delimiter must be escaped using
7610 a backslash ('\'). The pattern applies to a full line at a time.
7611 The "rspdeny" keyword strictly matches case while "rspideny"
7612 ignores case.
7613
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007614 <cond> is an optional matching condition built from ACLs. It makes it
7615 possible to ignore this rule when other conditions are not met.
7616
Willy Tarreau303c0352008-01-17 19:01:39 +01007617 A response containing any line which matches extended regular expression
7618 <search> will mark the request as denied. The test applies both to the
7619 response line and to response headers. Keep in mind that header names are not
7620 case-sensitive.
7621
7622 Main use of this keyword is to prevent sensitive information leak and to
Willy Tarreauced27012008-01-17 20:35:34 +01007623 block the response before it reaches the client. If a response is denied, it
7624 will be replaced with an HTTP 502 error so that the client never retrieves
7625 any sensitive data.
Willy Tarreau303c0352008-01-17 19:01:39 +01007626
7627 It is easier, faster and more powerful to use ACLs to write access policies.
7628 Rspdeny should be avoided in new designs.
7629
7630 Example :
7631 # Ensure that no content type matching ms-word will leak
7632 rspideny ^Content-type:\.*/ms-word
7633
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007634 See also: "reqdeny", "acl", "block", "http-response", section 6 about
7635 HTTP header manipulation and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007636
7637
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007638rsprep <search> <string> [{if | unless} <cond>]
7639rspirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01007640 Replace a regular expression with a string in an HTTP response line
7641 May be used in sections : defaults | frontend | listen | backend
7642 no | yes | yes | yes
7643 Arguments :
7644 <search> is the regular expression applied to HTTP headers and to the
7645 response line. This is an extended regular expression, so
7646 parenthesis grouping is supported and no preliminary backslash
7647 is required. Any space or known delimiter must be escaped using
7648 a backslash ('\'). The pattern applies to a full line at a time.
7649 The "rsprep" keyword strictly matches case while "rspirep"
7650 ignores case.
7651
7652 <string> is the complete line to be added. Any space or known delimiter
7653 must be escaped using a backslash ('\'). References to matched
7654 pattern groups are possible using the common \N form, with N
7655 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007656 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01007657
Willy Tarreaufdb563c2010-01-31 15:43:27 +01007658 <cond> is an optional matching condition built from ACLs. It makes it
7659 possible to ignore this rule when other conditions are not met.
7660
Willy Tarreau303c0352008-01-17 19:01:39 +01007661 Any line matching extended regular expression <search> in the response (both
7662 the response line and header lines) will be completely replaced with
7663 <string>. Most common use of this is to rewrite Location headers.
7664
7665 Header transformations only apply to traffic which passes through HAProxy,
7666 and not to traffic generated by HAProxy, such as health-checks or error
7667 responses. Note that for increased readability, it is suggested to add enough
7668 spaces between the request and the response. Keep in mind that header names
7669 are not case-sensitive.
7670
7671 Example :
7672 # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com"
7673 rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com
7674
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08007675 See also: "rspadd", "rspdel", "reqrep", "http-response", section 6 about
7676 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01007677
7678
David du Colombier486df472011-03-17 10:40:26 +01007679server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007680 Declare a server in a backend
7681 May be used in sections : defaults | frontend | listen | backend
7682 no | no | yes | yes
7683 Arguments :
7684 <name> is the internal name assigned to this server. This name will
Cyril Bonté941a0c62012-10-15 19:44:24 +02007685 appear in logs and alerts. If "http-send-name-header" is
Mark Lamourinec2247f02012-01-04 13:02:01 -05007686 set, it will be added to the request header sent to the server.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007687
David du Colombier486df472011-03-17 10:40:26 +01007688 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
7689 resolvable hostname is supported, but this name will be resolved
7690 during start-up. Address "0.0.0.0" or "*" has a special meaning.
7691 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +02007692 address as the one from the client connection. This is useful in
7693 transparent proxy architectures where the client's connection is
7694 intercepted and haproxy must forward to the original destination
7695 address. This is more or less what the "transparent" keyword does
7696 except that with a server it's possible to limit concurrency and
Willy Tarreau24709282013-03-10 21:32:12 +01007697 to report statistics. Optionally, an address family prefix may be
7698 used before the address to force the family regardless of the
7699 address format, which can be useful to specify a path to a unix
7700 socket with no slash ('/'). Currently supported prefixes are :
7701 - 'ipv4@' -> address is always IPv4
7702 - 'ipv6@' -> address is always IPv6
7703 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +02007704 - 'abns@' -> address is in abstract namespace (Linux only)
William Lallemandb2f07452015-05-12 14:27:13 +02007705 You may want to reference some environment variables in the
7706 address parameter, see section 2.3 about environment
Willy Tarreau6a031d12016-11-07 19:42:35 +01007707 variables. The "init-addr" setting can be used to modify the way
7708 IP addresses should be resolved upon startup.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007709
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007710 <port> is an optional port specification. If set, all connections will
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007711 be sent to this port. If unset, the same port the client
7712 connected to will be used. The port may also be prefixed by a "+"
7713 or a "-". In this case, the server's port will be determined by
7714 adding this value to the client's port.
7715
7716 <param*> is a list of parameters for this server. The "server" keywords
7717 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007718 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007719
7720 Examples :
7721 server first 10.1.1.1:1080 cookie first check inter 1000
7722 server second 10.1.1.2:1080 cookie second check inter 1000
Willy Tarreau24709282013-03-10 21:32:12 +01007723 server transp ipv4@
William Lallemandb2f07452015-05-12 14:27:13 +02007724 server backup "${SRV_BACKUP}:1080" backup
7725 server www1_dc1 "${LAN_DC1}.101:80"
7726 server www1_dc2 "${LAN_DC2}.101:80"
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007727
Willy Tarreau55dcaf62015-09-27 15:03:15 +02007728 Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
7729 sun_path length is used for the address length. Some other programs
7730 such as socat use the string length only by default. Pass the option
7731 ",unix-tightsocklen=0" to any abstract socket definition in socat to
7732 make it compatible with HAProxy's.
7733
Mark Lamourinec2247f02012-01-04 13:02:01 -05007734 See also: "default-server", "http-send-name-header" and section 5 about
7735 server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007736
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02007737server-state-file-name [<file>]
7738 Set the server state file to read, load and apply to servers available in
7739 this backend. It only applies when the directive "load-server-state-from-file"
7740 is set to "local". When <file> is not provided or if this directive is not
7741 set, then backend name is used. If <file> starts with a slash '/', then it is
7742 considered as an absolute path. Otherwise, <file> is concatenated to the
7743 global directive "server-state-file-base".
7744
7745 Example: the minimal configuration below would make HAProxy look for the
7746 state server file '/etc/haproxy/states/bk':
7747
7748 global
7749 server-state-file-base /etc/haproxy/states
7750
7751 backend bk
7752 load-server-state-from-file
7753
7754 See also: "server-state-file-base", "load-server-state-from-file", and
7755 "show servers state"
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007756
Frédéric Lécaillecb4502e2017-04-20 13:36:25 +02007757server-template <prefix> <num | range> <fqdn>[:<port>] [params*]
7758 Set a template to initialize servers with shared parameters.
7759 The names of these servers are built from <prefix> and <num | range> parameters.
7760 May be used in sections : defaults | frontend | listen | backend
7761 no | no | yes | yes
7762
7763 Arguments:
7764 <prefix> A prefix for the server names to be built.
7765
7766 <num | range>
7767 If <num> is provided, this template initializes <num> servers
7768 with 1 up to <num> as server name suffixes. A range of numbers
7769 <num_low>-<num_high> may also be used to use <num_low> up to
7770 <num_high> as server name suffixes.
7771
7772 <fqdn> A FQDN for all the servers this template initializes.
7773
7774 <port> Same meaning as "server" <port> argument (see "server" keyword).
7775
7776 <params*>
7777 Remaining server parameters among all those supported by "server"
7778 keyword.
7779
7780 Examples:
7781 # Initializes 3 servers with srv1, srv2 and srv3 as names,
7782 # google.com as FQDN, and health-check enabled.
7783 server-template srv 1-3 google.com:80 check
7784
7785 # or
7786 server-template srv 3 google.com:80 check
7787
7788 # would be equivalent to:
7789 server srv1 google.com:80 check
7790 server srv2 google.com:80 check
7791 server srv3 google.com:80 check
7792
7793
7794
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007795source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02007796source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01007797source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007798 Set the source address for outgoing connections
7799 May be used in sections : defaults | frontend | listen | backend
7800 yes | no | yes | yes
7801 Arguments :
7802 <addr> is the IPv4 address HAProxy will bind to before connecting to a
7803 server. This address is also used as a source for health checks.
Willy Tarreau24709282013-03-10 21:32:12 +01007804
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007805 The default value of 0.0.0.0 means that the system will select
Willy Tarreau24709282013-03-10 21:32:12 +01007806 the most appropriate address to reach its destination. Optionally
7807 an address family prefix may be used before the address to force
7808 the family regardless of the address format, which can be useful
7809 to specify a path to a unix socket with no slash ('/'). Currently
7810 supported prefixes are :
7811 - 'ipv4@' -> address is always IPv4
7812 - 'ipv6@' -> address is always IPv6
7813 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +02007814 - 'abns@' -> address is in abstract namespace (Linux only)
Cyril Bonté307ee1e2015-09-28 23:16:06 +02007815 You may want to reference some environment variables in the
7816 address parameter, see section 2.3 about environment variables.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007817
7818 <port> is an optional port. It is normally not needed but may be useful
7819 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02007820 the system will select a free port. Note that port ranges are not
7821 supported in the backend. If you want to force port ranges, you
7822 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007823
7824 <addr2> is the IP address to present to the server when connections are
7825 forwarded in full transparent proxy mode. This is currently only
7826 supported on some patched Linux kernels. When this address is
7827 specified, clients connecting to the server will be presented
7828 with this address, while health checks will still use the address
7829 <addr>.
7830
7831 <port2> is the optional port to present to the server when connections
7832 are forwarded in full transparent proxy mode (see <addr2> above).
7833 The default value of zero means the system will select a free
7834 port.
7835
Willy Tarreaubce70882009-09-07 11:51:47 +02007836 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
7837 This is the name of a comma-separated header list which can
7838 contain multiple IP addresses. By default, the last occurrence is
7839 used. This is designed to work with the X-Forwarded-For header
Baptiste Assmannea3e73b2013-02-02 23:47:49 +01007840 and to automatically bind to the client's IP address as seen
Willy Tarreaubce70882009-09-07 11:51:47 +02007841 by previous proxy, typically Stunnel. In order to use another
7842 occurrence from the last one, please see the <occ> parameter
7843 below. When the header (or occurrence) is not found, no binding
7844 is performed so that the proxy's default IP address is used. Also
7845 keep in mind that the header name is case insensitive, as for any
7846 HTTP header.
7847
7848 <occ> is the occurrence number of a value to be used in a multi-value
7849 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04007850 in order to specify which occurrence to use for the source IP
Willy Tarreaubce70882009-09-07 11:51:47 +02007851 address. Positive values indicate a position from the first
7852 occurrence, 1 being the first one. Negative values indicate
7853 positions relative to the last one, -1 being the last one. This
7854 is helpful for situations where an X-Forwarded-For header is set
7855 at the entry point of an infrastructure and must be used several
7856 proxy layers away. When this value is not specified, -1 is
7857 assumed. Passing a zero here disables the feature.
7858
Willy Tarreaud53f96b2009-02-04 18:46:54 +01007859 <name> is an optional interface name to which to bind to for outgoing
7860 traffic. On systems supporting this features (currently, only
7861 Linux), this allows one to bind all traffic to the server to
7862 this interface even if it is not the one the system would select
7863 based on routing tables. This should be used with extreme care.
7864 Note that using this option requires root privileges.
7865
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007866 The "source" keyword is useful in complex environments where a specific
7867 address only is allowed to connect to the servers. It may be needed when a
7868 private address must be used through a public gateway for instance, and it is
7869 known that the system cannot determine the adequate source address by itself.
7870
7871 An extension which is available on certain patched Linux kernels may be used
7872 through the "usesrc" optional keyword. It makes it possible to connect to the
7873 servers with an IP address which does not belong to the system itself. This
7874 is called "full transparent proxy mode". For this to work, the destination
7875 servers have to route their traffic back to this address through the machine
7876 running HAProxy, and IP forwarding must generally be enabled on this machine.
7877
7878 In this "full transparent proxy" mode, it is possible to force a specific IP
7879 address to be presented to the servers. This is not much used in fact. A more
7880 common use is to tell HAProxy to present the client's IP address. For this,
7881 there are two methods :
7882
7883 - present the client's IP and port addresses. This is the most transparent
7884 mode, but it can cause problems when IP connection tracking is enabled on
7885 the machine, because a same connection may be seen twice with different
7886 states. However, this solution presents the huge advantage of not
7887 limiting the system to the 64k outgoing address+port couples, because all
7888 of the client ranges may be used.
7889
7890 - present only the client's IP address and select a spare port. This
7891 solution is still quite elegant but slightly less transparent (downstream
7892 firewalls logs will not match upstream's). It also presents the downside
7893 of limiting the number of concurrent connections to the usual 64k ports.
7894 However, since the upstream and downstream ports are different, local IP
7895 connection tracking on the machine will not be upset by the reuse of the
7896 same session.
7897
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007898 This option sets the default source for all servers in the backend. It may
7899 also be specified in a "defaults" section. Finer source address specification
7900 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007901 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007902
Baptiste Assmann91bd3372015-07-17 21:59:42 +02007903 In order to work, "usesrc" requires root privileges.
7904
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007905 Examples :
7906 backend private
7907 # Connect to the servers using our 192.168.1.200 source address
7908 source 192.168.1.200
7909
7910 backend transparent_ssl1
7911 # Connect to the SSL farm from the client's source address
7912 source 192.168.1.200 usesrc clientip
7913
7914 backend transparent_ssl2
7915 # Connect to the SSL farm from the client's source address and port
7916 # not recommended if IP conntrack is present on the local machine.
7917 source 192.168.1.200 usesrc client
7918
7919 backend transparent_ssl3
7920 # Connect to the SSL farm from the client's source address. It
7921 # is more conntrack-friendly.
7922 source 192.168.1.200 usesrc clientip
7923
7924 backend transparent_smtp
7925 # Connect to the SMTP farm from the client's source address/port
7926 # with Tproxy version 4.
7927 source 0.0.0.0 usesrc clientip
7928
Willy Tarreaubce70882009-09-07 11:51:47 +02007929 backend transparent_http
7930 # Connect to the servers using the client's IP as seen by previous
7931 # proxy.
7932 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
7933
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007934 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007935 the Linux kernel on www.balabit.com, the "bind" keyword.
7936
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007937
Willy Tarreau844e3c52008-01-11 16:28:18 +01007938srvtimeout <timeout> (deprecated)
7939 Set the maximum inactivity time on the server side.
7940 May be used in sections : defaults | frontend | listen | backend
7941 yes | no | yes | yes
7942 Arguments :
7943 <timeout> is the timeout value specified in milliseconds by default, but
7944 can be in any other unit if the number is suffixed by the unit,
7945 as explained at the top of this document.
7946
7947 The inactivity timeout applies when the server is expected to acknowledge or
7948 send data. In HTTP mode, this timeout is particularly important to consider
7949 during the first phase of the server's response, when it has to send the
7950 headers, as it directly represents the server's processing time for the
7951 request. To find out what value to put there, it's often good to start with
7952 what would be considered as unacceptable response times, then check the logs
7953 to observe the response time distribution, and adjust the value accordingly.
7954
7955 The value is specified in milliseconds by default, but can be in any other
7956 unit if the number is suffixed by the unit, as specified at the top of this
7957 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
7958 recommended that the client timeout remains equal to the server timeout in
7959 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01007960 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01007961 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreaud72758d2010-01-12 10:42:19 +01007962 seconds (eg: 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01007963
7964 This parameter is specific to backends, but can be specified once for all in
7965 "defaults" sections. This is in fact one of the easiest solutions not to
7966 forget about it. An unspecified timeout results in an infinite timeout, which
7967 is not recommended. Such a usage is accepted and works but reports a warning
7968 during startup because it may results in accumulation of expired sessions in
7969 the system if the system's timeouts are not configured either.
7970
7971 This parameter is provided for compatibility but is currently deprecated.
7972 Please use "timeout server" instead.
7973
Willy Tarreauce887fd2012-05-12 12:50:00 +02007974 See also : "timeout server", "timeout tunnel", "timeout client" and
7975 "clitimeout".
Willy Tarreau844e3c52008-01-11 16:28:18 +01007976
7977
Cyril Bonté66c327d2010-10-12 00:14:37 +02007978stats admin { if | unless } <cond>
7979 Enable statistics admin level if/unless a condition is matched
7980 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02007981 no | yes | yes | yes
Cyril Bonté66c327d2010-10-12 00:14:37 +02007982
7983 This statement enables the statistics admin level if/unless a condition is
7984 matched.
7985
7986 The admin level allows to enable/disable servers from the web interface. By
7987 default, statistics page is read-only for security reasons.
7988
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01007989 Note : Consider not using this feature in multi-process mode (nbproc > 1)
7990 unless you know what you do : memory is not shared between the
7991 processes, which can result in random behaviours.
7992
Cyril Bonté23b39d92011-02-10 22:54:44 +01007993 Currently, the POST request is limited to the buffer size minus the reserved
7994 buffer space, which means that if the list of servers is too long, the
7995 request won't be processed. It is recommended to alter few servers at a
7996 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02007997
7998 Example :
7999 # statistics admin level only for localhost
8000 backend stats_localhost
8001 stats enable
8002 stats admin if LOCALHOST
8003
8004 Example :
8005 # statistics admin level always enabled because of the authentication
8006 backend stats_auth
8007 stats enable
8008 stats auth admin:AdMiN123
8009 stats admin if TRUE
8010
8011 Example :
8012 # statistics admin level depends on the authenticated user
8013 userlist stats-auth
8014 group admin users admin
8015 user admin insecure-password AdMiN123
8016 group readonly users haproxy
8017 user haproxy insecure-password haproxy
8018
8019 backend stats_auth
8020 stats enable
8021 acl AUTH http_auth(stats-auth)
8022 acl AUTH_ADMIN http_auth_group(stats-auth) admin
8023 stats http-request auth unless AUTH
8024 stats admin if AUTH_ADMIN
8025
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008026 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
8027 "bind-process", section 3.4 about userlists and section 7 about
8028 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02008029
8030
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008031stats auth <user>:<passwd>
8032 Enable statistics with authentication and grant access to an account
8033 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008034 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008035 Arguments :
8036 <user> is a user name to grant access to
8037
8038 <passwd> is the cleartext password associated to this user
8039
8040 This statement enables statistics with default settings, and restricts access
8041 to declared users only. It may be repeated as many times as necessary to
8042 allow as many users as desired. When a user tries to access the statistics
8043 without a valid account, a "401 Forbidden" response will be returned so that
8044 the browser asks the user to provide a valid user and password. The real
8045 which will be returned to the browser is configurable using "stats realm".
8046
8047 Since the authentication method is HTTP Basic Authentication, the passwords
8048 circulate in cleartext on the network. Thus, it was decided that the
8049 configuration file would also use cleartext passwords to remind the users
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02008050 that those ones should not be sensitive and not shared with any other account.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008051
8052 It is also possible to reduce the scope of the proxies which appear in the
8053 report using "stats scope".
8054
8055 Though this statement alone is enough to enable statistics reporting, it is
8056 recommended to set all other settings in order to avoid relying on default
8057 unobvious parameters.
8058
8059 Example :
8060 # public access (limited to this backend only)
8061 backend public_www
8062 server srv1 192.168.0.1:80
8063 stats enable
8064 stats hide-version
8065 stats scope .
8066 stats uri /admin?stats
8067 stats realm Haproxy\ Statistics
8068 stats auth admin1:AdMiN123
8069 stats auth admin2:AdMiN321
8070
8071 # internal monitoring access (unlimited)
8072 backend private_monitoring
8073 stats enable
8074 stats uri /admin?stats
8075 stats refresh 5s
8076
8077 See also : "stats enable", "stats realm", "stats scope", "stats uri"
8078
8079
8080stats enable
8081 Enable statistics reporting with default settings
8082 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008083 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008084 Arguments : none
8085
8086 This statement enables statistics reporting with default settings defined
8087 at build time. Unless stated otherwise, these settings are used :
8088 - stats uri : /haproxy?stats
8089 - stats realm : "HAProxy Statistics"
8090 - stats auth : no authentication
8091 - stats scope : no restriction
8092
8093 Though this statement alone is enough to enable statistics reporting, it is
8094 recommended to set all other settings in order to avoid relying on default
8095 unobvious parameters.
8096
8097 Example :
8098 # public access (limited to this backend only)
8099 backend public_www
8100 server srv1 192.168.0.1:80
8101 stats enable
8102 stats hide-version
8103 stats scope .
8104 stats uri /admin?stats
8105 stats realm Haproxy\ Statistics
8106 stats auth admin1:AdMiN123
8107 stats auth admin2:AdMiN321
8108
8109 # internal monitoring access (unlimited)
8110 backend private_monitoring
8111 stats enable
8112 stats uri /admin?stats
8113 stats refresh 5s
8114
8115 See also : "stats auth", "stats realm", "stats uri"
8116
8117
Willy Tarreaud63335a2010-02-26 12:56:52 +01008118stats hide-version
8119 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008120 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008121 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01008122 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008123
Willy Tarreaud63335a2010-02-26 12:56:52 +01008124 By default, the stats page reports some useful status information along with
8125 the statistics. Among them is HAProxy's version. However, it is generally
8126 considered dangerous to report precise version to anyone, as it can help them
8127 target known weaknesses with specific attacks. The "stats hide-version"
8128 statement removes the version from the statistics report. This is recommended
8129 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008130
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02008131 Though this statement alone is enough to enable statistics reporting, it is
8132 recommended to set all other settings in order to avoid relying on default
8133 unobvious parameters.
8134
Willy Tarreaud63335a2010-02-26 12:56:52 +01008135 Example :
8136 # public access (limited to this backend only)
8137 backend public_www
8138 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02008139 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01008140 stats hide-version
8141 stats scope .
8142 stats uri /admin?stats
8143 stats realm Haproxy\ Statistics
8144 stats auth admin1:AdMiN123
8145 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008146
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008147 # internal monitoring access (unlimited)
8148 backend private_monitoring
8149 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01008150 stats uri /admin?stats
8151 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01008152
Willy Tarreaud63335a2010-02-26 12:56:52 +01008153 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02008154
Willy Tarreau983e01e2010-01-11 18:42:06 +01008155
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02008156stats http-request { allow | deny | auth [realm <realm>] }
8157 [ { if | unless } <condition> ]
8158 Access control for statistics
8159
8160 May be used in sections: defaults | frontend | listen | backend
8161 no | no | yes | yes
8162
8163 As "http-request", these set of options allow to fine control access to
8164 statistics. Each option may be followed by if/unless and acl.
8165 First option with matched condition (or option without condition) is final.
8166 For "deny" a 403 error will be returned, for "allow" normal processing is
8167 performed, for "auth" a 401/407 error code is returned so the client
8168 should be asked to enter a username and password.
8169
8170 There is no fixed limit to the number of http-request statements per
8171 instance.
8172
8173 See also : "http-request", section 3.4 about userlists and section 7
8174 about ACL usage.
8175
8176
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008177stats realm <realm>
8178 Enable statistics and set authentication realm
8179 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008180 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008181 Arguments :
8182 <realm> is the name of the HTTP Basic Authentication realm reported to
8183 the browser. The browser uses it to display it in the pop-up
8184 inviting the user to enter a valid username and password.
8185
8186 The realm is read as a single word, so any spaces in it should be escaped
8187 using a backslash ('\').
8188
8189 This statement is useful only in conjunction with "stats auth" since it is
8190 only related to authentication.
8191
8192 Though this statement alone is enough to enable statistics reporting, it is
8193 recommended to set all other settings in order to avoid relying on default
8194 unobvious parameters.
8195
8196 Example :
8197 # public access (limited to this backend only)
8198 backend public_www
8199 server srv1 192.168.0.1:80
8200 stats enable
8201 stats hide-version
8202 stats scope .
8203 stats uri /admin?stats
8204 stats realm Haproxy\ Statistics
8205 stats auth admin1:AdMiN123
8206 stats auth admin2:AdMiN321
8207
8208 # internal monitoring access (unlimited)
8209 backend private_monitoring
8210 stats enable
8211 stats uri /admin?stats
8212 stats refresh 5s
8213
8214 See also : "stats auth", "stats enable", "stats uri"
8215
8216
8217stats refresh <delay>
8218 Enable statistics with automatic refresh
8219 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008220 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008221 Arguments :
8222 <delay> is the suggested refresh delay, specified in seconds, which will
8223 be returned to the browser consulting the report page. While the
8224 browser is free to apply any delay, it will generally respect it
8225 and refresh the page this every seconds. The refresh interval may
8226 be specified in any other non-default time unit, by suffixing the
8227 unit after the value, as explained at the top of this document.
8228
8229 This statement is useful on monitoring displays with a permanent page
8230 reporting the load balancer's activity. When set, the HTML report page will
8231 include a link "refresh"/"stop refresh" so that the user can select whether
8232 he wants automatic refresh of the page or not.
8233
8234 Though this statement alone is enough to enable statistics reporting, it is
8235 recommended to set all other settings in order to avoid relying on default
8236 unobvious parameters.
8237
8238 Example :
8239 # public access (limited to this backend only)
8240 backend public_www
8241 server srv1 192.168.0.1:80
8242 stats enable
8243 stats hide-version
8244 stats scope .
8245 stats uri /admin?stats
8246 stats realm Haproxy\ Statistics
8247 stats auth admin1:AdMiN123
8248 stats auth admin2:AdMiN321
8249
8250 # internal monitoring access (unlimited)
8251 backend private_monitoring
8252 stats enable
8253 stats uri /admin?stats
8254 stats refresh 5s
8255
8256 See also : "stats auth", "stats enable", "stats realm", "stats uri"
8257
8258
8259stats scope { <name> | "." }
8260 Enable statistics and limit access scope
8261 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008262 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008263 Arguments :
8264 <name> is the name of a listen, frontend or backend section to be
8265 reported. The special name "." (a single dot) designates the
8266 section in which the statement appears.
8267
8268 When this statement is specified, only the sections enumerated with this
8269 statement will appear in the report. All other ones will be hidden. This
8270 statement may appear as many times as needed if multiple sections need to be
8271 reported. Please note that the name checking is performed as simple string
8272 comparisons, and that it is never checked that a give section name really
8273 exists.
8274
8275 Though this statement alone is enough to enable statistics reporting, it is
8276 recommended to set all other settings in order to avoid relying on default
8277 unobvious parameters.
8278
8279 Example :
8280 # public access (limited to this backend only)
8281 backend public_www
8282 server srv1 192.168.0.1:80
8283 stats enable
8284 stats hide-version
8285 stats scope .
8286 stats uri /admin?stats
8287 stats realm Haproxy\ Statistics
8288 stats auth admin1:AdMiN123
8289 stats auth admin2:AdMiN321
8290
8291 # internal monitoring access (unlimited)
8292 backend private_monitoring
8293 stats enable
8294 stats uri /admin?stats
8295 stats refresh 5s
8296
8297 See also : "stats auth", "stats enable", "stats realm", "stats uri"
8298
Willy Tarreaud63335a2010-02-26 12:56:52 +01008299
Willy Tarreauc9705a12010-07-27 20:05:50 +02008300stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01008301 Enable reporting of a description on the statistics page.
8302 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008303 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01008304
Willy Tarreauc9705a12010-07-27 20:05:50 +02008305 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01008306 description from global section is automatically used instead.
8307
8308 This statement is useful for users that offer shared services to their
8309 customers, where node or description should be different for each customer.
8310
8311 Though this statement alone is enough to enable statistics reporting, it is
8312 recommended to set all other settings in order to avoid relying on default
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04008313 unobvious parameters. By default description is not shown.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008314
8315 Example :
8316 # internal monitoring access (unlimited)
8317 backend private_monitoring
8318 stats enable
8319 stats show-desc Master node for Europe, Asia, Africa
8320 stats uri /admin?stats
8321 stats refresh 5s
8322
8323 See also: "show-node", "stats enable", "stats uri" and "description" in
8324 global section.
8325
8326
8327stats show-legends
Willy Tarreaued2119c2014-04-24 22:10:39 +02008328 Enable reporting additional information on the statistics page
8329 May be used in sections : defaults | frontend | listen | backend
8330 yes | yes | yes | yes
8331 Arguments : none
8332
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03008333 Enable reporting additional information on the statistics page :
Willy Tarreaud63335a2010-02-26 12:56:52 +01008334 - cap: capabilities (proxy)
8335 - mode: one of tcp, http or health (proxy)
8336 - id: SNMP ID (proxy, socket, server)
8337 - IP (socket, server)
8338 - cookie (backend, server)
8339
8340 Though this statement alone is enough to enable statistics reporting, it is
8341 recommended to set all other settings in order to avoid relying on default
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04008342 unobvious parameters. Default behaviour is not to show this information.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008343
8344 See also: "stats enable", "stats uri".
8345
8346
8347stats show-node [ <name> ]
8348 Enable reporting of a host name on the statistics page.
8349 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008350 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01008351 Arguments:
8352 <name> is an optional name to be reported. If unspecified, the
8353 node name from global section is automatically used instead.
8354
8355 This statement is useful for users that offer shared services to their
8356 customers, where node or description might be different on a stats page
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04008357 provided for each customer. Default behaviour is not to show host name.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008358
8359 Though this statement alone is enough to enable statistics reporting, it is
8360 recommended to set all other settings in order to avoid relying on default
8361 unobvious parameters.
8362
8363 Example:
8364 # internal monitoring access (unlimited)
8365 backend private_monitoring
8366 stats enable
8367 stats show-node Europe-1
8368 stats uri /admin?stats
8369 stats refresh 5s
8370
8371 See also: "show-desc", "stats enable", "stats uri", and "node" in global
8372 section.
8373
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008374
8375stats uri <prefix>
8376 Enable statistics and define the URI prefix to access them
8377 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008378 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008379 Arguments :
8380 <prefix> is the prefix of any URI which will be redirected to stats. This
8381 prefix may contain a question mark ('?') to indicate part of a
8382 query string.
8383
8384 The statistics URI is intercepted on the relayed traffic, so it appears as a
8385 page within the normal application. It is strongly advised to ensure that the
8386 selected URI will never appear in the application, otherwise it will never be
8387 possible to reach it in the application.
8388
8389 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008390 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008391 It is generally a good idea to include a question mark in the URI so that
8392 intermediate proxies refrain from caching the results. Also, since any string
8393 beginning with the prefix will be accepted as a stats request, the question
8394 mark helps ensuring that no valid URI will begin with the same words.
8395
8396 It is sometimes very convenient to use "/" as the URI prefix, and put that
8397 statement in a "listen" instance of its own. That makes it easy to dedicate
8398 an address or a port to statistics only.
8399
8400 Though this statement alone is enough to enable statistics reporting, it is
8401 recommended to set all other settings in order to avoid relying on default
8402 unobvious parameters.
8403
8404 Example :
8405 # public access (limited to this backend only)
8406 backend public_www
8407 server srv1 192.168.0.1:80
8408 stats enable
8409 stats hide-version
8410 stats scope .
8411 stats uri /admin?stats
8412 stats realm Haproxy\ Statistics
8413 stats auth admin1:AdMiN123
8414 stats auth admin2:AdMiN321
8415
8416 # internal monitoring access (unlimited)
8417 backend private_monitoring
8418 stats enable
8419 stats uri /admin?stats
8420 stats refresh 5s
8421
8422 See also : "stats auth", "stats enable", "stats realm"
8423
8424
Willy Tarreaud63335a2010-02-26 12:56:52 +01008425stick match <pattern> [table <table>] [{if | unless} <cond>]
8426 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008427 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +01008428 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008429
8430 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02008431 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008432 describes what elements of the incoming request or connection
8433 will be analysed in the hope to find a matching entry in a
8434 stickiness table. This rule is mandatory.
8435
8436 <table> is an optional stickiness table name. If unspecified, the same
8437 backend's table is used. A stickiness table is declared using
8438 the "stick-table" statement.
8439
8440 <cond> is an optional matching condition. It makes it possible to match
8441 on a certain criterion only when other conditions are met (or
8442 not met). For instance, it could be used to match on a source IP
8443 address except when a request passes through a known proxy, in
8444 which case we'd match on a header containing that IP address.
8445
8446 Some protocols or applications require complex stickiness rules and cannot
8447 always simply rely on cookies nor hashing. The "stick match" statement
8448 describes a rule to extract the stickiness criterion from an incoming request
8449 or connection. See section 7 for a complete list of possible patterns and
8450 transformation rules.
8451
8452 The table has to be declared using the "stick-table" statement. It must be of
8453 a type compatible with the pattern. By default it is the one which is present
8454 in the same backend. It is possible to share a table with other backends by
8455 referencing it using the "table" keyword. If another table is referenced,
8456 the server's ID inside the backends are used. By default, all server IDs
8457 start at 1 in each backend, so the server ordering is enough. But in case of
8458 doubt, it is highly recommended to force server IDs using their "id" setting.
8459
8460 It is possible to restrict the conditions where a "stick match" statement
8461 will apply, using "if" or "unless" followed by a condition. See section 7 for
8462 ACL based conditions.
8463
8464 There is no limit on the number of "stick match" statements. The first that
8465 applies and matches will cause the request to be directed to the same server
8466 as was used for the request which created the entry. That way, multiple
8467 matches can be used as fallbacks.
8468
8469 The stick rules are checked after the persistence cookies, so they will not
8470 affect stickiness if a cookie has already been used to select a server. That
8471 way, it becomes very easy to insert cookies and match on IP addresses in
8472 order to maintain stickiness between HTTP and HTTPS.
8473
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008474 Note : Consider not using this feature in multi-process mode (nbproc > 1)
8475 unless you know what you do : memory is not shared between the
8476 processes, which can result in random behaviours.
8477
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008478 Example :
8479 # forward SMTP users to the same server they just used for POP in the
8480 # last 30 minutes
8481 backend pop
8482 mode tcp
8483 balance roundrobin
8484 stick store-request src
8485 stick-table type ip size 200k expire 30m
8486 server s1 192.168.1.1:110
8487 server s2 192.168.1.1:110
8488
8489 backend smtp
8490 mode tcp
8491 balance roundrobin
8492 stick match src table pop
8493 server s1 192.168.1.1:25
8494 server s2 192.168.1.1:25
8495
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008496 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +02008497 about ACLs and samples fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008498
8499
8500stick on <pattern> [table <table>] [{if | unless} <condition>]
8501 Define a request pattern to associate a user to a server
8502 May be used in sections : defaults | frontend | listen | backend
8503 no | no | yes | yes
8504
8505 Note : This form is exactly equivalent to "stick match" followed by
8506 "stick store-request", all with the same arguments. Please refer
8507 to both keywords for details. It is only provided as a convenience
8508 for writing more maintainable configurations.
8509
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008510 Note : Consider not using this feature in multi-process mode (nbproc > 1)
8511 unless you know what you do : memory is not shared between the
8512 processes, which can result in random behaviours.
8513
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008514 Examples :
8515 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +01008516 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008517
8518 # ...is strictly equivalent to this one :
8519 stick match src table pop if !localhost
8520 stick store-request src table pop if !localhost
8521
8522
8523 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
8524 # well as HTTP without cookie. Share the same table between both accesses.
8525 backend http
8526 mode http
8527 balance roundrobin
8528 stick on src table https
8529 cookie SRV insert indirect nocache
8530 server s1 192.168.1.1:80 cookie s1
8531 server s2 192.168.1.1:80 cookie s2
8532
8533 backend https
8534 mode tcp
8535 balance roundrobin
8536 stick-table type ip size 200k expire 30m
8537 stick on src
8538 server s1 192.168.1.1:443
8539 server s2 192.168.1.1:443
8540
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008541 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008542
8543
8544stick store-request <pattern> [table <table>] [{if | unless} <condition>]
8545 Define a request pattern used to create an entry in a stickiness table
8546 May be used in sections : defaults | frontend | listen | backend
8547 no | no | yes | yes
8548
8549 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02008550 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008551 describes what elements of the incoming request or connection
8552 will be analysed, extracted and stored in the table once a
8553 server is selected.
8554
8555 <table> is an optional stickiness table name. If unspecified, the same
8556 backend's table is used. A stickiness table is declared using
8557 the "stick-table" statement.
8558
8559 <cond> is an optional storage condition. It makes it possible to store
8560 certain criteria only when some conditions are met (or not met).
8561 For instance, it could be used to store the source IP address
8562 except when the request passes through a known proxy, in which
8563 case we'd store a converted form of a header containing that IP
8564 address.
8565
8566 Some protocols or applications require complex stickiness rules and cannot
8567 always simply rely on cookies nor hashing. The "stick store-request" statement
8568 describes a rule to decide what to extract from the request and when to do
8569 it, in order to store it into a stickiness table for further requests to
8570 match it using the "stick match" statement. Obviously the extracted part must
8571 make sense and have a chance to be matched in a further request. Storing a
8572 client's IP address for instance often makes sense. Storing an ID found in a
8573 URL parameter also makes sense. Storing a source port will almost never make
8574 any sense because it will be randomly matched. See section 7 for a complete
8575 list of possible patterns and transformation rules.
8576
8577 The table has to be declared using the "stick-table" statement. It must be of
8578 a type compatible with the pattern. By default it is the one which is present
8579 in the same backend. It is possible to share a table with other backends by
8580 referencing it using the "table" keyword. If another table is referenced,
8581 the server's ID inside the backends are used. By default, all server IDs
8582 start at 1 in each backend, so the server ordering is enough. But in case of
8583 doubt, it is highly recommended to force server IDs using their "id" setting.
8584
8585 It is possible to restrict the conditions where a "stick store-request"
8586 statement will apply, using "if" or "unless" followed by a condition. This
8587 condition will be evaluated while parsing the request, so any criteria can be
8588 used. See section 7 for ACL based conditions.
8589
8590 There is no limit on the number of "stick store-request" statements, but
8591 there is a limit of 8 simultaneous stores per request or response. This
8592 makes it possible to store up to 8 criteria, all extracted from either the
8593 request or the response, regardless of the number of rules. Only the 8 first
8594 ones which match will be kept. Using this, it is possible to feed multiple
8595 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +01008596 another protocol or access method. Using multiple store-request rules with
8597 the same table is possible and may be used to find the best criterion to rely
8598 on, by arranging the rules by decreasing preference order. Only the first
8599 extracted criterion for a given table will be stored. All subsequent store-
8600 request rules referencing the same table will be skipped and their ACLs will
8601 not be evaluated.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008602
8603 The "store-request" rules are evaluated once the server connection has been
8604 established, so that the table will contain the real server that processed
8605 the request.
8606
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008607 Note : Consider not using this feature in multi-process mode (nbproc > 1)
8608 unless you know what you do : memory is not shared between the
8609 processes, which can result in random behaviours.
8610
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008611 Example :
8612 # forward SMTP users to the same server they just used for POP in the
8613 # last 30 minutes
8614 backend pop
8615 mode tcp
8616 balance roundrobin
8617 stick store-request src
8618 stick-table type ip size 200k expire 30m
8619 server s1 192.168.1.1:110
8620 server s2 192.168.1.1:110
8621
8622 backend smtp
8623 mode tcp
8624 balance roundrobin
8625 stick match src table pop
8626 server s1 192.168.1.1:25
8627 server s2 192.168.1.1:25
8628
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008629 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +02008630 about ACLs and sample fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008631
8632
Emeric Brun7c6b82e2010-09-24 16:34:28 +02008633stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +02008634 size <size> [expire <expire>] [nopurge] [peers <peersect>]
8635 [store <data_type>]*
Godbach64cef792013-12-04 16:08:22 +08008636 Configure the stickiness table for the current section
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008637 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +02008638 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008639
8640 Arguments :
8641 ip a table declared with "type ip" will only store IPv4 addresses.
8642 This form is very compact (about 50 bytes per entry) and allows
8643 very fast entry lookup and stores with almost no overhead. This
8644 is mainly used to store client source IP addresses.
8645
David du Colombier9a6d3c92011-03-17 10:40:24 +01008646 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
8647 This form is very compact (about 60 bytes per entry) and allows
8648 very fast entry lookup and stores with almost no overhead. This
8649 is mainly used to store client source IP addresses.
8650
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008651 integer a table declared with "type integer" will store 32bit integers
8652 which can represent a client identifier found in a request for
8653 instance.
8654
8655 string a table declared with "type string" will store substrings of up
8656 to <len> characters. If the string provided by the pattern
8657 extractor is larger than <len>, it will be truncated before
8658 being stored. During matching, at most <len> characters will be
8659 compared between the string in the table and the extracted
8660 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +02008661 to 32 characters.
8662
8663 binary a table declared with "type binary" will store binary blocks
8664 of <len> bytes. If the block provided by the pattern
8665 extractor is larger than <len>, it will be truncated before
Willy Tarreaube722a22014-06-13 16:31:59 +02008666 being stored. If the block provided by the sample expression
Emeric Brun7c6b82e2010-09-24 16:34:28 +02008667 is shorter than <len>, it will be padded by 0. When not
8668 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008669
8670 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +02008671 "string" type table (See type "string" above). Or the number
8672 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008673 changing this parameter as memory usage will proportionally
8674 increase.
8675
8676 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +01008677 value directly impacts memory usage. Count approximately
8678 50 bytes per entry, plus the size of a string if any. The size
8679 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008680
8681 [nopurge] indicates that we refuse to purge older entries when the table
8682 is full. When not specified and the table is full when haproxy
8683 wants to store an entry in it, it will flush a few of the oldest
8684 entries in order to release some space for the new ones. This is
8685 most often the desired behaviour. In some specific cases, it
8686 be desirable to refuse new entries instead of purging the older
8687 ones. That may be the case when the amount of data to store is
8688 far above the hardware limits and we prefer not to offer access
8689 to new clients than to reject the ones already connected. When
8690 using this parameter, be sure to properly set the "expire"
8691 parameter (see below).
8692
Emeric Brunf099e792010-09-27 12:05:28 +02008693 <peersect> is the name of the peers section to use for replication. Entries
8694 which associate keys to server IDs are kept synchronized with
8695 the remote peers declared in this section. All entries are also
8696 automatically learned from the local peer (old process) during a
8697 soft restart.
8698
Willy Tarreau1abc6732015-05-01 19:21:02 +02008699 NOTE : each peers section may be referenced only by tables
8700 belonging to the same unique process.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008701
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008702 <expire> defines the maximum duration of an entry in the table since it
8703 was last created, refreshed or matched. The expiration delay is
8704 defined using the standard time format, similarly as the various
8705 timeouts. The maximum duration is slightly above 24 days. See
Jarno Huuskonene0ee0be2017-07-04 10:35:12 +03008706 section 2.4 for more information. If this delay is not specified,
Cyril Bontédc4d9032012-04-08 21:57:39 +02008707 the session won't automatically expire, but older entries will
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008708 be removed once full. Be sure not to use the "nopurge" parameter
8709 if not expiration delay is specified.
8710
Willy Tarreau08d5f982010-06-06 13:34:54 +02008711 <data_type> is used to store additional information in the stick-table. This
8712 may be used by ACLs in order to control various criteria related
8713 to the activity of the client matching the stick-table. For each
8714 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +02008715 that the additional data can fit. Several data types may be
8716 stored with an entry. Multiple data types may be specified after
8717 the "store" keyword, as a comma-separated list. Alternatively,
8718 it is possible to repeat the "store" keyword followed by one or
8719 several data types. Except for the "server_id" type which is
8720 automatically detected and enabled, all data types must be
8721 explicitly declared to be stored. If an ACL references a data
8722 type which is not stored, the ACL will simply not match. Some
8723 data types require an argument which must be passed just after
8724 the type between parenthesis. See below for the supported data
8725 types and their arguments.
8726
8727 The data types that can be stored with an entry are the following :
8728 - server_id : this is an integer which holds the numeric ID of the server a
8729 request was assigned to. It is used by the "stick match", "stick store",
8730 and "stick on" rules. It is automatically enabled when referenced.
8731
8732 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
8733 integer which may be used for anything. Most of the time it will be used
8734 to put a special tag on some entries, for instance to note that a
8735 specific behaviour was detected and must be known for future matches.
8736
Willy Tarreauba2ffd12013-05-29 15:54:14 +02008737 - gpc0_rate(<period>) : increment rate of the first General Purpose Counter
8738 over a period. It is a positive 32-bit integer integer which may be used
8739 for anything. Just like <gpc0>, it counts events, but instead of keeping
8740 a cumulative count, it maintains the rate at which the counter is
8741 incremented. Most of the time it will be used to measure the frequency of
8742 occurrence of certain events (eg: requests to a specific URL).
8743
Willy Tarreauc9705a12010-07-27 20:05:50 +02008744 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
8745 the absolute number of connections received from clients which matched
8746 this entry. It does not mean the connections were accepted, just that
8747 they were received.
8748
8749 - conn_cur : Current Connections. It is a positive 32-bit integer which
8750 stores the concurrent connection counts for the entry. It is incremented
8751 once an incoming connection matches the entry, and decremented once the
8752 connection leaves. That way it is possible to know at any time the exact
8753 number of concurrent connections for an entry.
8754
8755 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
8756 integer parameter <period> which indicates in milliseconds the length
8757 of the period over which the average is measured. It reports the average
8758 incoming connection rate over that period, in connections per period. The
8759 result is an integer which can be matched using ACLs.
8760
8761 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
8762 the absolute number of sessions received from clients which matched this
8763 entry. A session is a connection that was accepted by the layer 4 rules.
8764
8765 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
8766 integer parameter <period> which indicates in milliseconds the length
8767 of the period over which the average is measured. It reports the average
8768 incoming session rate over that period, in sessions per period. The
8769 result is an integer which can be matched using ACLs.
8770
8771 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
8772 counts the absolute number of HTTP requests received from clients which
8773 matched this entry. It does not matter whether they are valid requests or
8774 not. Note that this is different from sessions when keep-alive is used on
8775 the client side.
8776
8777 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
8778 integer parameter <period> which indicates in milliseconds the length
8779 of the period over which the average is measured. It reports the average
8780 HTTP request rate over that period, in requests per period. The result is
8781 an integer which can be matched using ACLs. It does not matter whether
8782 they are valid requests or not. Note that this is different from sessions
8783 when keep-alive is used on the client side.
8784
8785 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
8786 counts the absolute number of HTTP requests errors induced by clients
8787 which matched this entry. Errors are counted on invalid and truncated
8788 requests, as well as on denied or tarpitted requests, and on failed
8789 authentications. If the server responds with 4xx, then the request is
8790 also counted as an error since it's an error triggered by the client
8791 (eg: vulnerability scan).
8792
8793 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
8794 integer parameter <period> which indicates in milliseconds the length
8795 of the period over which the average is measured. It reports the average
8796 HTTP request error rate over that period, in requests per period (see
8797 http_err_cnt above for what is accounted as an error). The result is an
8798 integer which can be matched using ACLs.
8799
8800 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
8801 integer which counts the cumulated amount of bytes received from clients
8802 which matched this entry. Headers are included in the count. This may be
8803 used to limit abuse of upload features on photo or video servers.
8804
8805 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
8806 integer parameter <period> which indicates in milliseconds the length
8807 of the period over which the average is measured. It reports the average
8808 incoming bytes rate over that period, in bytes per period. It may be used
8809 to detect users which upload too much and too fast. Warning: with large
8810 uploads, it is possible that the amount of uploaded data will be counted
8811 once upon termination, thus causing spikes in the average transfer speed
8812 instead of having a smooth one. This may partially be smoothed with
8813 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
8814 recommended for better fairness.
8815
8816 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
8817 integer which counts the cumulated amount of bytes sent to clients which
8818 matched this entry. Headers are included in the count. This may be used
8819 to limit abuse of bots sucking the whole site.
8820
8821 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
8822 an integer parameter <period> which indicates in milliseconds the length
8823 of the period over which the average is measured. It reports the average
8824 outgoing bytes rate over that period, in bytes per period. It may be used
8825 to detect users which download too much and too fast. Warning: with large
8826 transfers, it is possible that the amount of transferred data will be
8827 counted once upon termination, thus causing spikes in the average
8828 transfer speed instead of having a smooth one. This may partially be
8829 smoothed with "option contstats" though this is not perfect yet. Use of
8830 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +02008831
Willy Tarreauc00cdc22010-06-06 16:48:26 +02008832 There is only one stick-table per proxy. At the moment of writing this doc,
8833 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008834 to be required, simply create a dummy backend with a stick-table in it and
8835 reference it.
8836
8837 It is important to understand that stickiness based on learning information
8838 has some limitations, including the fact that all learned associations are
Baptiste Assmann123ff042016-03-06 23:29:28 +01008839 lost upon restart unless peers are properly configured to transfer such
8840 information upon restart (recommended). In general it can be good as a
8841 complement but not always as an exclusive stickiness.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008842
Willy Tarreauc9705a12010-07-27 20:05:50 +02008843 Last, memory requirements may be important when storing many data types.
8844 Indeed, storing all indicators above at once in each entry requires 116 bytes
8845 per entry, or 116 MB for a 1-million entries table. This is definitely not
8846 something that can be ignored.
8847
8848 Example:
8849 # Keep track of counters of up to 1 million IP addresses over 5 minutes
8850 # and store a general purpose counter and the average connection rate
8851 # computed over a sliding window of 30 seconds.
8852 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
8853
Jarno Huuskonene0ee0be2017-07-04 10:35:12 +03008854 See also : "stick match", "stick on", "stick store-request", section 2.4
David du Colombiera13d1b92011-03-17 10:40:22 +01008855 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01008856
8857
Emeric Brun6a1cefa2010-09-24 18:15:17 +02008858stick store-response <pattern> [table <table>] [{if | unless} <condition>]
Baptiste Assmann2f2d2ec2016-03-06 23:27:24 +01008859 Define a response pattern used to create an entry in a stickiness table
Emeric Brun6a1cefa2010-09-24 18:15:17 +02008860 May be used in sections : defaults | frontend | listen | backend
8861 no | no | yes | yes
8862
8863 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02008864 <pattern> is a sample expression rule as described in section 7.3. It
Emeric Brun6a1cefa2010-09-24 18:15:17 +02008865 describes what elements of the response or connection will
8866 be analysed, extracted and stored in the table once a
8867 server is selected.
8868
8869 <table> is an optional stickiness table name. If unspecified, the same
8870 backend's table is used. A stickiness table is declared using
8871 the "stick-table" statement.
8872
8873 <cond> is an optional storage condition. It makes it possible to store
8874 certain criteria only when some conditions are met (or not met).
8875 For instance, it could be used to store the SSL session ID only
8876 when the response is a SSL server hello.
8877
8878 Some protocols or applications require complex stickiness rules and cannot
8879 always simply rely on cookies nor hashing. The "stick store-response"
8880 statement describes a rule to decide what to extract from the response and
8881 when to do it, in order to store it into a stickiness table for further
8882 requests to match it using the "stick match" statement. Obviously the
8883 extracted part must make sense and have a chance to be matched in a further
Cyril Bonté108cf6e2012-04-21 23:30:29 +02008884 request. Storing an ID found in a header of a response makes sense.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02008885 See section 7 for a complete list of possible patterns and transformation
8886 rules.
8887
8888 The table has to be declared using the "stick-table" statement. It must be of
8889 a type compatible with the pattern. By default it is the one which is present
8890 in the same backend. It is possible to share a table with other backends by
8891 referencing it using the "table" keyword. If another table is referenced,
8892 the server's ID inside the backends are used. By default, all server IDs
8893 start at 1 in each backend, so the server ordering is enough. But in case of
8894 doubt, it is highly recommended to force server IDs using their "id" setting.
8895
8896 It is possible to restrict the conditions where a "stick store-response"
8897 statement will apply, using "if" or "unless" followed by a condition. This
8898 condition will be evaluated while parsing the response, so any criteria can
8899 be used. See section 7 for ACL based conditions.
8900
8901 There is no limit on the number of "stick store-response" statements, but
8902 there is a limit of 8 simultaneous stores per request or response. This
8903 makes it possible to store up to 8 criteria, all extracted from either the
8904 request or the response, regardless of the number of rules. Only the 8 first
8905 ones which match will be kept. Using this, it is possible to feed multiple
8906 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +01008907 another protocol or access method. Using multiple store-response rules with
8908 the same table is possible and may be used to find the best criterion to rely
8909 on, by arranging the rules by decreasing preference order. Only the first
8910 extracted criterion for a given table will be stored. All subsequent store-
8911 response rules referencing the same table will be skipped and their ACLs will
8912 not be evaluated. However, even if a store-request rule references a table, a
8913 store-response rule may also use the same table. This means that each table
8914 may learn exactly one element from the request and one element from the
8915 response at once.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02008916
8917 The table will contain the real server that processed the request.
8918
8919 Example :
8920 # Learn SSL session ID from both request and response and create affinity.
8921 backend https
8922 mode tcp
8923 balance roundrobin
Cyril Bontédc4d9032012-04-08 21:57:39 +02008924 # maximum SSL session ID length is 32 bytes.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02008925 stick-table type binary len 32 size 30k expire 30m
Cyril Bonté108cf6e2012-04-21 23:30:29 +02008926
Emeric Brun6a1cefa2010-09-24 18:15:17 +02008927 acl clienthello req_ssl_hello_type 1
8928 acl serverhello rep_ssl_hello_type 2
8929
8930 # use tcp content accepts to detects ssl client and server hello.
8931 tcp-request inspect-delay 5s
8932 tcp-request content accept if clienthello
8933
8934 # no timeout on response inspect delay by default.
8935 tcp-response content accept if serverhello
Cyril Bonté108cf6e2012-04-21 23:30:29 +02008936
Emeric Brun6a1cefa2010-09-24 18:15:17 +02008937 # SSL session ID (SSLID) may be present on a client or server hello.
8938 # Its length is coded on 1 byte at offset 43 and its value starts
8939 # at offset 44.
8940
8941 # Match and learn on request if client hello.
8942 stick on payload_lv(43,1) if clienthello
8943
8944 # Learn on response if server hello.
8945 stick store-response payload_lv(43,1) if serverhello
Cyril Bontédc4d9032012-04-08 21:57:39 +02008946
Emeric Brun6a1cefa2010-09-24 18:15:17 +02008947 server s1 192.168.1.1:443
8948 server s2 192.168.1.1:443
8949
8950 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
8951 extraction.
8952
8953
Willy Tarreau938c7fe2014-04-25 14:21:39 +02008954tcp-check connect [params*]
8955 Opens a new connection
8956 May be used in sections: defaults | frontend | listen | backend
8957 no | no | yes | yes
8958
8959 When an application lies on more than a single TCP port or when HAProxy
8960 load-balance many services in a single backend, it makes sense to probe all
8961 the services individually before considering a server as operational.
8962
8963 When there are no TCP port configured on the server line neither server port
8964 directive, then the 'tcp-check connect port <port>' must be the first step
8965 of the sequence.
8966
8967 In a tcp-check ruleset a 'connect' is required, it is also mandatory to start
8968 the ruleset with a 'connect' rule. Purpose is to ensure admin know what they
8969 do.
8970
8971 Parameters :
8972 They are optional and can be used to describe how HAProxy should open and
8973 use the TCP connection.
8974
8975 port if not set, check port or server port is used.
8976 It tells HAProxy where to open the connection to.
8977 <port> must be a valid TCP port source integer, from 1 to 65535.
8978
8979 send-proxy send a PROXY protocol string
8980
8981 ssl opens a ciphered connection
8982
8983 Examples:
8984 # check HTTP and HTTPs services on a server.
8985 # first open port 80 thanks to server line port directive, then
8986 # tcp-check opens port 443, ciphered and run a request on it:
8987 option tcp-check
8988 tcp-check connect
8989 tcp-check send GET\ /\ HTTP/1.0\r\n
8990 tcp-check send Host:\ haproxy.1wt.eu\r\n
8991 tcp-check send \r\n
8992 tcp-check expect rstring (2..|3..)
8993 tcp-check connect port 443 ssl
8994 tcp-check send GET\ /\ HTTP/1.0\r\n
8995 tcp-check send Host:\ haproxy.1wt.eu\r\n
8996 tcp-check send \r\n
8997 tcp-check expect rstring (2..|3..)
8998 server www 10.0.0.1 check port 80
8999
9000 # check both POP and IMAP from a single server:
9001 option tcp-check
9002 tcp-check connect port 110
9003 tcp-check expect string +OK\ POP3\ ready
9004 tcp-check connect port 143
9005 tcp-check expect string *\ OK\ IMAP4\ ready
9006 server mail 10.0.0.1 check
9007
9008 See also : "option tcp-check", "tcp-check send", "tcp-check expect"
9009
9010
9011tcp-check expect [!] <match> <pattern>
9012 Specify data to be collected and analysed during a generic health check
9013 May be used in sections: defaults | frontend | listen | backend
9014 no | no | yes | yes
9015
9016 Arguments :
9017 <match> is a keyword indicating how to look for a specific pattern in the
9018 response. The keyword may be one of "string", "rstring" or
9019 binary.
9020 The keyword may be preceded by an exclamation mark ("!") to negate
9021 the match. Spaces are allowed between the exclamation mark and the
9022 keyword. See below for more details on the supported keywords.
9023
9024 <pattern> is the pattern to look for. It may be a string or a regular
9025 expression. If the pattern contains spaces, they must be escaped
9026 with the usual backslash ('\').
9027 If the match is set to binary, then the pattern must be passed as
9028 a serie of hexadecimal digits in an even number. Each sequence of
9029 two digits will represent a byte. The hexadecimal digits may be
9030 used upper or lower case.
9031
9032
9033 The available matches are intentionally similar to their http-check cousins :
9034
9035 string <string> : test the exact string matches in the response buffer.
9036 A health check response will be considered valid if the
9037 response's buffer contains this exact string. If the
9038 "string" keyword is prefixed with "!", then the response
9039 will be considered invalid if the body contains this
9040 string. This can be used to look for a mandatory pattern
9041 in a protocol response, or to detect a failure when a
9042 specific error appears in a protocol banner.
9043
9044 rstring <regex> : test a regular expression on the response buffer.
9045 A health check response will be considered valid if the
9046 response's buffer matches this expression. If the
9047 "rstring" keyword is prefixed with "!", then the response
9048 will be considered invalid if the body matches the
9049 expression.
9050
9051 binary <hexstring> : test the exact string in its hexadecimal form matches
9052 in the response buffer. A health check response will
9053 be considered valid if the response's buffer contains
9054 this exact hexadecimal string.
9055 Purpose is to match data on binary protocols.
9056
9057 It is important to note that the responses will be limited to a certain size
9058 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
9059 Thus, too large responses may not contain the mandatory pattern when using
9060 "string", "rstring" or binary. If a large response is absolutely required, it
9061 is possible to change the default max size by setting the global variable.
9062 However, it is worth keeping in mind that parsing very large responses can
9063 waste some CPU cycles, especially when regular expressions are used, and that
9064 it is always better to focus the checks on smaller resources. Also, in its
9065 current state, the check will not find any string nor regex past a null
9066 character in the response. Similarly it is not possible to request matching
9067 the null character.
9068
9069 Examples :
9070 # perform a POP check
9071 option tcp-check
9072 tcp-check expect string +OK\ POP3\ ready
9073
9074 # perform an IMAP check
9075 option tcp-check
9076 tcp-check expect string *\ OK\ IMAP4\ ready
9077
9078 # look for the redis master server
9079 option tcp-check
9080 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +02009081 tcp-check expect string +PONG
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009082 tcp-check send info\ replication\r\n
9083 tcp-check expect string role:master
9084 tcp-check send QUIT\r\n
9085 tcp-check expect string +OK
9086
9087
9088 See also : "option tcp-check", "tcp-check connect", "tcp-check send",
9089 "tcp-check send-binary", "http-check expect", tune.chksize
9090
9091
9092tcp-check send <data>
9093 Specify a string to be sent as a question during a generic health check
9094 May be used in sections: defaults | frontend | listen | backend
9095 no | no | yes | yes
9096
9097 <data> : the data to be sent as a question during a generic health check
9098 session. For now, <data> must be a string.
9099
9100 Examples :
9101 # look for the redis master server
9102 option tcp-check
9103 tcp-check send info\ replication\r\n
9104 tcp-check expect string role:master
9105
9106 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
9107 "tcp-check send-binary", tune.chksize
9108
9109
9110tcp-check send-binary <hexastring>
9111 Specify an hexa digits string to be sent as a binary question during a raw
9112 tcp health check
9113 May be used in sections: defaults | frontend | listen | backend
9114 no | no | yes | yes
9115
9116 <data> : the data to be sent as a question during a generic health check
9117 session. For now, <data> must be a string.
9118 <hexastring> : test the exact string in its hexadecimal form matches in the
9119 response buffer. A health check response will be considered
9120 valid if the response's buffer contains this exact
9121 hexadecimal string.
9122 Purpose is to send binary data to ask on binary protocols.
9123
9124 Examples :
9125 # redis check in binary
9126 option tcp-check
9127 tcp-check send-binary 50494e470d0a # PING\r\n
9128 tcp-check expect binary 2b504F4e47 # +PONG
9129
9130
9131 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
9132 "tcp-check send", tune.chksize
9133
9134
Willy Tarreaue9656522010-08-17 15:40:09 +02009135tcp-request connection <action> [{if | unless} <condition>]
9136 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +02009137 May be used in sections : defaults | frontend | listen | backend
9138 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +02009139 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +02009140 <action> defines the action to perform if the condition applies. See
9141 below.
Willy Tarreau1a687942010-05-23 22:40:30 +02009142
Willy Tarreaue9656522010-08-17 15:40:09 +02009143 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009144
9145 Immediately after acceptance of a new incoming connection, it is possible to
9146 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +02009147 or dropped or have its counters tracked. Those conditions cannot make use of
9148 any data contents because the connection has not been read from yet, and the
9149 buffers are not yet allocated. This is used to selectively and very quickly
9150 accept or drop connections from various sources with a very low overhead. If
9151 some contents need to be inspected in order to take the decision, the
9152 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009153
Willy Tarreaue9656522010-08-17 15:40:09 +02009154 The "tcp-request connection" rules are evaluated in their exact declaration
9155 order. If no rule matches or if there is no rule, the default action is to
9156 accept the incoming connection. There is no specific limit to the number of
9157 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009158
Willy Tarreaua9083d02015-05-08 15:27:59 +02009159 Four types of actions are supported :
Willy Tarreaue9656522010-08-17 15:40:09 +02009160 - accept :
9161 accepts the connection if the condition is true (when used with "if")
9162 or false (when used with "unless"). The first such rule executed ends
9163 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009164
Willy Tarreaue9656522010-08-17 15:40:09 +02009165 - reject :
9166 rejects the connection if the condition is true (when used with "if")
9167 or false (when used with "unless"). The first such rule executed ends
9168 the rules evaluation. Rejected connections do not even become a
9169 session, which is why they are accounted separately for in the stats,
9170 as "denied connections". They are not considered for the session
9171 rate-limit and are not logged either. The reason is that these rules
9172 should only be used to filter extremely high connection rates such as
9173 the ones encountered during a massive DDoS attack. Under these extreme
9174 conditions, the simple action of logging each event would make the
9175 system collapse and would considerably lower the filtering capacity. If
9176 logging is absolutely desired, then "tcp-request content" rules should
Willy Tarreau4f614292016-10-21 17:49:36 +02009177 be used instead, as "tcp-request session" rules will not log either.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009178
Willy Tarreau4f0d9192013-06-11 20:40:55 +02009179 - expect-proxy layer4 :
9180 configures the client-facing connection to receive a PROXY protocol
9181 header before any byte is read from the socket. This is equivalent to
9182 having the "accept-proxy" keyword on the "bind" line, except that using
9183 the TCP rule allows the PROXY protocol to be accepted only for certain
9184 IP address ranges using an ACL. This is convenient when multiple layers
9185 of load balancers are passed through by traffic coming from public
9186 hosts.
9187
Bertrand Jacquin90759682016-06-06 15:35:39 +01009188 - expect-netscaler-cip layer4 :
9189 configures the client-facing connection to receive a NetScaler Client
9190 IP insertion protocol header before any byte is read from the socket.
9191 This is equivalent to having the "accept-netscaler-cip" keyword on the
9192 "bind" line, except that using the TCP rule allows the PROXY protocol
9193 to be accepted only for certain IP address ranges using an ACL. This
9194 is convenient when multiple layers of load balancers are passed
9195 through by traffic coming from public hosts.
9196
Willy Tarreau18bf01e2014-06-13 16:18:52 +02009197 - capture <sample> len <length> :
9198 This only applies to "tcp-request content" rules. It captures sample
9199 expression <sample> from the request buffer, and converts it to a
9200 string of at most <len> characters. The resulting string is stored into
9201 the next request "capture" slot, so it will possibly appear next to
9202 some captured HTTP headers. It will then automatically appear in the
9203 logs, and it will be possible to extract it using sample fetch rules to
9204 feed it into headers or anything. The length should be limited given
9205 that this size will be allocated for each capture during the whole
Willy Tarreaua9083d02015-05-08 15:27:59 +02009206 session life. Please check section 7.3 (Fetching samples) and "capture
9207 request header" for more information.
Willy Tarreau18bf01e2014-06-13 16:18:52 +02009208
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009209 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] :
Willy Tarreaue9656522010-08-17 15:40:09 +02009210 enables tracking of sticky counters from current connection. These
Willy Tarreau09448f72014-06-25 18:12:15 +02009211 rules do not stop evaluation and do not change default action. 3 sets
Willy Tarreaue9656522010-08-17 15:40:09 +02009212 of counters may be simultaneously tracked by the same connection. The
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009213 first "track-sc0" rule executed enables tracking of the counters of the
9214 specified table as the first set. The first "track-sc1" rule executed
Willy Tarreaue9656522010-08-17 15:40:09 +02009215 enables tracking of the counters of the specified table as the second
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009216 set. The first "track-sc2" rule executed enables tracking of the
9217 counters of the specified table as the third set. It is a recommended
9218 practice to use the first set of counters for the per-frontend counters
9219 and the second set for the per-backend ones. But this is just a
9220 guideline, all may be used everywhere.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009221
Willy Tarreaue9656522010-08-17 15:40:09 +02009222 These actions take one or two arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02009223 <key> is mandatory, and is a sample expression rule as described
Willy Tarreau74ca5042013-06-11 23:12:07 +02009224 in section 7.3. It describes what elements of the incoming
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009225 request or connection will be analysed, extracted, combined,
9226 and used to select which table entry to update the counters.
9227 Note that "tcp-request connection" cannot use content-based
9228 fetches.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009229
Willy Tarreaue9656522010-08-17 15:40:09 +02009230 <table> is an optional table to be used instead of the default one,
9231 which is the stick-table declared in the current proxy. All
9232 the counters for the matches and updates for the key will
9233 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009234
Willy Tarreaue9656522010-08-17 15:40:09 +02009235 Once a "track-sc*" rule is executed, the key is looked up in the table
9236 and if it is not found, an entry is allocated for it. Then a pointer to
9237 that entry is kept during all the session's life, and this entry's
9238 counters are updated as often as possible, every time the session's
9239 counters are updated, and also systematically when the session ends.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009240 Counters are only updated for events that happen after the tracking has
9241 been started. For example, connection counters will not be updated when
9242 tracking layer 7 information, since the connection event happens before
9243 layer7 information is extracted.
9244
Willy Tarreaue9656522010-08-17 15:40:09 +02009245 If the entry tracks concurrent connection counters, one connection is
9246 counted for as long as the entry is tracked, and the entry will not
9247 expire during that time. Tracking counters also provides a performance
9248 advantage over just checking the keys, because only one table lookup is
9249 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009250
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02009251 - sc-inc-gpc0(<sc-id>):
9252 The "sc-inc-gpc0" increments the GPC0 counter according to the sticky
9253 counter designated by <sc-id>. If an error occurs, this action silently
9254 fails and the actions evaluation continues.
9255
Thierry FOURNIER236657b2015-08-19 08:25:14 +02009256 - sc-set-gpt0(<sc-id>) <int>:
9257 This action sets the GPT0 tag according to the sticky counter designated
9258 by <sc-id> and the value of <int>. The expected result is a boolean. If
9259 an error occurs, this action silently fails and the actions evaluation
9260 continues.
9261
William Lallemand2e785f22016-05-25 01:48:42 +02009262 - set-src <expr> :
9263 Is used to set the source IP address to the value of specified
9264 expression. Useful if you want to mask source IP for privacy.
9265 If you want to provide an IP from a HTTP header use "http-request
9266 set-src"
9267
9268 <expr> Is a standard HAProxy expression formed by a sample-fetch
9269 followed by some converters.
9270
9271 Example:
9272
9273 tcp-request connection set-src src,ipmask(24)
9274
Willy Tarreau0c630532016-10-21 17:52:58 +02009275 When possible, set-src preserves the original source port as long as the
9276 address family allows it, otherwise the source port is set to 0.
William Lallemand2e785f22016-05-25 01:48:42 +02009277
William Lallemand44be6402016-05-25 01:51:35 +02009278 - set-src-port <expr> :
9279 Is used to set the source port address to the value of specified
9280 expression.
9281
9282 <expr> Is a standard HAProxy expression formed by a sample-fetch
9283 followed by some converters.
9284
9285 Example:
9286
9287 tcp-request connection set-src-port int(4000)
9288
Willy Tarreau0c630532016-10-21 17:52:58 +02009289 When possible, set-src-port preserves the original source address as long
9290 as the address family supports a port, otherwise it forces the source
9291 address to IPv4 "0.0.0.0" before rewriting the port.
William Lallemand44be6402016-05-25 01:51:35 +02009292
William Lallemand13e9b0c2016-05-25 02:34:07 +02009293 - set-dst <expr> :
9294 Is used to set the destination IP address to the value of specified
9295 expression. Useful if you want to mask IP for privacy in log.
9296 If you want to provide an IP from a HTTP header use "http-request
9297 set-dst". If you want to connect to the new address/port, use
9298 '0.0.0.0:0' as a server address in the backend.
9299
9300 <expr> Is a standard HAProxy expression formed by a sample-fetch
9301 followed by some converters.
9302
9303 Example:
9304
9305 tcp-request connection set-dst dst,ipmask(24)
9306 tcp-request connection set-dst ipv4(10.0.0.1)
9307
Willy Tarreau0c630532016-10-21 17:52:58 +02009308 When possible, set-dst preserves the original destination port as long as
9309 the address family allows it, otherwise the destination port is set to 0.
9310
William Lallemand13e9b0c2016-05-25 02:34:07 +02009311 - set-dst-port <expr> :
9312 Is used to set the destination port address to the value of specified
9313 expression. If you want to connect to the new address/port, use
9314 '0.0.0.0:0' as a server address in the backend.
9315
9316
9317 <expr> Is a standard HAProxy expression formed by a sample-fetch
9318 followed by some converters.
9319
9320 Example:
9321
9322 tcp-request connection set-dst-port int(4000)
9323
Willy Tarreau0c630532016-10-21 17:52:58 +02009324 When possible, set-dst-port preserves the original destination address as
9325 long as the address family supports a port, otherwise it forces the
9326 destination address to IPv4 "0.0.0.0" before rewriting the port.
9327
Willy Tarreau2d392c22015-08-24 01:43:45 +02009328 - "silent-drop" :
9329 This stops the evaluation of the rules and makes the client-facing
9330 connection suddenly disappear using a system-dependant way that tries
9331 to prevent the client from being notified. The effect it then that the
9332 client still sees an established connection while there's none on
9333 HAProxy. The purpose is to achieve a comparable effect to "tarpit"
9334 except that it doesn't use any local resource at all on the machine
9335 running HAProxy. It can resist much higher loads than "tarpit", and
9336 slow down stronger attackers. It is important to undestand the impact
9337 of using this mechanism. All stateful equipments placed between the
9338 client and HAProxy (firewalls, proxies, load balancers) will also keep
9339 the established connection for a long time and may suffer from this
9340 action. On modern Linux systems running with enough privileges, the
9341 TCP_REPAIR socket option is used to block the emission of a TCP
9342 reset. On other systems, the socket's TTL is reduced to 1 so that the
9343 TCP reset doesn't pass the first router, though it's still delivered to
9344 local networks. Do not use it unless you fully understand how it works.
9345
Willy Tarreaue9656522010-08-17 15:40:09 +02009346 Note that the "if/unless" condition is optional. If no condition is set on
9347 the action, it is simply performed unconditionally. That can be useful for
9348 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009349
Willy Tarreaue9656522010-08-17 15:40:09 +02009350 Example: accept all connections from white-listed hosts, reject too fast
9351 connection without counting them, and track accepted connections.
9352 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009353
Willy Tarreaue9656522010-08-17 15:40:09 +02009354 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009355 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009356 tcp-request connection track-sc0 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009357
Willy Tarreaue9656522010-08-17 15:40:09 +02009358 Example: accept all connections from white-listed hosts, count all other
9359 connections and reject too fast ones. This results in abusive ones
9360 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009361
Willy Tarreaue9656522010-08-17 15:40:09 +02009362 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009363 tcp-request connection track-sc0 src
9364 tcp-request connection reject if { sc0_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009365
Willy Tarreau4f0d9192013-06-11 20:40:55 +02009366 Example: enable the PROXY protocol for traffic coming from all known proxies.
9367
9368 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
9369
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009370 See section 7 about ACL usage.
9371
Willy Tarreau4f614292016-10-21 17:49:36 +02009372 See also : "tcp-request session", "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009373
9374
Willy Tarreaue9656522010-08-17 15:40:09 +02009375tcp-request content <action> [{if | unless} <condition>]
9376 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +02009377 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02009378 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +02009379 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +02009380 <action> defines the action to perform if the condition applies. See
9381 below.
Willy Tarreau62644772008-07-16 18:36:06 +02009382
Willy Tarreaue9656522010-08-17 15:40:09 +02009383 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +02009384
Willy Tarreaue9656522010-08-17 15:40:09 +02009385 A request's contents can be analysed at an early stage of request processing
9386 called "TCP content inspection". During this stage, ACL-based rules are
9387 evaluated every time the request contents are updated, until either an
9388 "accept" or a "reject" rule matches, or the TCP request inspection delay
9389 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +02009390
Willy Tarreaue9656522010-08-17 15:40:09 +02009391 The first difference between these rules and "tcp-request connection" rules
9392 is that "tcp-request content" rules can make use of contents to take a
9393 decision. Most often, these decisions will consider a protocol recognition or
9394 validity. The second difference is that content-based rules can be used in
Willy Tarreauf3338342014-01-28 21:40:28 +01009395 both frontends and backends. In case of HTTP keep-alive with the client, all
9396 tcp-request content rules are evaluated again, so haproxy keeps a record of
9397 what sticky counters were assigned by a "tcp-request connection" versus a
9398 "tcp-request content" rule, and flushes all the content-related ones after
9399 processing an HTTP request, so that they may be evaluated again by the rules
9400 being evaluated again for the next request. This is of particular importance
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009401 when the rule tracks some L7 information or when it is conditioned by an
Willy Tarreauf3338342014-01-28 21:40:28 +01009402 L7-based ACL, since tracking may change between requests.
Willy Tarreau62644772008-07-16 18:36:06 +02009403
Willy Tarreaue9656522010-08-17 15:40:09 +02009404 Content-based rules are evaluated in their exact declaration order. If no
9405 rule matches or if there is no rule, the default action is to accept the
9406 contents. There is no specific limit to the number of rules which may be
9407 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +02009408
Thierry FOURNIER236657b2015-08-19 08:25:14 +02009409 Several types of actions are supported :
Willy Tarreau18bf01e2014-06-13 16:18:52 +02009410 - accept : the request is accepted
9411 - reject : the request is rejected and the connection is closed
9412 - capture : the specified sample expression is captured
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009413 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02009414 - sc-inc-gpc0(<sc-id>)
Thierry Fournierb9125672016-03-29 19:34:37 +02009415 - sc-set-gpt0(<sc-id>) <int>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009416 - set-var(<var-name>) <expr>
Christopher Faulet85d79c92016-11-09 16:54:56 +01009417 - unset-var(<var-name>)
Willy Tarreau2d392c22015-08-24 01:43:45 +02009418 - silent-drop
Christopher Faulet76c09ef2017-09-21 11:03:52 +02009419 - send-spoe-group <engin-name> <group-name>
Willy Tarreau62644772008-07-16 18:36:06 +02009420
Willy Tarreaue9656522010-08-17 15:40:09 +02009421 They have the same meaning as their counter-parts in "tcp-request connection"
9422 so please refer to that section for a complete description.
Willy Tarreau62644772008-07-16 18:36:06 +02009423
Willy Tarreauf3338342014-01-28 21:40:28 +01009424 While there is nothing mandatory about it, it is recommended to use the
9425 track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request
9426 content" rules in the frontend, and track-sc2 for "tcp-request content"
9427 rules in the backend, because that makes the configuration more readable
9428 and easier to troubleshoot, but this is just a guideline and all counters
9429 may be used everywhere.
Willy Tarreau62644772008-07-16 18:36:06 +02009430
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009431 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +02009432 the action, it is simply performed unconditionally. That can be useful for
9433 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +02009434
Willy Tarreaue9656522010-08-17 15:40:09 +02009435 It is perfectly possible to match layer 7 contents with "tcp-request content"
Willy Tarreauc0239e02012-04-16 14:42:55 +02009436 rules, since HTTP-specific ACL matches are able to preliminarily parse the
9437 contents of a buffer before extracting the required data. If the buffered
9438 contents do not parse as a valid HTTP message, then the ACL does not match.
9439 The parser which is involved there is exactly the same as for all other HTTP
Willy Tarreauf3338342014-01-28 21:40:28 +01009440 processing, so there is no risk of parsing something differently. In an HTTP
9441 backend connected to from an HTTP frontend, it is guaranteed that HTTP
9442 contents will always be immediately present when the rule is evaluated first.
Willy Tarreau62644772008-07-16 18:36:06 +02009443
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009444 Tracking layer7 information is also possible provided that the information
Willy Tarreau4d54c7c2014-09-16 15:48:15 +02009445 are present when the rule is processed. The rule processing engine is able to
9446 wait until the inspect delay expires when the data to be tracked is not yet
9447 available.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009448
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009449 The "set-var" is used to set the content of a variable. The variable is
Willy Tarreau4f614292016-10-21 17:49:36 +02009450 declared inline. For "tcp-request session" rules, only session-level
9451 variables can be used, without any layer7 contents.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009452
Daniel Schneller0b547052016-03-21 20:46:57 +01009453 <var-name> The name of the variable starts with an indication about
9454 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +01009455 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +01009456 "sess" : the variable is shared with the whole session
9457 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009458 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +01009459 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009460 processing
Daniel Schneller0b547052016-03-21 20:46:57 +01009461 "res" : the variable is shared only during response
9462 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009463 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +01009464 The name may only contain characters 'a-z', 'A-Z', '0-9',
9465 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009466
9467 <expr> Is a standard HAProxy expression formed by a sample-fetch
9468 followed by some converters.
9469
Christopher Faulet85d79c92016-11-09 16:54:56 +01009470 The "unset-var" is used to unset a variable. See above for details about
9471 <var-name>.
9472
Christopher Faulet76c09ef2017-09-21 11:03:52 +02009473 The "send-spoe-group" is used to trigger sending of a group of SPOE
9474 messages. To do so, the SPOE engine used to send messages must be defined, as
9475 well as the SPOE group to send. Of course, the SPOE engine must refer to an
9476 existing SPOE filter. If not engine name is provided on the SPOE filter line,
9477 the SPOE agent name must be used.
9478
9479 <engine-name> The SPOE engine name.
9480
9481 <group-name> The SPOE group name as specified in the engine configuration.
9482
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009483 Example:
9484
9485 tcp-request content set-var(sess.my_var) src
Christopher Faulet85d79c92016-11-09 16:54:56 +01009486 tcp-request content unset-var(sess.my_var2)
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009487
Willy Tarreau62644772008-07-16 18:36:06 +02009488 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +02009489 # Accept HTTP requests containing a Host header saying "example.com"
9490 # and reject everything else.
9491 acl is_host_com hdr(Host) -i example.com
9492 tcp-request inspect-delay 30s
Willy Tarreauc0239e02012-04-16 14:42:55 +02009493 tcp-request content accept if is_host_com
Willy Tarreaue9656522010-08-17 15:40:09 +02009494 tcp-request content reject
9495
9496 Example:
Willy Tarreau62644772008-07-16 18:36:06 +02009497 # reject SMTP connection if client speaks first
9498 tcp-request inspect-delay 30s
9499 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009500 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +02009501
9502 # Forward HTTPS connection only if client speaks
9503 tcp-request inspect-delay 30s
9504 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02009505 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +02009506 tcp-request content reject
9507
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009508 Example:
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009509 # Track the last IP(stick-table type string) from X-Forwarded-For
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009510 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +02009511 tcp-request content track-sc0 hdr(x-forwarded-for,-1)
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009512 # Or track the last IP(stick-table type ip|ipv6) from X-Forwarded-For
9513 tcp-request content track-sc0 req.hdr_ip(x-forwarded-for,-1)
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009514
9515 Example:
9516 # track request counts per "base" (concatenation of Host+URL)
9517 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +02009518 tcp-request content track-sc0 base table req-rate
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01009519
Willy Tarreaue9656522010-08-17 15:40:09 +02009520 Example: track per-frontend and per-backend counters, block abusers at the
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009521 frontend when the backend detects abuse(and marks gpc0).
Willy Tarreaue9656522010-08-17 15:40:09 +02009522
9523 frontend http
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009524 # Use General Purpose Couter 0 in SC0 as a global abuse counter
Willy Tarreaue9656522010-08-17 15:40:09 +02009525 # protecting all our sites
9526 stick-table type ip size 1m expire 5m store gpc0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009527 tcp-request connection track-sc0 src
9528 tcp-request connection reject if { sc0_get_gpc0 gt 0 }
Willy Tarreaue9656522010-08-17 15:40:09 +02009529 ...
9530 use_backend http_dynamic if { path_end .php }
9531
9532 backend http_dynamic
9533 # if a source makes too fast requests to this dynamic site (tracked
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009534 # by SC1), block it globally in the frontend.
Willy Tarreaue9656522010-08-17 15:40:09 +02009535 stick-table type ip size 1m expire 5m store http_req_rate(10s)
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009536 acl click_too_fast sc1_http_req_rate gt 10
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03009537 acl mark_as_abuser sc0_inc_gpc0(http) gt 0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009538 tcp-request content track-sc1 src
Willy Tarreaue9656522010-08-17 15:40:09 +02009539 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +02009540
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009541 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02009542
Jarno Huuskonen95b012b2017-04-06 13:59:14 +03009543 See also : "tcp-request connection", "tcp-request session",
9544 "tcp-request inspect-delay", and "http-request".
Willy Tarreau62644772008-07-16 18:36:06 +02009545
9546
9547tcp-request inspect-delay <timeout>
9548 Set the maximum allowed time to wait for data during content inspection
9549 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02009550 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +02009551 Arguments :
9552 <timeout> is the timeout value specified in milliseconds by default, but
9553 can be in any other unit if the number is suffixed by the unit,
9554 as explained at the top of this document.
9555
9556 People using haproxy primarily as a TCP relay are often worried about the
9557 risk of passing any type of protocol to a server without any analysis. In
9558 order to be able to analyze the request contents, we must first withhold
9559 the data then analyze them. This statement simply enables withholding of
9560 data for at most the specified amount of time.
9561
Willy Tarreaufb356202010-08-03 14:02:05 +02009562 TCP content inspection applies very early when a connection reaches a
9563 frontend, then very early when the connection is forwarded to a backend. This
9564 means that a connection may experience a first delay in the frontend and a
9565 second delay in the backend if both have tcp-request rules.
9566
Willy Tarreau62644772008-07-16 18:36:06 +02009567 Note that when performing content inspection, haproxy will evaluate the whole
9568 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009569 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +02009570 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +01009571 contents are definitive. If no delay is set, haproxy will not wait at all
9572 and will immediately apply a verdict based on the available information.
9573 Obviously this is unlikely to be very useful and might even be racy, so such
9574 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +02009575
9576 As soon as a rule matches, the request is released and continues as usual. If
9577 the timeout is reached and no rule matches, the default policy will be to let
9578 it pass through unaffected.
9579
9580 For most protocols, it is enough to set it to a few seconds, as most clients
9581 send the full request immediately upon connection. Add 3 or more seconds to
9582 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +01009583 to use large values, for instance to ensure that the client never talks
Willy Tarreau62644772008-07-16 18:36:06 +02009584 before the server (eg: SMTP), or to wait for a client to talk before passing
9585 data to the server (eg: SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +02009586 least the inspection delay, otherwise it will expire first. If the client
9587 closes the connection or if the buffer is full, the delay immediately expires
9588 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +02009589
Willy Tarreau55165fe2009-05-10 12:02:55 +02009590 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +02009591 "timeout client".
9592
9593
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009594tcp-response content <action> [{if | unless} <condition>]
9595 Perform an action on a session response depending on a layer 4-7 condition
9596 May be used in sections : defaults | frontend | listen | backend
9597 no | no | yes | yes
9598 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +02009599 <action> defines the action to perform if the condition applies. See
9600 below.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009601
9602 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
9603
9604 Response contents can be analysed at an early stage of response processing
9605 called "TCP content inspection". During this stage, ACL-based rules are
9606 evaluated every time the response contents are updated, until either an
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02009607 "accept", "close" or a "reject" rule matches, or a TCP response inspection
9608 delay is set and expires with no matching rule.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009609
9610 Most often, these decisions will consider a protocol recognition or validity.
9611
9612 Content-based rules are evaluated in their exact declaration order. If no
9613 rule matches or if there is no rule, the default action is to accept the
9614 contents. There is no specific limit to the number of rules which may be
9615 inserted.
9616
Thierry FOURNIER236657b2015-08-19 08:25:14 +02009617 Several types of actions are supported :
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009618 - accept :
9619 accepts the response if the condition is true (when used with "if")
9620 or false (when used with "unless"). The first such rule executed ends
9621 the rules evaluation.
9622
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02009623 - close :
9624 immediately closes the connection with the server if the condition is
9625 true (when used with "if"), or false (when used with "unless"). The
9626 first such rule executed ends the rules evaluation. The main purpose of
9627 this action is to force a connection to be finished between a client
9628 and a server after an exchange when the application protocol expects
9629 some long time outs to elapse first. The goal is to eliminate idle
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009630 connections which take significant resources on servers with certain
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02009631 protocols.
9632
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009633 - reject :
9634 rejects the response if the condition is true (when used with "if")
9635 or false (when used with "unless"). The first such rule executed ends
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009636 the rules evaluation. Rejected session are immediately closed.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009637
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009638 - set-var(<var-name>) <expr>
9639 Sets a variable.
9640
Christopher Faulet85d79c92016-11-09 16:54:56 +01009641 - unset-var(<var-name>)
9642 Unsets a variable.
9643
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02009644 - sc-inc-gpc0(<sc-id>):
9645 This action increments the GPC0 counter according to the sticky
9646 counter designated by <sc-id>. If an error occurs, this action fails
9647 silently and the actions evaluation continues.
9648
Thierry FOURNIER236657b2015-08-19 08:25:14 +02009649 - sc-set-gpt0(<sc-id>) <int> :
9650 This action sets the GPT0 tag according to the sticky counter designated
9651 by <sc-id> and the value of <int>. The expected result is a boolean. If
9652 an error occurs, this action silently fails and the actions evaluation
9653 continues.
9654
Willy Tarreau2d392c22015-08-24 01:43:45 +02009655 - "silent-drop" :
9656 This stops the evaluation of the rules and makes the client-facing
9657 connection suddenly disappear using a system-dependant way that tries
9658 to prevent the client from being notified. The effect it then that the
9659 client still sees an established connection while there's none on
9660 HAProxy. The purpose is to achieve a comparable effect to "tarpit"
9661 except that it doesn't use any local resource at all on the machine
9662 running HAProxy. It can resist much higher loads than "tarpit", and
9663 slow down stronger attackers. It is important to undestand the impact
9664 of using this mechanism. All stateful equipments placed between the
9665 client and HAProxy (firewalls, proxies, load balancers) will also keep
9666 the established connection for a long time and may suffer from this
9667 action. On modern Linux systems running with enough privileges, the
9668 TCP_REPAIR socket option is used to block the emission of a TCP
9669 reset. On other systems, the socket's TTL is reduced to 1 so that the
9670 TCP reset doesn't pass the first router, though it's still delivered to
9671 local networks. Do not use it unless you fully understand how it works.
9672
Christopher Faulet76c09ef2017-09-21 11:03:52 +02009673 - send-spoe-group <engine-name> <group-name>
9674 Send a group of SPOE messages.
9675
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009676 Note that the "if/unless" condition is optional. If no condition is set on
9677 the action, it is simply performed unconditionally. That can be useful for
9678 for changing the default action to a reject.
9679
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009680 It is perfectly possible to match layer 7 contents with "tcp-response
9681 content" rules, but then it is important to ensure that a full response has
9682 been buffered, otherwise no contents will match. In order to achieve this,
9683 the best solution involves detecting the HTTP protocol during the inspection
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009684 period.
9685
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009686 The "set-var" is used to set the content of a variable. The variable is
9687 declared inline.
9688
Daniel Schneller0b547052016-03-21 20:46:57 +01009689 <var-name> The name of the variable starts with an indication about
9690 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +01009691 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +01009692 "sess" : the variable is shared with the whole session
9693 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009694 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +01009695 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009696 processing
Daniel Schneller0b547052016-03-21 20:46:57 +01009697 "res" : the variable is shared only during response
9698 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009699 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +01009700 The name may only contain characters 'a-z', 'A-Z', '0-9',
9701 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02009702
9703 <expr> Is a standard HAProxy expression formed by a sample-fetch
9704 followed by some converters.
9705
9706 Example:
9707
9708 tcp-request content set-var(sess.my_var) src
9709
Christopher Faulet85d79c92016-11-09 16:54:56 +01009710 The "unset-var" is used to unset a variable. See above for details about
9711 <var-name>.
9712
9713 Example:
9714
9715 tcp-request content unset-var(sess.my_var)
9716
Christopher Faulet76c09ef2017-09-21 11:03:52 +02009717 The "send-spoe-group" is used to trigger sending of a group of SPOE
9718 messages. To do so, the SPOE engine used to send messages must be defined, as
9719 well as the SPOE group to send. Of course, the SPOE engine must refer to an
9720 existing SPOE filter. If not engine name is provided on the SPOE filter line,
9721 the SPOE agent name must be used.
9722
9723 <engine-name> The SPOE engine name.
9724
9725 <group-name> The SPOE group name as specified in the engine configuration.
9726
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009727 See section 7 about ACL usage.
9728
9729 See also : "tcp-request content", "tcp-response inspect-delay"
9730
9731
Willy Tarreau4f614292016-10-21 17:49:36 +02009732tcp-request session <action> [{if | unless} <condition>]
9733 Perform an action on a validated session depending on a layer 5 condition
9734 May be used in sections : defaults | frontend | listen | backend
9735 no | yes | yes | no
9736 Arguments :
9737 <action> defines the action to perform if the condition applies. See
9738 below.
9739
9740 <condition> is a standard layer5-only ACL-based condition (see section 7).
9741
9742 Once a session is validated, (ie. after all handshakes have been completed),
9743 it is possible to evaluate some conditions to decide whether this session
9744 must be accepted or dropped or have its counters tracked. Those conditions
9745 cannot make use of any data contents because no buffers are allocated yet and
9746 the processing cannot wait at this stage. The main use case it to copy some
9747 early information into variables (since variables are accessible in the
9748 session), or to keep track of some information collected after the handshake,
9749 such as SSL-level elements (SNI, ciphers, client cert's CN) or information
9750 from the PROXY protocol header (eg: track a source forwarded this way). The
9751 extracted information can thus be copied to a variable or tracked using
9752 "track-sc" rules. Of course it is also possible to decide to accept/reject as
9753 with other rulesets. Most operations performed here could also be performed
9754 in "tcp-request content" rules, except that in HTTP these rules are evaluated
9755 for each new request, and that might not always be acceptable. For example a
9756 rule might increment a counter on each evaluation. It would also be possible
9757 that a country is resolved by geolocation from the source IP address,
9758 assigned to a session-wide variable, then the source address rewritten from
9759 an HTTP header for all requests. If some contents need to be inspected in
9760 order to take the decision, the "tcp-request content" statements must be used
9761 instead.
9762
9763 The "tcp-request session" rules are evaluated in their exact declaration
9764 order. If no rule matches or if there is no rule, the default action is to
9765 accept the incoming session. There is no specific limit to the number of
9766 rules which may be inserted.
9767
9768 Several types of actions are supported :
9769 - accept : the request is accepted
9770 - reject : the request is rejected and the connection is closed
9771 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
9772 - sc-inc-gpc0(<sc-id>)
9773 - sc-set-gpt0(<sc-id>) <int>
9774 - set-var(<var-name>) <expr>
Christopher Faulet85d79c92016-11-09 16:54:56 +01009775 - unset-var(<var-name>)
Willy Tarreau4f614292016-10-21 17:49:36 +02009776 - silent-drop
9777
9778 These actions have the same meaning as their respective counter-parts in
9779 "tcp-request connection" and "tcp-request content", so please refer to these
9780 sections for a complete description.
9781
9782 Note that the "if/unless" condition is optional. If no condition is set on
9783 the action, it is simply performed unconditionally. That can be useful for
9784 "track-sc*" actions as well as for changing the default action to a reject.
9785
9786 Example: track the original source address by default, or the one advertised
9787 in the PROXY protocol header for connection coming from the local
9788 proxies. The first connection-level rule enables receipt of the
9789 PROXY protocol for these ones, the second rule tracks whatever
9790 address we decide to keep after optional decoding.
9791
9792 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
9793 tcp-request session track-sc0 src
9794
9795 Example: accept all sessions from white-listed hosts, reject too fast
9796 sessions without counting them, and track accepted sessions.
9797 This results in session rate being capped from abusive sources.
9798
9799 tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
9800 tcp-request session reject if { src_sess_rate gt 10 }
9801 tcp-request session track-sc0 src
9802
9803 Example: accept all sessions from white-listed hosts, count all other
9804 sessions and reject too fast ones. This results in abusive ones
9805 being blocked as long as they don't slow down.
9806
9807 tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
9808 tcp-request session track-sc0 src
9809 tcp-request session reject if { sc0_sess_rate gt 10 }
9810
9811 See section 7 about ACL usage.
9812
9813 See also : "tcp-request connection", "tcp-request content", "stick-table"
9814
9815
Emeric Brun0a3b67f2010-09-24 15:34:53 +02009816tcp-response inspect-delay <timeout>
9817 Set the maximum allowed time to wait for a response during content inspection
9818 May be used in sections : defaults | frontend | listen | backend
9819 no | no | yes | yes
9820 Arguments :
9821 <timeout> is the timeout value specified in milliseconds by default, but
9822 can be in any other unit if the number is suffixed by the unit,
9823 as explained at the top of this document.
9824
9825 See also : "tcp-response content", "tcp-request inspect-delay".
9826
9827
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01009828timeout check <timeout>
9829 Set additional check timeout, but only after a connection has been already
9830 established.
9831
9832 May be used in sections: defaults | frontend | listen | backend
9833 yes | no | yes | yes
9834 Arguments:
9835 <timeout> is the timeout value specified in milliseconds by default, but
9836 can be in any other unit if the number is suffixed by the unit,
9837 as explained at the top of this document.
9838
9839 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
9840 for check and "timeout check" as an additional read timeout. The "min" is
9841 used so that people running with *very* long "timeout connect" (eg. those
9842 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +01009843 (Please also note that there is no valid reason to have such long connect
9844 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
9845 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01009846
9847 If "timeout check" is not set haproxy uses "inter" for complete check
9848 timeout (connect + read) exactly like all <1.3.15 version.
9849
9850 In most cases check request is much simpler and faster to handle than normal
9851 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +01009852 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01009853
9854 This parameter is specific to backends, but can be specified once for all in
9855 "defaults" sections. This is in fact one of the easiest solutions not to
9856 forget about it.
9857
Willy Tarreau41a340d2008-01-22 12:25:31 +01009858 See also: "timeout connect", "timeout queue", "timeout server",
9859 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01009860
9861
Willy Tarreau0ba27502007-12-24 16:55:16 +01009862timeout client <timeout>
9863timeout clitimeout <timeout> (deprecated)
9864 Set the maximum inactivity time on the client side.
9865 May be used in sections : defaults | frontend | listen | backend
9866 yes | yes | yes | no
9867 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01009868 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01009869 can be in any other unit if the number is suffixed by the unit,
9870 as explained at the top of this document.
9871
9872 The inactivity timeout applies when the client is expected to acknowledge or
9873 send data. In HTTP mode, this timeout is particularly important to consider
9874 during the first phase, when the client sends the request, and during the
Baptiste Assmann2e1941e2016-03-06 23:24:12 +01009875 response while it is reading data sent by the server. That said, for the
9876 first phase, it is preferable to set the "timeout http-request" to better
9877 protect HAProxy from Slowloris like attacks. The value is specified in
9878 milliseconds by default, but can be in any other unit if the number is
Willy Tarreau0ba27502007-12-24 16:55:16 +01009879 suffixed by the unit, as specified at the top of this document. In TCP mode
9880 (and to a lesser extent, in HTTP mode), it is highly recommended that the
9881 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01009882 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01009883 losses by specifying timeouts that are slightly above multiples of 3 seconds
Willy Tarreauce887fd2012-05-12 12:50:00 +02009884 (eg: 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
9885 sessions (eg: WebSocket and HTTP), it's worth considering "timeout tunnel",
Willy Tarreau05cdd962014-05-10 14:30:07 +02009886 which overrides "timeout client" and "timeout server" for tunnels, as well as
9887 "timeout client-fin" for half-closed connections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01009888
9889 This parameter is specific to frontends, but can be specified once for all in
9890 "defaults" sections. This is in fact one of the easiest solutions not to
9891 forget about it. An unspecified timeout results in an infinite timeout, which
9892 is not recommended. Such a usage is accepted and works but reports a warning
9893 during startup because it may results in accumulation of expired sessions in
9894 the system if the system's timeouts are not configured either.
9895
Willy Tarreau95c4e142017-11-26 12:18:55 +01009896 This also applies to HTTP/2 connections, which will be closed with GOAWAY.
Lukas Tribus75df9d72017-11-24 19:05:12 +01009897
Willy Tarreau0ba27502007-12-24 16:55:16 +01009898 This parameter replaces the old, deprecated "clitimeout". It is recommended
9899 to use it to write new configurations. The form "timeout clitimeout" is
9900 provided only by backwards compatibility but its use is strongly discouraged.
9901
Baptiste Assmann2e1941e2016-03-06 23:24:12 +01009902 See also : "clitimeout", "timeout server", "timeout tunnel",
9903 "timeout http-request".
Willy Tarreau0ba27502007-12-24 16:55:16 +01009904
9905
Willy Tarreau05cdd962014-05-10 14:30:07 +02009906timeout client-fin <timeout>
9907 Set the inactivity timeout on the client side for half-closed connections.
9908 May be used in sections : defaults | frontend | listen | backend
9909 yes | yes | yes | no
9910 Arguments :
9911 <timeout> is the timeout value specified in milliseconds by default, but
9912 can be in any other unit if the number is suffixed by the unit,
9913 as explained at the top of this document.
9914
9915 The inactivity timeout applies when the client is expected to acknowledge or
9916 send data while one direction is already shut down. This timeout is different
9917 from "timeout client" in that it only applies to connections which are closed
9918 in one direction. This is particularly useful to avoid keeping connections in
9919 FIN_WAIT state for too long when clients do not disconnect cleanly. This
9920 problem is particularly common long connections such as RDP or WebSocket.
9921 Note that this timeout can override "timeout tunnel" when a connection shuts
Willy Tarreau599391a2017-11-24 10:16:00 +01009922 down in one direction. It is applied to idle HTTP/2 connections once a GOAWAY
9923 frame was sent, often indicating an expectation that the connection quickly
9924 ends.
Willy Tarreau05cdd962014-05-10 14:30:07 +02009925
9926 This parameter is specific to frontends, but can be specified once for all in
9927 "defaults" sections. By default it is not set, so half-closed connections
9928 will use the other timeouts (timeout.client or timeout.tunnel).
9929
9930 See also : "timeout client", "timeout server-fin", and "timeout tunnel".
9931
9932
Willy Tarreau0ba27502007-12-24 16:55:16 +01009933timeout connect <timeout>
9934timeout contimeout <timeout> (deprecated)
9935 Set the maximum time to wait for a connection attempt to a server to succeed.
9936 May be used in sections : defaults | frontend | listen | backend
9937 yes | no | yes | yes
9938 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01009939 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01009940 can be in any other unit if the number is suffixed by the unit,
9941 as explained at the top of this document.
9942
9943 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01009944 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01009945 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01009946 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01009947 connect timeout also presets both queue and tarpit timeouts to the same value
9948 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +01009949
9950 This parameter is specific to backends, but can be specified once for all in
9951 "defaults" sections. This is in fact one of the easiest solutions not to
9952 forget about it. An unspecified timeout results in an infinite timeout, which
9953 is not recommended. Such a usage is accepted and works but reports a warning
9954 during startup because it may results in accumulation of failed sessions in
9955 the system if the system's timeouts are not configured either.
9956
9957 This parameter replaces the old, deprecated "contimeout". It is recommended
9958 to use it to write new configurations. The form "timeout contimeout" is
9959 provided only by backwards compatibility but its use is strongly discouraged.
9960
Willy Tarreau41a340d2008-01-22 12:25:31 +01009961 See also: "timeout check", "timeout queue", "timeout server", "contimeout",
9962 "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +01009963
9964
Willy Tarreaub16a5742010-01-10 14:46:16 +01009965timeout http-keep-alive <timeout>
9966 Set the maximum allowed time to wait for a new HTTP request to appear
9967 May be used in sections : defaults | frontend | listen | backend
9968 yes | yes | yes | yes
9969 Arguments :
9970 <timeout> is the timeout value specified in milliseconds by default, but
9971 can be in any other unit if the number is suffixed by the unit,
9972 as explained at the top of this document.
9973
9974 By default, the time to wait for a new request in case of keep-alive is set
9975 by "timeout http-request". However this is not always convenient because some
9976 people want very short keep-alive timeouts in order to release connections
9977 faster, and others prefer to have larger ones but still have short timeouts
9978 once the request has started to present itself.
9979
9980 The "http-keep-alive" timeout covers these needs. It will define how long to
9981 wait for a new HTTP request to start coming after a response was sent. Once
9982 the first byte of request has been seen, the "http-request" timeout is used
9983 to wait for the complete request to come. Note that empty lines prior to a
9984 new request do not refresh the timeout and are not counted as a new request.
9985
9986 There is also another difference between the two timeouts : when a connection
9987 expires during timeout http-keep-alive, no error is returned, the connection
9988 just closes. If the connection expires in "http-request" while waiting for a
9989 connection to complete, a HTTP 408 error is returned.
9990
9991 In general it is optimal to set this value to a few tens to hundreds of
9992 milliseconds, to allow users to fetch all objects of a page at once but
9993 without waiting for further clicks. Also, if set to a very small value (eg:
9994 1 millisecond) it will probably only accept pipelined requests but not the
9995 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +02009996 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +01009997
9998 If this parameter is not set, the "http-request" timeout applies, and if both
9999 are not set, "timeout client" still applies at the lower level. It should be
10000 set in the frontend to take effect, unless the frontend is in TCP mode, in
10001 which case the HTTP backend's timeout will be used.
10002
Willy Tarreau95c4e142017-11-26 12:18:55 +010010003 When using HTTP/2 "timeout client" is applied instead. This is so we can keep
10004 using short keep-alive timeouts in HTTP/1.1 while using longer ones in HTTP/2
Lukas Tribus75df9d72017-11-24 19:05:12 +010010005 (where we only have one connection per client and a connection setup).
10006
Willy Tarreaub16a5742010-01-10 14:46:16 +010010007 See also : "timeout http-request", "timeout client".
10008
10009
Willy Tarreau036fae02008-01-06 13:24:40 +010010010timeout http-request <timeout>
10011 Set the maximum allowed time to wait for a complete HTTP request
10012 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +020010013 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +010010014 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010010015 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +010010016 can be in any other unit if the number is suffixed by the unit,
10017 as explained at the top of this document.
10018
10019 In order to offer DoS protection, it may be required to lower the maximum
10020 accepted time to receive a complete HTTP request without affecting the client
10021 timeout. This helps protecting against established connections on which
10022 nothing is sent. The client timeout cannot offer a good protection against
10023 this abuse because it is an inactivity timeout, which means that if the
10024 attacker sends one character every now and then, the timeout will not
10025 trigger. With the HTTP request timeout, no matter what speed the client
Willy Tarreau2705a612014-05-23 17:38:34 +020010026 types, the request will be aborted if it does not complete in time. When the
10027 timeout expires, an HTTP 408 response is sent to the client to inform it
10028 about the problem, and the connection is closed. The logs will report
10029 termination codes "cR". Some recent browsers are having problems with this
10030 standard, well-documented behaviour, so it might be needed to hide the 408
Willy Tarreau0f228a02015-05-01 15:37:53 +020010031 code using "option http-ignore-probes" or "errorfile 408 /dev/null". See
10032 more details in the explanations of the "cR" termination code in section 8.5.
Willy Tarreau036fae02008-01-06 13:24:40 +010010033
Baptiste Assmanneccdf432015-10-28 13:49:01 +010010034 By default, this timeout only applies to the header part of the request,
10035 and not to any data. As soon as the empty line is received, this timeout is
10036 not used anymore. When combined with "option http-buffer-request", this
10037 timeout also applies to the body of the request..
10038 It is used again on keep-alive connections to wait for a second
Willy Tarreaub16a5742010-01-10 14:46:16 +010010039 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +010010040
10041 Generally it is enough to set it to a few seconds, as most clients send the
10042 full request immediately upon connection. Add 3 or more seconds to cover TCP
10043 retransmits but that's all. Setting it to very low values (eg: 50 ms) will
10044 generally work on local networks as long as there are no packet losses. This
10045 will prevent people from sending bare HTTP requests using telnet.
10046
10047 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +020010048 chunk of the incoming request. It should be set in the frontend to take
10049 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
10050 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +010010051
Willy Tarreau0f228a02015-05-01 15:37:53 +020010052 See also : "errorfile", "http-ignore-probes", "timeout http-keep-alive", and
Baptiste Assmanneccdf432015-10-28 13:49:01 +010010053 "timeout client", "option http-buffer-request".
Willy Tarreau036fae02008-01-06 13:24:40 +010010054
Willy Tarreau844e3c52008-01-11 16:28:18 +010010055
10056timeout queue <timeout>
10057 Set the maximum time to wait in the queue for a connection slot to be free
10058 May be used in sections : defaults | frontend | listen | backend
10059 yes | no | yes | yes
10060 Arguments :
10061 <timeout> is the timeout value specified in milliseconds by default, but
10062 can be in any other unit if the number is suffixed by the unit,
10063 as explained at the top of this document.
10064
10065 When a server's maxconn is reached, connections are left pending in a queue
10066 which may be server-specific or global to the backend. In order not to wait
10067 indefinitely, a timeout is applied to requests pending in the queue. If the
10068 timeout is reached, it is considered that the request will almost never be
10069 served, so it is dropped and a 503 error is returned to the client.
10070
10071 The "timeout queue" statement allows to fix the maximum time for a request to
10072 be left pending in a queue. If unspecified, the same value as the backend's
10073 connection timeout ("timeout connect") is used, for backwards compatibility
10074 with older versions with no "timeout queue" parameter.
10075
10076 See also : "timeout connect", "contimeout".
10077
10078
10079timeout server <timeout>
10080timeout srvtimeout <timeout> (deprecated)
10081 Set the maximum inactivity time on the server side.
10082 May be used in sections : defaults | frontend | listen | backend
10083 yes | no | yes | yes
10084 Arguments :
10085 <timeout> is the timeout value specified in milliseconds by default, but
10086 can be in any other unit if the number is suffixed by the unit,
10087 as explained at the top of this document.
10088
10089 The inactivity timeout applies when the server is expected to acknowledge or
10090 send data. In HTTP mode, this timeout is particularly important to consider
10091 during the first phase of the server's response, when it has to send the
10092 headers, as it directly represents the server's processing time for the
10093 request. To find out what value to put there, it's often good to start with
10094 what would be considered as unacceptable response times, then check the logs
10095 to observe the response time distribution, and adjust the value accordingly.
10096
10097 The value is specified in milliseconds by default, but can be in any other
10098 unit if the number is suffixed by the unit, as specified at the top of this
10099 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
10100 recommended that the client timeout remains equal to the server timeout in
10101 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010010102 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +010010103 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreauce887fd2012-05-12 12:50:00 +020010104 seconds (eg: 4 or 5 seconds minimum). If some long-lived sessions are mixed
10105 with short-lived sessions (eg: WebSocket and HTTP), it's worth considering
10106 "timeout tunnel", which overrides "timeout client" and "timeout server" for
10107 tunnels.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010108
10109 This parameter is specific to backends, but can be specified once for all in
10110 "defaults" sections. This is in fact one of the easiest solutions not to
10111 forget about it. An unspecified timeout results in an infinite timeout, which
10112 is not recommended. Such a usage is accepted and works but reports a warning
10113 during startup because it may results in accumulation of expired sessions in
10114 the system if the system's timeouts are not configured either.
10115
10116 This parameter replaces the old, deprecated "srvtimeout". It is recommended
10117 to use it to write new configurations. The form "timeout srvtimeout" is
10118 provided only by backwards compatibility but its use is strongly discouraged.
10119
Willy Tarreauce887fd2012-05-12 12:50:00 +020010120 See also : "srvtimeout", "timeout client" and "timeout tunnel".
Willy Tarreau844e3c52008-01-11 16:28:18 +010010121
Willy Tarreau05cdd962014-05-10 14:30:07 +020010122
10123timeout server-fin <timeout>
10124 Set the inactivity timeout on the server side for half-closed connections.
10125 May be used in sections : defaults | frontend | listen | backend
10126 yes | no | yes | yes
10127 Arguments :
10128 <timeout> is the timeout value specified in milliseconds by default, but
10129 can be in any other unit if the number is suffixed by the unit,
10130 as explained at the top of this document.
10131
10132 The inactivity timeout applies when the server is expected to acknowledge or
10133 send data while one direction is already shut down. This timeout is different
10134 from "timeout server" in that it only applies to connections which are closed
10135 in one direction. This is particularly useful to avoid keeping connections in
10136 FIN_WAIT state for too long when a remote server does not disconnect cleanly.
10137 This problem is particularly common long connections such as RDP or WebSocket.
10138 Note that this timeout can override "timeout tunnel" when a connection shuts
10139 down in one direction. This setting was provided for completeness, but in most
10140 situations, it should not be needed.
10141
10142 This parameter is specific to backends, but can be specified once for all in
10143 "defaults" sections. By default it is not set, so half-closed connections
10144 will use the other timeouts (timeout.server or timeout.tunnel).
10145
10146 See also : "timeout client-fin", "timeout server", and "timeout tunnel".
10147
Willy Tarreau844e3c52008-01-11 16:28:18 +010010148
10149timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +010010150 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +010010151 May be used in sections : defaults | frontend | listen | backend
10152 yes | yes | yes | yes
10153 Arguments :
10154 <timeout> is the tarpit duration specified in milliseconds by default, but
10155 can be in any other unit if the number is suffixed by the unit,
10156 as explained at the top of this document.
10157
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030010158 When a connection is tarpitted using "http-request tarpit" or
10159 "reqtarpit", it is maintained open with no activity for a certain
10160 amount of time, then closed. "timeout tarpit" defines how long it will
10161 be maintained open.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010162
10163 The value is specified in milliseconds by default, but can be in any other
10164 unit if the number is suffixed by the unit, as specified at the top of this
10165 document. If unspecified, the same value as the backend's connection timeout
10166 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +010010167 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010168
10169 See also : "timeout connect", "contimeout".
10170
10171
Willy Tarreauce887fd2012-05-12 12:50:00 +020010172timeout tunnel <timeout>
10173 Set the maximum inactivity time on the client and server side for tunnels.
10174 May be used in sections : defaults | frontend | listen | backend
10175 yes | no | yes | yes
10176 Arguments :
10177 <timeout> is the timeout value specified in milliseconds by default, but
10178 can be in any other unit if the number is suffixed by the unit,
10179 as explained at the top of this document.
10180
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010181 The tunnel timeout applies when a bidirectional connection is established
Willy Tarreauce887fd2012-05-12 12:50:00 +020010182 between a client and a server, and the connection remains inactive in both
10183 directions. This timeout supersedes both the client and server timeouts once
10184 the connection becomes a tunnel. In TCP, this timeout is used as soon as no
10185 analyser remains attached to either connection (eg: tcp content rules are
10186 accepted). In HTTP, this timeout is used when a connection is upgraded (eg:
10187 when switching to the WebSocket protocol, or forwarding a CONNECT request
10188 to a proxy), or after the first response when no keepalive/close option is
10189 specified.
10190
Willy Tarreau05cdd962014-05-10 14:30:07 +020010191 Since this timeout is usually used in conjunction with long-lived connections,
10192 it usually is a good idea to also set "timeout client-fin" to handle the
10193 situation where a client suddenly disappears from the net and does not
10194 acknowledge a close, or sends a shutdown and does not acknowledge pending
10195 data anymore. This can happen in lossy networks where firewalls are present,
10196 and is detected by the presence of large amounts of sessions in a FIN_WAIT
10197 state.
10198
Willy Tarreauce887fd2012-05-12 12:50:00 +020010199 The value is specified in milliseconds by default, but can be in any other
10200 unit if the number is suffixed by the unit, as specified at the top of this
10201 document. Whatever the expected normal idle time, it is a good practice to
10202 cover at least one or several TCP packet losses by specifying timeouts that
10203 are slightly above multiples of 3 seconds (eg: 4 or 5 seconds minimum).
10204
10205 This parameter is specific to backends, but can be specified once for all in
10206 "defaults" sections. This is in fact one of the easiest solutions not to
10207 forget about it.
10208
10209 Example :
10210 defaults http
10211 option http-server-close
10212 timeout connect 5s
10213 timeout client 30s
Willy Tarreau05cdd962014-05-10 14:30:07 +020010214 timeout client-fin 30s
Willy Tarreauce887fd2012-05-12 12:50:00 +020010215 timeout server 30s
10216 timeout tunnel 1h # timeout to use with WebSocket and CONNECT
10217
Willy Tarreau05cdd962014-05-10 14:30:07 +020010218 See also : "timeout client", "timeout client-fin", "timeout server".
Willy Tarreauce887fd2012-05-12 12:50:00 +020010219
10220
Willy Tarreau844e3c52008-01-11 16:28:18 +010010221transparent (deprecated)
10222 Enable client-side transparent proxying
10223 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +010010224 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +010010225 Arguments : none
10226
10227 This keyword was introduced in order to provide layer 7 persistence to layer
10228 3 load balancers. The idea is to use the OS's ability to redirect an incoming
10229 connection for a remote address to a local process (here HAProxy), and let
10230 this process know what address was initially requested. When this option is
10231 used, sessions without cookies will be forwarded to the original destination
10232 IP address of the incoming request (which should match that of another
10233 equipment), while requests with cookies will still be forwarded to the
10234 appropriate server.
10235
10236 The "transparent" keyword is deprecated, use "option transparent" instead.
10237
10238 Note that contrary to a common belief, this option does NOT make HAProxy
10239 present the client's IP to the server when establishing the connection.
10240
Willy Tarreau844e3c52008-01-11 16:28:18 +010010241 See also: "option transparent"
10242
William Lallemanda73203e2012-03-12 12:48:57 +010010243unique-id-format <string>
10244 Generate a unique ID for each request.
10245 May be used in sections : defaults | frontend | listen | backend
10246 yes | yes | yes | no
10247 Arguments :
10248 <string> is a log-format string.
10249
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010250 This keyword creates a ID for each request using the custom log format. A
10251 unique ID is useful to trace a request passing through many components of
10252 a complex infrastructure. The newly created ID may also be logged using the
10253 %ID tag the log-format string.
William Lallemanda73203e2012-03-12 12:48:57 +010010254
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010255 The format should be composed from elements that are guaranteed to be
10256 unique when combined together. For instance, if multiple haproxy instances
10257 are involved, it might be important to include the node name. It is often
10258 needed to log the incoming connection's source and destination addresses
10259 and ports. Note that since multiple requests may be performed over the same
10260 connection, including a request counter may help differentiate them.
10261 Similarly, a timestamp may protect against a rollover of the counter.
10262 Logging the process ID will avoid collisions after a service restart.
William Lallemanda73203e2012-03-12 12:48:57 +010010263
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010264 It is recommended to use hexadecimal notation for many fields since it
10265 makes them more compact and saves space in logs.
William Lallemanda73203e2012-03-12 12:48:57 +010010266
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010267 Example:
William Lallemanda73203e2012-03-12 12:48:57 +010010268
Julien Vehentf21be322014-03-07 08:27:34 -050010269 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +010010270
10271 will generate:
10272
10273 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
10274
10275 See also: "unique-id-header"
10276
10277unique-id-header <name>
10278 Add a unique ID header in the HTTP request.
10279 May be used in sections : defaults | frontend | listen | backend
10280 yes | yes | yes | no
10281 Arguments :
10282 <name> is the name of the header.
10283
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010284 Add a unique-id header in the HTTP request sent to the server, using the
10285 unique-id-format. It can't work if the unique-id-format doesn't exist.
William Lallemanda73203e2012-03-12 12:48:57 +010010286
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010287 Example:
William Lallemanda73203e2012-03-12 12:48:57 +010010288
Julien Vehentf21be322014-03-07 08:27:34 -050010289 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +010010290 unique-id-header X-Unique-ID
10291
10292 will generate:
10293
10294 X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
10295
10296 See also: "unique-id-format"
Willy Tarreau844e3c52008-01-11 16:28:18 +010010297
Willy Tarreauf51658d2014-04-23 01:21:56 +020010298use_backend <backend> [{if | unless} <condition>]
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020010299 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010300 May be used in sections : defaults | frontend | listen | backend
10301 no | yes | yes | no
10302 Arguments :
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010010303 <backend> is the name of a valid backend or "listen" section, or a
10304 "log-format" string resolving to a backend name.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010305
Willy Tarreauf51658d2014-04-23 01:21:56 +020010306 <condition> is a condition composed of ACLs, as described in section 7. If
10307 it is omitted, the rule is unconditionally applied.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010308
10309 When doing content-switching, connections arrive on a frontend and are then
10310 dispatched to various backends depending on a number of conditions. The
10311 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020010312 "use_backend" keyword. While it is normally used with HTTP processing, it can
10313 also be used in pure TCP, either without content using stateless ACLs (eg:
10314 source address validation) or combined with a "tcp-request" rule to wait for
10315 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010316
10317 There may be as many "use_backend" rules as desired. All of these rules are
10318 evaluated in their declaration order, and the first one which matches will
10319 assign the backend.
10320
10321 In the first form, the backend will be used if the condition is met. In the
10322 second form, the backend will be used if the condition is not met. If no
10323 condition is valid, the backend defined with "default_backend" will be used.
10324 If no default backend is defined, either the servers in the same section are
10325 used (in case of a "listen" section) or, in case of a frontend, no server is
10326 used and a 503 service unavailable response is returned.
10327
Willy Tarreau51aecc72009-07-12 09:47:04 +020010328 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010329 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +020010330 and backend processing will immediately follow, or the backend will wait for
10331 a complete HTTP request to get in. This feature is useful when a frontend
10332 must decode several protocols on a unique port, one of them being HTTP.
10333
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010010334 When <backend> is a simple name, it is resolved at configuration time, and an
10335 error is reported if the specified backend does not exist. If <backend> is
10336 a log-format string instead, no check may be done at configuration time, so
10337 the backend name is resolved dynamically at run time. If the resulting
10338 backend name does not correspond to any valid backend, no other rule is
10339 evaluated, and the default_backend directive is applied instead. Note that
10340 when using dynamic backend names, it is highly recommended to use a prefix
10341 that no other backend uses in order to ensure that an unauthorized backend
10342 cannot be forced from the request.
10343
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010344 It is worth mentioning that "use_backend" rules with an explicit name are
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010010345 used to detect the association between frontends and backends to compute the
10346 backend's "fullconn" setting. This cannot be done for dynamic names.
10347
10348 See also: "default_backend", "tcp-request", "fullconn", "log-format", and
10349 section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +010010350
Willy Tarreau036fae02008-01-06 13:24:40 +010010351
Willy Tarreau4a5cade2012-04-05 21:09:48 +020010352use-server <server> if <condition>
10353use-server <server> unless <condition>
10354 Only use a specific server if/unless an ACL-based condition is matched.
10355 May be used in sections : defaults | frontend | listen | backend
10356 no | no | yes | yes
10357 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010358 <server> is the name of a valid server in the same backend section.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020010359
10360 <condition> is a condition composed of ACLs, as described in section 7.
10361
10362 By default, connections which arrive to a backend are load-balanced across
10363 the available servers according to the configured algorithm, unless a
10364 persistence mechanism such as a cookie is used and found in the request.
10365
10366 Sometimes it is desirable to forward a particular request to a specific
10367 server without having to declare a dedicated backend for this server. This
10368 can be achieved using the "use-server" rules. These rules are evaluated after
10369 the "redirect" rules and before evaluating cookies, and they have precedence
10370 on them. There may be as many "use-server" rules as desired. All of these
10371 rules are evaluated in their declaration order, and the first one which
10372 matches will assign the server.
10373
10374 If a rule designates a server which is down, and "option persist" is not used
10375 and no force-persist rule was validated, it is ignored and evaluation goes on
10376 with the next rules until one matches.
10377
10378 In the first form, the server will be used if the condition is met. In the
10379 second form, the server will be used if the condition is not met. If no
10380 condition is valid, the processing continues and the server will be assigned
10381 according to other persistence mechanisms.
10382
10383 Note that even if a rule is matched, cookie processing is still performed but
10384 does not assign the server. This allows prefixed cookies to have their prefix
10385 stripped.
10386
10387 The "use-server" statement works both in HTTP and TCP mode. This makes it
10388 suitable for use with content-based inspection. For instance, a server could
10389 be selected in a farm according to the TLS SNI field. And if these servers
10390 have their weight set to zero, they will not be used for other traffic.
10391
10392 Example :
10393 # intercept incoming TLS requests based on the SNI field
10394 use-server www if { req_ssl_sni -i www.example.com }
10395 server www 192.168.0.1:443 weight 0
10396 use-server mail if { req_ssl_sni -i mail.example.com }
10397 server mail 192.168.0.1:587 weight 0
10398 use-server imap if { req_ssl_sni -i imap.example.com }
Lukas Tribus98a3e3f2017-03-26 12:55:35 +000010399 server imap 192.168.0.1:993 weight 0
Willy Tarreau4a5cade2012-04-05 21:09:48 +020010400 # all the rest is forwarded to this server
10401 server default 192.168.0.2:443 check
10402
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010403 See also: "use_backend", section 5 about server and section 7 about ACLs.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020010404
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010405
104065. Bind and Server options
10407--------------------------
10408
10409The "bind", "server" and "default-server" keywords support a number of settings
10410depending on some build options and on the system HAProxy was built on. These
10411settings generally each consist in one word sometimes followed by a value,
10412written on the same line as the "bind" or "server" line. All these options are
10413described in this section.
10414
10415
104165.1. Bind options
10417-----------------
10418
10419The "bind" keyword supports a certain number of settings which are all passed
10420as arguments on the same line. The order in which those arguments appear makes
10421no importance, provided that they appear after the bind address. All of these
10422parameters are optional. Some of them consist in a single words (booleans),
10423while other ones expect a value after them. In this case, the value must be
10424provided immediately after the setting name.
10425
10426The currently supported settings are the following ones.
10427
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010010428accept-netscaler-cip <magic number>
10429 Enforces the use of the NetScaler Client IP insertion protocol over any
10430 connection accepted by any of the TCP sockets declared on the same line. The
10431 NetScaler Client IP insertion protocol dictates the layer 3/4 addresses of
10432 the incoming connection to be used everywhere an address is used, with the
10433 only exception of "tcp-request connection" rules which will only see the
10434 real connection address. Logs will reflect the addresses indicated in the
10435 protocol, unless it is violated, in which case the real address will still
10436 be used. This keyword combined with support from external components can be
10437 used as an efficient and reliable alternative to the X-Forwarded-For
Bertrand Jacquin90759682016-06-06 15:35:39 +010010438 mechanism which is not always reliable and not even always usable. See also
10439 "tcp-request connection expect-netscaler-cip" for a finer-grained setting of
10440 which client is allowed to use the protocol.
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010010441
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010442accept-proxy
10443 Enforces the use of the PROXY protocol over any connection accepted by any of
Willy Tarreau77992672014-06-14 11:06:17 +020010444 the sockets declared on the same line. Versions 1 and 2 of the PROXY protocol
10445 are supported and correctly detected. The PROXY protocol dictates the layer
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010446 3/4 addresses of the incoming connection to be used everywhere an address is
10447 used, with the only exception of "tcp-request connection" rules which will
10448 only see the real connection address. Logs will reflect the addresses
10449 indicated in the protocol, unless it is violated, in which case the real
10450 address will still be used. This keyword combined with support from external
10451 components can be used as an efficient and reliable alternative to the
10452 X-Forwarded-For mechanism which is not always reliable and not even always
Willy Tarreau4f0d9192013-06-11 20:40:55 +020010453 usable. See also "tcp-request connection expect-proxy" for a finer-grained
10454 setting of which client is allowed to use the protocol.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010455
Olivier Houchardc2aae742017-09-22 18:26:28 +020010456allow-0rtt
10457 Allow receiving early data when using TLS 1.3. This is disabled by default,
10458 due to security considerations.
10459
Willy Tarreauab861d32013-04-02 02:30:41 +020010460alpn <protocols>
10461 This enables the TLS ALPN extension and advertises the specified protocol
10462 list as supported on top of ALPN. The protocol list consists in a comma-
10463 delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
10464 quotes). This requires that the SSL library is build with support for TLS
10465 extensions enabled (check with haproxy -vv). The ALPN extension replaces the
Willy Tarreau95c4e142017-11-26 12:18:55 +010010466 initial NPN extension. ALPN is required to enable HTTP/2 on an HTTP frontend.
10467 Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the
10468 now obsolete NPN extension. At the time of writing this, most browsers still
10469 support both ALPN and NPN for HTTP/2 so a fallback to NPN may still work for
10470 a while. But ALPN must be used whenever possible. If both HTTP/2 and HTTP/1.1
10471 are expected to be supported, both versions can be advertised, in order of
10472 preference, like below :
10473
10474 bind :443 ssl crt pub.pem alpn h2,http/1.1
Willy Tarreauab861d32013-04-02 02:30:41 +020010475
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010476backlog <backlog>
10477 Sets the socket's backlog to this value. If unspecified, the frontend's
10478 backlog is used instead, which generally defaults to the maxconn value.
10479
Emmanuel Hocdete7f2b732017-01-09 16:15:54 +010010480curves <curves>
10481 This setting is only available when support for OpenSSL was built in. It sets
10482 the string describing the list of elliptic curves algorithms ("curve suite")
10483 that are negotiated during the SSL/TLS handshake with ECDHE. The format of the
10484 string is a colon-delimited list of curve name.
10485 Example: "X25519:P-256" (without quote)
10486 When "curves" is set, "ecdhe" parameter is ignored.
10487
Emeric Brun7fb34422012-09-28 15:26:15 +020010488ecdhe <named curve>
10489 This setting is only available when support for OpenSSL was built in. It sets
Emeric Brun6924ef82013-03-06 14:08:53 +010010490 the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default,
10491 used named curve is prime256v1.
Emeric Brun7fb34422012-09-28 15:26:15 +020010492
Emeric Brunfd33a262012-10-11 16:28:27 +020010493ca-file <cafile>
Emeric Brun1a073b42012-09-28 17:07:34 +020010494 This setting is only available when support for OpenSSL was built in. It
10495 designates a PEM file from which to load CA certificates used to verify
10496 client's certificate.
10497
Emeric Brunb6dc9342012-09-28 17:55:37 +020010498ca-ignore-err [all|<errorID>,...]
10499 This setting is only available when support for OpenSSL was built in.
10500 Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
10501 If set to 'all', all errors are ignored. SSL handshake is not aborted if an
10502 error is ignored.
10503
Christopher Faulet31af49d2015-06-09 17:29:50 +020010504ca-sign-file <cafile>
10505 This setting is only available when support for OpenSSL was built in. It
10506 designates a PEM file containing both the CA certificate and the CA private
10507 key used to create and sign server's certificates. This is a mandatory
10508 setting when the dynamic generation of certificates is enabled. See
10509 'generate-certificates' for details.
10510
Bertrand Jacquind4d0a232016-11-13 16:37:12 +000010511ca-sign-pass <passphrase>
Christopher Faulet31af49d2015-06-09 17:29:50 +020010512 This setting is only available when support for OpenSSL was built in. It is
10513 the CA private key passphrase. This setting is optional and used only when
10514 the dynamic generation of certificates is enabled. See
10515 'generate-certificates' for details.
10516
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010517ciphers <ciphers>
10518 This setting is only available when support for OpenSSL was built in. It sets
10519 the string describing the list of cipher algorithms ("cipher suite") that are
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010520 negotiated during the SSL/TLS handshake. The format of the string is defined
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010521 in "man 1 ciphers" from OpenSSL man pages, and can be for instance a string
10522 such as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes).
Daniel Schneller87e43022017-09-01 19:29:57 +020010523 Depending on the compatiblity and security requirements, the list of suitable
10524 ciphers depends on a variety of variables. For background information and
10525 recommendations see e. g. (https://wiki.mozilla.org/Security/Server_Side_TLS)
10526 and (https://mozilla.github.io/server-side-tls/ssl-config-generator/).
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010527
Emeric Brunfd33a262012-10-11 16:28:27 +020010528crl-file <crlfile>
Emeric Brun1a073b42012-09-28 17:07:34 +020010529 This setting is only available when support for OpenSSL was built in. It
10530 designates a PEM file from which to load certificate revocation list used
10531 to verify client's certificate.
10532
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010533crt <cert>
Alex Davies0fbf0162013-03-02 16:04:50 +000010534 This setting is only available when support for OpenSSL was built in. It
10535 designates a PEM file containing both the required certificates and any
10536 associated private keys. This file can be built by concatenating multiple
10537 PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA
10538 requires an intermediate certificate, this can also be concatenated into this
10539 file.
10540
10541 If the OpenSSL used supports Diffie-Hellman, parameters present in this file
10542 are loaded.
10543
10544 If a directory name is used instead of a PEM file, then all files found in
Cyril Bonté3180f7b2015-01-25 00:16:08 +010010545 that directory will be loaded in alphabetic order unless their name ends with
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010010546 '.issuer', '.ocsp' or '.sctl' (reserved extensions). This directive may be
10547 specified multiple times in order to load certificates from multiple files or
10548 directories. The certificates will be presented to clients who provide a
10549 valid TLS Server Name Indication field matching one of their CN or alt
10550 subjects. Wildcards are supported, where a wildcard character '*' is used
10551 instead of the first hostname component (eg: *.example.org matches
10552 www.example.org but not www.sub.example.org).
Alex Davies0fbf0162013-03-02 16:04:50 +000010553
10554 If no SNI is provided by the client or if the SSL library does not support
10555 TLS extensions, or if the client provides an SNI hostname which does not
10556 match any certificate, then the first loaded certificate will be presented.
10557 This means that when loading certificates from a directory, it is highly
Cyril Bonté3180f7b2015-01-25 00:16:08 +010010558 recommended to load the default one first as a file or to ensure that it will
10559 always be the first one in the directory.
Alex Davies0fbf0162013-03-02 16:04:50 +000010560
Emeric Brune032bfa2012-09-28 13:01:45 +020010561 Note that the same cert may be loaded multiple times without side effects.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010562
Alex Davies0fbf0162013-03-02 16:04:50 +000010563 Some CAs (such as Godaddy) offer a drop down list of server types that do not
10564 include HAProxy when obtaining a certificate. If this happens be sure to
Godbach8bf60a12014-04-21 21:42:41 +080010565 choose a webserver that the CA believes requires an intermediate CA (for
Alex Davies0fbf0162013-03-02 16:04:50 +000010566 Godaddy, selection Apache Tomcat will get the correct bundle, but many
10567 others, e.g. nginx, result in a wrong bundle that will not work for some
10568 clients).
10569
Emeric Brun4147b2e2014-06-16 18:36:30 +020010570 For each PEM file, haproxy checks for the presence of file at the same path
10571 suffixed by ".ocsp". If such file is found, support for the TLS Certificate
10572 Status Request extension (also known as "OCSP stapling") is automatically
10573 enabled. The content of this file is optional. If not empty, it must contain
10574 a valid OCSP Response in DER format. In order to be valid an OCSP Response
10575 must comply with the following rules: it has to indicate a good status,
10576 it has to be a single response for the certificate of the PEM file, and it
10577 has to be valid at the moment of addition. If these rules are not respected
10578 the OCSP Response is ignored and a warning is emitted. In order to identify
10579 which certificate an OCSP Response applies to, the issuer's certificate is
10580 necessary. If the issuer's certificate is not found in the PEM file, it will
10581 be loaded from a file at the same path as the PEM file suffixed by ".issuer"
10582 if it exists otherwise it will fail with an error.
10583
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010010584 For each PEM file, haproxy also checks for the presence of file at the same
10585 path suffixed by ".sctl". If such file is found, support for Certificate
10586 Transparency (RFC6962) TLS extension is enabled. The file must contain a
10587 valid Signed Certificate Timestamp List, as described in RFC. File is parsed
10588 to check basic syntax, but no signatures are verified.
10589
yanbzhu6c25e9e2016-01-05 12:52:02 -050010590 There are cases where it is desirable to support multiple key types, e.g. RSA
10591 and ECDSA in the cipher suites offered to the clients. This allows clients
10592 that support EC certificates to be able to use EC ciphers, while
10593 simultaneously supporting older, RSA only clients.
yanbzhud19630c2015-12-14 15:10:25 -050010594
10595 In order to provide this functionality, multiple PEM files, each with a
10596 different key type, are required. To associate these PEM files into a
10597 "cert bundle" that is recognized by haproxy, they must be named in the
10598 following way: All PEM files that are to be bundled must have the same base
10599 name, with a suffix indicating the key type. Currently, three suffixes are
10600 supported: rsa, dsa and ecdsa. For example, if www.example.com has two PEM
10601 files, an RSA file and an ECDSA file, they must be named: "example.pem.rsa"
10602 and "example.pem.ecdsa". The first part of the filename is arbitrary; only the
10603 suffix matters. To load this bundle into haproxy, specify the base name only:
10604
10605 Example : bind :8443 ssl crt example.pem
10606
yanbzhu6c25e9e2016-01-05 12:52:02 -050010607 Note that the suffix is not given to haproxy; this tells haproxy to look for
yanbzhud19630c2015-12-14 15:10:25 -050010608 a cert bundle.
10609
10610 Haproxy will load all PEM files in the bundle at the same time to try to
10611 support multiple key types. PEM files are combined based on Common Name
10612 (CN) and Subject Alternative Name (SAN) to support SNI lookups. This means
10613 that even if you give haproxy a cert bundle, if there are no shared CN/SAN
10614 entries in the certificates in that bundle, haproxy will not be able to
10615 provide multi-cert support.
10616
10617 Assuming bundle in the example above contained the following:
10618
10619 Filename | CN | SAN
10620 -------------------+-----------------+-------------------
10621 example.pem.rsa | www.example.com | rsa.example.com
yanbzhu6c25e9e2016-01-05 12:52:02 -050010622 -------------------+-----------------+-------------------
yanbzhud19630c2015-12-14 15:10:25 -050010623 example.pem.ecdsa | www.example.com | ecdsa.example.com
10624 -------------------+-----------------+-------------------
10625
10626 Users connecting with an SNI of "www.example.com" will be able
10627 to use both RSA and ECDSA cipher suites. Users connecting with an SNI of
10628 "rsa.example.com" will only be able to use RSA cipher suites, and users
10629 connecting with "ecdsa.example.com" will only be able to use ECDSA cipher
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020010630 suites. With BoringSSL and Openssl >= 1.1.1 multi-cert is natively supported,
10631 no need to bundle certificates. ECDSA certificate will be preferred if client
10632 support it.
yanbzhud19630c2015-12-14 15:10:25 -050010633
10634 If a directory name is given as the <cert> argument, haproxy will
10635 automatically search and load bundled files in that directory.
10636
10637 OSCP files (.ocsp) and issuer files (.issuer) are supported with multi-cert
10638 bundling. Each certificate can have its own .ocsp and .issuer file. At this
10639 time, sctl is not supported in multi-certificate bundling.
10640
Emeric Brunb6dc9342012-09-28 17:55:37 +020010641crt-ignore-err <errors>
Alex Davies0fbf0162013-03-02 16:04:50 +000010642 This setting is only available when support for OpenSSL was built in. Sets a
10643 comma separated list of errorIDs to ignore during verify at depth == 0. If
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010644 set to 'all', all errors are ignored. SSL handshake is not aborted if an error
Alex Davies0fbf0162013-03-02 16:04:50 +000010645 is ignored.
Emeric Brunb6dc9342012-09-28 17:55:37 +020010646
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010010647crt-list <file>
10648 This setting is only available when support for OpenSSL was built in. It
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010649 designates a list of PEM file with an optional ssl configuration and a SNI
10650 filter per certificate, with the following format for each line :
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010010651
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010652 <crtfile> [\[<sslbindconf> ...\]] [[!]<snifilter> ...]
10653
Emmanuel Hocdet174dfe52017-07-28 15:01:05 +020010654 sslbindconf support "npn", "alpn", "verify", "ca-file", "no-ca-names",
10655 crl-file", "ecdhe", "curves", "ciphers" configuration. With BoringSSL
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020010656 and Openssl >= 1.1.1 "ssl-min-ver" and "ssl-max-ver" are also supported.
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010657 It override the configuration set in bind line for the certificate.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010010658
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +020010659 Wildcards are supported in the SNI filter. Negative filter are also supported,
10660 only useful in combination with a wildcard filter to exclude a particular SNI.
10661 The certificates will be presented to clients who provide a valid TLS Server
10662 Name Indication field matching one of the SNI filters. If no SNI filter is
10663 specified, the CN and alt subjects are used. This directive may be specified
10664 multiple times. See the "crt" option for more information. The default
10665 certificate is still needed to meet OpenSSL expectations. If it is not used,
10666 the 'strict-sni' option may be used.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010010667
yanbzhu6c25e9e2016-01-05 12:52:02 -050010668 Multi-cert bundling (see "crt") is supported with crt-list, as long as only
Emmanuel Hocdetd294aea2016-05-13 11:14:06 +020010669 the base name is given in the crt-list. SNI filter will do the same work on
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020010670 all bundled certificates. With BoringSSL and Openssl >= 1.1.1 multi-cert is
10671 natively supported, avoid multi-cert bundling. RSA and ECDSA certificates can
10672 be declared in a row, and set different ssl and filter parameter.
yanbzhud19630c2015-12-14 15:10:25 -050010673
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010674 crt-list file example:
10675 cert1.pem
Emmanuel Hocdet05942112017-02-20 16:11:50 +010010676 cert2.pem [alpn h2,http/1.1]
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010677 certW.pem *.domain.tld !secure.domain.tld
Emmanuel Hocdet05942112017-02-20 16:11:50 +010010678 certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld
Emmanuel Hocdet98263292016-12-29 18:26:15 +010010679
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010680defer-accept
10681 Is an optional keyword which is supported only on certain Linux kernels. It
10682 states that a connection will only be accepted once some data arrive on it,
10683 or at worst after the first retransmit. This should be used only on protocols
10684 for which the client talks first (eg: HTTP). It can slightly improve
10685 performance by ensuring that most of the request is already available when
10686 the connection is accepted. On the other hand, it will not be able to detect
10687 connections which don't talk. It is important to note that this option is
10688 broken in all kernels up to 2.6.31, as the connection is never accepted until
10689 the client talks. This can cause issues with front firewalls which would see
10690 an established connection while the proxy will only see it in SYN_RECV. This
10691 option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
10692
William Lallemandf6975e92017-05-26 17:42:10 +020010693expose-fd listeners
10694 This option is only usable with the stats socket. It gives your stats socket
10695 the capability to pass listeners FD to another HAProxy process.
William Lallemande202b1e2017-06-01 17:38:56 +020010696 During a reload with the master-worker mode, the process is automatically
10697 reexecuted adding -x and one of the stats socket with this option.
William Lallemandf6975e92017-05-26 17:42:10 +020010698 See alors "-x" in the management guide.
10699
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010700force-sslv3
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010701 This option enforces use of SSLv3 only on SSL connections instantiated from
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010702 this listener. SSLv3 is generally less expensive than the TLS counterparts
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010703 for high connection rates. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010704 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010705
10706force-tlsv10
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010707 This option enforces use of TLSv1.0 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010708 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010709 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010710
10711force-tlsv11
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010712 This option enforces use of TLSv1.1 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010713 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010714 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010715
10716force-tlsv12
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010717 This option enforces use of TLSv1.2 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010718 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010719 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010720
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020010721force-tlsv13
10722 This option enforces use of TLSv1.3 only on SSL connections instantiated from
10723 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010724 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020010725
Christopher Faulet31af49d2015-06-09 17:29:50 +020010726generate-certificates
10727 This setting is only available when support for OpenSSL was built in. It
10728 enables the dynamic SSL certificates generation. A CA certificate and its
10729 private key are necessary (see 'ca-sign-file'). When HAProxy is configured as
10730 a transparent forward proxy, SSL requests generate errors because of a common
10731 name mismatch on the certificate presented to the client. With this option
10732 enabled, HAProxy will try to forge a certificate using the SNI hostname
10733 indicated by the client. This is done only if no certificate matches the SNI
10734 hostname (see 'crt-list'). If an error occurs, the default certificate is
10735 used, else the 'strict-sni' option is set.
10736 It can also be used when HAProxy is configured as a reverse proxy to ease the
10737 deployment of an architecture with many backends.
10738
10739 Creating a SSL certificate is an expensive operation, so a LRU cache is used
10740 to store forged certificates (see 'tune.ssl.ssl-ctx-cache-size'). It
10741 increases the HAProxy's memroy footprint to reduce latency when the same
10742 certificate is used many times.
10743
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010744gid <gid>
10745 Sets the group of the UNIX sockets to the designated system gid. It can also
10746 be set by default in the global section's "unix-bind" statement. Note that
10747 some platforms simply ignore this. This setting is equivalent to the "group"
10748 setting except that the group ID is used instead of its name. This setting is
10749 ignored by non UNIX sockets.
10750
10751group <group>
10752 Sets the group of the UNIX sockets to the designated system group. It can
10753 also be set by default in the global section's "unix-bind" statement. Note
10754 that some platforms simply ignore this. This setting is equivalent to the
10755 "gid" setting except that the group name is used instead of its gid. This
10756 setting is ignored by non UNIX sockets.
10757
10758id <id>
10759 Fixes the socket ID. By default, socket IDs are automatically assigned, but
10760 sometimes it is more convenient to fix them to ease monitoring. This value
10761 must be strictly positive and unique within the listener/frontend. This
10762 option can only be used when defining only a single socket.
10763
10764interface <interface>
Lukas Tribusfce2e962013-02-12 22:13:19 +010010765 Restricts the socket to a specific interface. When specified, only packets
10766 received from that particular interface are processed by the socket. This is
10767 currently only supported on Linux. The interface must be a primary system
10768 interface, not an aliased interface. It is also possible to bind multiple
10769 frontends to the same address if they are bound to different interfaces. Note
10770 that binding to a network interface requires root privileges. This parameter
10771 is only compatible with TCPv4/TCPv6 sockets.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010772
Willy Tarreauabb175f2012-09-24 12:43:26 +020010773level <level>
10774 This setting is used with the stats sockets only to restrict the nature of
10775 the commands that can be issued on the socket. It is ignored by other
10776 sockets. <level> can be one of :
10777 - "user" is the least privileged level ; only non-sensitive stats can be
10778 read, and no change is allowed. It would make sense on systems where it
10779 is not easy to restrict access to the socket.
10780 - "operator" is the default level and fits most common uses. All data can
10781 be read, and only non-sensitive changes are permitted (eg: clear max
10782 counters).
10783 - "admin" should be used with care, as everything is permitted (eg: clear
10784 all counters).
10785
Andjelko Iharosc4df59e2017-07-20 11:59:48 +020010786severity-output <format>
10787 This setting is used with the stats sockets only to configure severity
10788 level output prepended to informational feedback messages. Severity
10789 level of messages can range between 0 and 7, conforming to syslog
10790 rfc5424. Valid and successful socket commands requesting data
10791 (i.e. "show map", "get acl foo" etc.) will never have a severity level
10792 prepended. It is ignored by other sockets. <format> can be one of :
10793 - "none" (default) no severity level is prepended to feedback messages.
10794 - "number" severity level is prepended as a number.
10795 - "string" severity level is prepended as a string following the
10796 rfc5424 convention.
10797
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010798maxconn <maxconn>
10799 Limits the sockets to this number of concurrent connections. Extraneous
10800 connections will remain in the system's backlog until a connection is
10801 released. If unspecified, the limit will be the same as the frontend's
10802 maxconn. Note that in case of port ranges or multiple addresses, the same
10803 value will be applied to each socket. This setting enables different
10804 limitations on expensive sockets, for instance SSL entries which may easily
10805 eat all memory.
10806
10807mode <mode>
10808 Sets the octal mode used to define access permissions on the UNIX socket. It
10809 can also be set by default in the global section's "unix-bind" statement.
10810 Note that some platforms simply ignore this. This setting is ignored by non
10811 UNIX sockets.
10812
10813mss <maxseg>
10814 Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming
10815 connections. This can be used to force a lower MSS for certain specific
10816 ports, for instance for connections passing through a VPN. Note that this
10817 relies on a kernel feature which is theoretically supported under Linux but
10818 was buggy in all versions prior to 2.6.28. It may or may not work on other
10819 operating systems. It may also not change the advertised value but change the
10820 effective size of outgoing segments. The commonly advertised value for TCPv4
10821 over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is
10822 positive, it will be used as the advertised MSS. If it is negative, it will
10823 indicate by how much to reduce the incoming connection's advertised MSS for
10824 outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.
10825
10826name <name>
10827 Sets an optional name for these sockets, which will be reported on the stats
10828 page.
10829
Willy Tarreaud72f0f32015-10-13 14:50:22 +020010830namespace <name>
10831 On Linux, it is possible to specify which network namespace a socket will
10832 belong to. This directive makes it possible to explicitly bind a listener to
10833 a namespace different from the default one. Please refer to your operating
10834 system's documentation to find more details about network namespaces.
10835
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010836nice <nice>
10837 Sets the 'niceness' of connections initiated from the socket. Value must be
10838 in the range -1024..1024 inclusive, and defaults to zero. Positive values
10839 means that such connections are more friendly to others and easily offer
10840 their place in the scheduler. On the opposite, negative values mean that
10841 connections want to run with a higher priority than others. The difference
10842 only happens under high loads when the system is close to saturation.
10843 Negative values are appropriate for low-latency or administration services,
10844 and high values are generally recommended for CPU intensive tasks such as SSL
10845 processing or bulk transfers which are less sensible to latency. For example,
10846 it may make sense to use a positive value for an SMTP socket and a negative
10847 one for an RDP socket.
10848
Emmanuel Hocdet174dfe52017-07-28 15:01:05 +020010849no-ca-names
10850 This setting is only available when support for OpenSSL was built in. It
10851 prevents from send CA names in server hello message when ca-file is used.
10852
Emeric Brun9b3009b2012-10-05 11:55:06 +020010853no-sslv3
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010854 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010855 disables support for SSLv3 on any sockets instantiated from the listener when
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010856 SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010857 be enabled using any configuration option. This option is also available on
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010858 global statement "ssl-default-bind-options". Use "ssl-min-ver" and
10859 "ssl-max-ver" instead.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010860
Emeric Brun90ad8722012-10-02 14:00:59 +020010861no-tls-tickets
10862 This setting is only available when support for OpenSSL was built in. It
10863 disables the stateless session resumption (RFC 5077 TLS Ticket
10864 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010865 session resumption is more expensive in CPU usage. This option is also
10866 available on global statement "ssl-default-bind-options".
Emeric Brun90ad8722012-10-02 14:00:59 +020010867
Emeric Brun9b3009b2012-10-05 11:55:06 +020010868no-tlsv10
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010869 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010870 disables support for TLSv1.0 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010871 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010872 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010873 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
10874 and "ssl-max-ver" instead.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010875
Emeric Brun9b3009b2012-10-05 11:55:06 +020010876no-tlsv11
Emeric Brunf5da4932012-09-28 19:42:54 +020010877 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010878 disables support for TLSv1.1 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010879 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010880 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010881 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
10882 and "ssl-max-ver" instead.
Emeric Brunf5da4932012-09-28 19:42:54 +020010883
Emeric Brun9b3009b2012-10-05 11:55:06 +020010884no-tlsv12
Emeric Brunf5da4932012-09-28 19:42:54 +020010885 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010886 disables support for TLSv1.2 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020010887 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010888 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010889 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
10890 and "ssl-max-ver" instead.
Emeric Brunf5da4932012-09-28 19:42:54 +020010891
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020010892no-tlsv13
10893 This setting is only available when support for OpenSSL was built in. It
10894 disables support for TLSv1.3 on any sockets instantiated from the listener
10895 when SSL is supported. Note that SSLv2 is forced disabled in the code and
10896 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010897 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
10898 and "ssl-max-ver" instead.
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020010899
Willy Tarreau6c9a3d52012-10-18 18:57:14 +020010900npn <protocols>
10901 This enables the NPN TLS extension and advertises the specified protocol list
10902 as supported on top of NPN. The protocol list consists in a comma-delimited
10903 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
10904 This requires that the SSL library is build with support for TLS extensions
Willy Tarreauab861d32013-04-02 02:30:41 +020010905 enabled (check with haproxy -vv). Note that the NPN extension has been
Willy Tarreau95c4e142017-11-26 12:18:55 +010010906 replaced with the ALPN extension (see the "alpn" keyword), though this one is
10907 only available starting with OpenSSL 1.0.2. If HTTP/2 is desired on an older
10908 version of OpenSSL, NPN might still be used as most clients still support it
10909 at the time of writing this. It is possible to enable both NPN and ALPN
10910 though it probably doesn't make any sense out of testing.
Willy Tarreau6c9a3d52012-10-18 18:57:14 +020010911
Lukas Tribus53ae85c2017-05-04 15:45:40 +000010912prefer-client-ciphers
10913 Use the client's preference when selecting the cipher suite, by default
10914 the server's preference is enforced. This option is also available on
10915 global statement "ssl-default-bind-options".
10916
Christopher Fauletc644fa92017-11-23 22:44:11 +010010917process <process-set>[/<thread-set>]
10918 This restricts the list of processes and/or threads on which this listener is
10919 allowed to run. It does not enforce any process but eliminates those which do
10920 not match. If the frontend uses a "bind-process" setting, the intersection
10921 between the two is applied. If in the end the listener is not allowed to run
10922 on any remaining process, a warning is emitted, and the listener will either
10923 run on the first process of the listener if a single process was specified,
10924 or on all of its processes if multiple processes were specified. If a thread
10925 set is specified, it limits the threads allowed to process inoming
10926 connections for this listener, for the corresponding process set. For the
10927 unlikely case where several ranges are needed, this directive may be
10928 repeated. <process-set> and <thread-set> must use the format
10929
10930 all | odd | even | number[-[number]]
10931
10932 Ranges can be partially defined. The higher bound can be omitted. In such
10933 case, it is replaced by the corresponding maximum value. The main purpose of
10934 this directive is to be used with the stats sockets and have one different
10935 socket per process. The second purpose is to have multiple bind lines sharing
10936 the same IP:port but not the same process in a listener, so that the system
10937 can distribute the incoming connections into multiple queues and allow a
10938 smoother inter-process load balancing. Currently Linux 3.9 and above is known
10939 for supporting this. See also "bind-process" and "nbproc".
Willy Tarreau6ae1ba62014-05-07 19:01:58 +020010940
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010941ssl
10942 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010943 enables SSL deciphering on connections instantiated from this listener. A
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010944 certificate is necessary (see "crt" above). All contents in the buffers will
10945 appear in clear text, so that ACLs and HTTP processing will only have access
Emmanuel Hocdetbd695fe2017-05-15 15:53:41 +020010946 to deciphered contents. SSLv3 is disabled per default, use "ssl-min-ver SSLv3"
10947 to enable it.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020010948
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020010949ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
10950 This option enforces use of <version> or lower on SSL connections instantiated
10951 from this listener. This option is also available on global statement
10952 "ssl-default-bind-options". See also "ssl-min-ver".
10953
10954ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
10955 This option enforces use of <version> or upper on SSL connections instantiated
10956 from this listener. This option is also available on global statement
10957 "ssl-default-bind-options". See also "ssl-max-ver".
10958
Emmanuel Hocdet65623372013-01-24 17:17:15 +010010959strict-sni
10960 This setting is only available when support for OpenSSL was built in. The
10961 SSL/TLS negotiation is allow only if the client provided an SNI which match
10962 a certificate. The default certificate is not used.
10963 See the "crt" option for more information.
10964
Willy Tarreau2af207a2015-02-04 00:45:58 +010010965tcp-ut <delay>
Tim Düsterhus4896c442016-11-29 02:15:19 +010010966 Sets the TCP User Timeout for all incoming connections instantiated from this
Willy Tarreau2af207a2015-02-04 00:45:58 +010010967 listening socket. This option is available on Linux since version 2.6.37. It
10968 allows haproxy to configure a timeout for sockets which contain data not
Tim Düsterhus4896c442016-11-29 02:15:19 +010010969 receiving an acknowledgement for the configured delay. This is especially
Willy Tarreau2af207a2015-02-04 00:45:58 +010010970 useful on long-lived connections experiencing long idle periods such as
10971 remote terminals or database connection pools, where the client and server
10972 timeouts must remain high to allow a long period of idle, but where it is
10973 important to detect that the client has disappeared in order to release all
10974 resources associated with its connection (and the server's session). The
10975 argument is a delay expressed in milliseconds by default. This only works
10976 for regular TCP connections, and is ignored for other protocols.
10977
Willy Tarreau1c862c52012-10-05 16:21:00 +020010978tfo
Lukas Tribus0defb902013-02-13 23:35:39 +010010979 Is an optional keyword which is supported only on Linux kernels >= 3.7. It
Willy Tarreau1c862c52012-10-05 16:21:00 +020010980 enables TCP Fast Open on the listening socket, which means that clients which
10981 support this feature will be able to send a request and receive a response
10982 during the 3-way handshake starting from second connection, thus saving one
10983 round-trip after the first connection. This only makes sense with protocols
10984 that use high connection rates and where each round trip matters. This can
10985 possibly cause issues with many firewalls which do not accept data on SYN
10986 packets, so this option should only be enabled once well tested. This option
Lukas Tribus0999f762013-04-02 16:43:24 +020010987 is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may
10988 need to build HAProxy with USE_TFO=1 if your libc doesn't define
10989 TCP_FASTOPEN.
Willy Tarreau1c862c52012-10-05 16:21:00 +020010990
Nenad Merdanovic188ad3e2015-02-27 19:56:50 +010010991tls-ticket-keys <keyfile>
10992 Sets the TLS ticket keys file to load the keys from. The keys need to be 48
10993 bytes long, encoded with base64 (ex. openssl rand -base64 48). Number of keys
10994 is specified by the TLS_TICKETS_NO build option (default 3) and at least as
10995 many keys need to be present in the file. Last TLS_TICKETS_NO keys will be
10996 used for decryption and the penultimate one for encryption. This enables easy
10997 key rotation by just appending new key to the file and reloading the process.
10998 Keys must be periodically rotated (ex. every 12h) or Perfect Forward Secrecy
10999 is compromised. It is also a good idea to keep the keys off any permanent
11000 storage such as hard drives (hint: use tmpfs and don't swap those files).
11001 Lifetime hint can be changed using tune.ssl.timeout.
11002
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011003transparent
11004 Is an optional keyword which is supported only on certain Linux kernels. It
11005 indicates that the addresses will be bound even if they do not belong to the
11006 local machine, and that packets targeting any of these addresses will be
11007 intercepted just as if the addresses were locally configured. This normally
11008 requires that IP forwarding is enabled. Caution! do not use this with the
11009 default address '*', as it would redirect any traffic for the specified port.
11010 This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1.
11011 This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on
11012 kernel version. Some distribution kernels include backports of the feature,
11013 so check for support with your vendor.
11014
Willy Tarreau77e3af92012-11-24 15:07:23 +010011015v4v6
11016 Is an optional keyword which is supported only on most recent systems
11017 including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4
11018 and IPv6 when it uses the default address. Doing so is sometimes necessary
11019 on systems which bind to IPv6 only by default. It has no effect on non-IPv6
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011020 sockets, and is overridden by the "v6only" option.
Willy Tarreau77e3af92012-11-24 15:07:23 +010011021
Willy Tarreau9b6700f2012-11-24 11:55:28 +010011022v6only
11023 Is an optional keyword which is supported only on most recent systems
11024 including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only
11025 when it uses the default address. Doing so is sometimes preferred to doing it
Willy Tarreau77e3af92012-11-24 15:07:23 +010011026 system-wide as it is per-listener. It has no effect on non-IPv6 sockets and
11027 has precedence over the "v4v6" option.
Willy Tarreau9b6700f2012-11-24 11:55:28 +010011028
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011029uid <uid>
11030 Sets the owner of the UNIX sockets to the designated system uid. It can also
11031 be set by default in the global section's "unix-bind" statement. Note that
11032 some platforms simply ignore this. This setting is equivalent to the "user"
11033 setting except that the user numeric ID is used instead of its name. This
11034 setting is ignored by non UNIX sockets.
11035
11036user <user>
11037 Sets the owner of the UNIX sockets to the designated system user. It can also
11038 be set by default in the global section's "unix-bind" statement. Note that
11039 some platforms simply ignore this. This setting is equivalent to the "uid"
11040 setting except that the user name is used instead of its uid. This setting is
11041 ignored by non UNIX sockets.
11042
Emeric Brun1a073b42012-09-28 17:07:34 +020011043verify [none|optional|required]
11044 This setting is only available when support for OpenSSL was built in. If set
11045 to 'none', client certificate is not requested. This is the default. In other
11046 cases, a client certificate is requested. If the client does not provide a
11047 certificate after the request and if 'verify' is set to 'required', then the
11048 handshake is aborted, while it would have succeeded if set to 'optional'. The
Emeric Brunfd33a262012-10-11 16:28:27 +020011049 certificate provided by the client is always verified using CAs from
11050 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
11051 is aborted, regardless of the 'verify' option, unless the error code exactly
11052 matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020011053
Willy Tarreaub6205fd2012-09-24 12:27:33 +0200110545.2. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +010011055------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020011056
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010011057The "server" and "default-server" keywords support a certain number of settings
11058which are all passed as arguments on the server line. The order in which those
11059arguments appear does not count, and they are all optional. Some of those
11060settings are single words (booleans) while others expect one or several values
11061after them. In this case, the values must immediately follow the setting name.
11062Except default-server, all those settings must be specified after the server's
11063address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +020011064
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011065 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010011066 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +020011067
Frédéric Lécailled2376272017-03-21 18:52:12 +010011068Note that all these settings are supported both by "server" and "default-server"
11069keywords, except "id" which is only supported by "server".
11070
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011071The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +010011072
Willy Tarreauceb4ac92012-04-28 00:41:46 +020011073addr <ipv4|ipv6>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011074 Using the "addr" parameter, it becomes possible to use a different IP address
Baptiste Assmann13f83532016-03-06 23:14:36 +010011075 to send health-checks or to probe the agent-check. On some servers, it may be
11076 desirable to dedicate an IP address to specific component able to perform
11077 complex tests which are more suitable to health-checks than the application.
11078 This parameter is ignored if the "check" parameter is not set. See also the
11079 "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +020011080
Simon Hormand60d6912013-11-25 10:46:36 +090011081agent-check
11082 Enable an auxiliary agent check which is run independently of a regular
Willy Tarreau81f5d942013-12-09 20:51:51 +010011083 health check. An agent health check is performed by making a TCP connection
11084 to the port set by the "agent-port" parameter and reading an ASCII string.
11085 The string is made of a series of words delimited by spaces, tabs or commas
11086 in any order, optionally terminated by '\r' and/or '\n', each consisting of :
Simon Hormand60d6912013-11-25 10:46:36 +090011087
Willy Tarreau81f5d942013-12-09 20:51:51 +010011088 - An ASCII representation of a positive integer percentage, e.g. "75%".
Simon Hormand60d6912013-11-25 10:46:36 +090011089 Values in this format will set the weight proportional to the initial
Willy Tarreauc5af3a62014-10-07 15:27:33 +020011090 weight of a server as configured when haproxy starts. Note that a zero
11091 weight is reported on the stats page as "DRAIN" since it has the same
11092 effect on the server (it's removed from the LB farm).
Simon Hormand60d6912013-11-25 10:46:36 +090011093
Nenad Merdanovic174dd372016-04-24 23:10:06 +020011094 - The string "maxconn:" followed by an integer (no space between). Values in
11095 this format will set the maxconn of a server. The maximum number of
11096 connections advertised needs to be multipled by the number of load balancers
11097 and different backends that use this health check to get the total number
11098 of connections the server might receive. Example: maxconn:30
11099
Willy Tarreau81f5d942013-12-09 20:51:51 +010011100 - The word "ready". This will turn the server's administrative state to the
11101 READY mode, thus cancelling any DRAIN or MAINT state
Simon Hormand60d6912013-11-25 10:46:36 +090011102
Willy Tarreau81f5d942013-12-09 20:51:51 +010011103 - The word "drain". This will turn the server's administrative state to the
11104 DRAIN mode, thus it will not accept any new connections other than those
11105 that are accepted via persistence.
Simon Hormand60d6912013-11-25 10:46:36 +090011106
Willy Tarreau81f5d942013-12-09 20:51:51 +010011107 - The word "maint". This will turn the server's administrative state to the
11108 MAINT mode, thus it will not accept any new connections at all, and health
11109 checks will be stopped.
Simon Hormand60d6912013-11-25 10:46:36 +090011110
Willy Tarreau81f5d942013-12-09 20:51:51 +010011111 - The words "down", "failed", or "stopped", optionally followed by a
11112 description string after a sharp ('#'). All of these mark the server's
11113 operating state as DOWN, but since the word itself is reported on the stats
11114 page, the difference allows an administrator to know if the situation was
11115 expected or not : the service may intentionally be stopped, may appear up
11116 but fail some validity tests, or may be seen as down (eg: missing process,
11117 or port not responding).
Simon Hormand60d6912013-11-25 10:46:36 +090011118
Willy Tarreau81f5d942013-12-09 20:51:51 +010011119 - The word "up" sets back the server's operating state as UP if health checks
11120 also report that the service is accessible.
Simon Hormand60d6912013-11-25 10:46:36 +090011121
Willy Tarreau81f5d942013-12-09 20:51:51 +010011122 Parameters which are not advertised by the agent are not changed. For
11123 example, an agent might be designed to monitor CPU usage and only report a
11124 relative weight and never interact with the operating status. Similarly, an
11125 agent could be designed as an end-user interface with 3 radio buttons
11126 allowing an administrator to change only the administrative state. However,
11127 it is important to consider that only the agent may revert its own actions,
11128 so if a server is set to DRAIN mode or to DOWN state using the agent, the
11129 agent must implement the other equivalent actions to bring the service into
11130 operations again.
Simon Hormand60d6912013-11-25 10:46:36 +090011131
Simon Horman2f1f9552013-11-25 10:46:37 +090011132 Failure to connect to the agent is not considered an error as connectivity
11133 is tested by the regular health check which is enabled by the "check"
Willy Tarreau81f5d942013-12-09 20:51:51 +010011134 parameter. Warning though, it is not a good idea to stop an agent after it
11135 reports "down", since only an agent reporting "up" will be able to turn the
11136 server up again. Note that the CLI on the Unix stats socket is also able to
Willy Tarreau989222a2016-01-15 10:26:26 +010011137 force an agent's result in order to work around a bogus agent if needed.
Simon Horman2f1f9552013-11-25 10:46:37 +090011138
Willy Tarreau81f5d942013-12-09 20:51:51 +010011139 Requires the "agent-port" parameter to be set. See also the "agent-inter"
Frédéric Lécailled2376272017-03-21 18:52:12 +010011140 and "no-agent-check" parameters.
Simon Hormand60d6912013-11-25 10:46:36 +090011141
James Brown55f9ff12015-10-21 18:19:05 -070011142agent-send <string>
11143 If this option is specified, haproxy will send the given string (verbatim)
11144 to the agent server upon connection. You could, for example, encode
11145 the backend name into this string, which would enable your agent to send
11146 different responses based on the backend. Make sure to include a '\n' if
11147 you want to terminate your request with a newline.
11148
Simon Hormand60d6912013-11-25 10:46:36 +090011149agent-inter <delay>
11150 The "agent-inter" parameter sets the interval between two agent checks
11151 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
11152
11153 Just as with every other time-based parameter, it may be entered in any
11154 other explicit unit among { us, ms, s, m, h, d }. The "agent-inter"
11155 parameter also serves as a timeout for agent checks "timeout check" is
11156 not set. In order to reduce "resonance" effects when multiple servers are
11157 hosted on the same hardware, the agent and health checks of all servers
11158 are started with a small time offset between them. It is also possible to
11159 add some random noise in the agent and health checks interval using the
11160 global "spread-checks" keyword. This makes sense for instance when a lot
11161 of backends use the same servers.
11162
11163 See also the "agent-check" and "agent-port" parameters.
11164
Misiek768d8602017-01-09 09:52:43 +010011165agent-addr <addr>
11166 The "agent-addr" parameter sets address for agent check.
11167
11168 You can offload agent-check to another target, so you can make single place
11169 managing status and weights of servers defined in haproxy in case you can't
11170 make self-aware and self-managing services. You can specify both IP or
11171 hostname, it will be resolved.
11172
Simon Hormand60d6912013-11-25 10:46:36 +090011173agent-port <port>
11174 The "agent-port" parameter sets the TCP port used for agent checks.
11175
11176 See also the "agent-check" and "agent-inter" parameters.
11177
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011178backup
11179 When "backup" is present on a server line, the server is only used in load
11180 balancing when all other non-backup servers are unavailable. Requests coming
11181 with a persistence cookie referencing the server will always be served
11182 though. By default, only the first operational backup server is used, unless
Frédéric Lécailled2376272017-03-21 18:52:12 +010011183 the "allbackups" option is set in the backend. See also the "no-backup" and
11184 "allbackups" options.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011185
Emeric Brunef42d922012-10-11 16:11:36 +020011186ca-file <cafile>
11187 This setting is only available when support for OpenSSL was built in. It
11188 designates a PEM file from which to load CA certificates used to verify
11189 server's certificate.
11190
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011191check
11192 This option enables health checks on the server. By default, a server is
Patrick Mézardb7aeec62012-01-22 16:01:22 +010011193 always considered available. If "check" is set, the server is available when
11194 accepting periodic TCP connections, to ensure that it is really able to serve
11195 requests. The default address and port to send the tests to are those of the
11196 server, and the default source is the same as the one defined in the
11197 backend. It is possible to change the address using the "addr" parameter, the
11198 port using the "port" parameter, the source address using the "source"
11199 address, and the interval and timers using the "inter", "rise" and "fall"
Simon Hormanafc47ee2013-11-25 10:46:35 +090011200 parameters. The request method is define in the backend using the "httpchk",
11201 "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please
Frédéric Lécailled2376272017-03-21 18:52:12 +010011202 refer to those options and parameters for more information. See also
11203 "no-check" option.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011204
Willy Tarreau6c16adc2012-10-05 00:04:16 +020011205check-send-proxy
11206 This option forces emission of a PROXY protocol line with outgoing health
11207 checks, regardless of whether the server uses send-proxy or not for the
11208 normal traffic. By default, the PROXY protocol is enabled for health checks
11209 if it is already enabled for normal traffic and if no "port" nor "addr"
11210 directive is present. However, if such a directive is present, the
11211 "check-send-proxy" option needs to be used to force the use of the
11212 protocol. See also the "send-proxy" option for more information.
11213
Olivier Houchard9130a962017-10-17 17:33:43 +020011214check-sni
11215 This option allows you to specify the SNI to be used when doing health checks
11216 over SSL.
11217
Willy Tarreau763a95b2012-10-04 23:15:39 +020011218check-ssl
11219 This option forces encryption of all health checks over SSL, regardless of
11220 whether the server uses SSL or not for the normal traffic. This is generally
11221 used when an explicit "port" or "addr" directive is specified and SSL health
11222 checks are not inherited. It is important to understand that this option
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011223 inserts an SSL transport layer below the checks, so that a simple TCP connect
Willy Tarreau763a95b2012-10-04 23:15:39 +020011224 check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
11225 common use is to send HTTPS checks by combining "httpchk" with SSL checks.
11226 All SSL settings are common to health checks and traffic (eg: ciphers).
Frédéric Lécailled2376272017-03-21 18:52:12 +010011227 See the "ssl" option for more information and "no-check-ssl" to disable
11228 this option.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011229
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011230ciphers <ciphers>
11231 This option sets the string describing the list of cipher algorithms that is
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011232 is negotiated during the SSL/TLS handshake with the server. The format of the
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011233 string is defined in "man 1 ciphers". When SSL is used to communicate with
11234 servers on the local network, it is common to see a weaker set of algorithms
11235 than what is used over the internet. Doing so reduces CPU usage on both the
11236 server and haproxy while still keeping it compatible with deployed software.
11237 Some algorithms such as RC4-SHA1 are reasonably cheap. If no security at all
11238 is needed and just connectivity, using DES can be appropriate.
11239
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011240cookie <value>
11241 The "cookie" parameter sets the cookie value assigned to the server to
11242 <value>. This value will be checked in incoming requests, and the first
11243 operational server possessing the same value will be selected. In return, in
11244 cookie insertion or rewrite modes, this value will be assigned to the cookie
11245 sent to the client. There is nothing wrong in having several servers sharing
11246 the same cookie value, and it is in fact somewhat common between normal and
11247 backup servers. See also the "cookie" keyword in backend section.
11248
Emeric Brunef42d922012-10-11 16:11:36 +020011249crl-file <crlfile>
11250 This setting is only available when support for OpenSSL was built in. It
11251 designates a PEM file from which to load certificate revocation list used
11252 to verify server's certificate.
11253
Emeric Bruna7aa3092012-10-26 12:58:00 +020011254crt <cert>
11255 This setting is only available when support for OpenSSL was built in.
11256 It designates a PEM file from which to load both a certificate and the
11257 associated private key. This file can be built by concatenating both PEM
11258 files into one. This certificate will be sent if the server send a client
11259 certificate request.
11260
Willy Tarreau96839092010-03-29 10:02:24 +020011261disabled
11262 The "disabled" keyword starts the server in the "disabled" state. That means
11263 that it is marked down in maintenance mode, and no connection other than the
11264 ones allowed by persist mode will reach it. It is very well suited to setup
11265 new servers, because normal traffic will never reach them, while it is still
11266 possible to test the service by making use of the force-persist mechanism.
Frédéric Lécailled2376272017-03-21 18:52:12 +010011267 See also "enabled" setting.
Willy Tarreau96839092010-03-29 10:02:24 +020011268
Frédéric Lécailled2376272017-03-21 18:52:12 +010011269enabled
11270 This option may be used as 'server' setting to reset any 'disabled'
11271 setting which would have been inherited from 'default-server' directive as
11272 default value.
11273 It may also be used as 'default-server' setting to reset any previous
11274 'default-server' 'disabled' setting.
Willy Tarreau96839092010-03-29 10:02:24 +020011275
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011276error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +010011277 If health observing is enabled, the "error-limit" parameter specifies the
11278 number of consecutive errors that triggers event selected by the "on-error"
11279 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011280
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011281 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011282
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011283fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011284 The "fall" parameter states that a server will be considered as dead after
11285 <count> consecutive unsuccessful health checks. This value defaults to 3 if
11286 unspecified. See also the "check", "inter" and "rise" parameters.
11287
Emeric Brun8694b9a2012-10-05 14:39:07 +020011288force-sslv3
11289 This option enforces use of SSLv3 only when SSL is used to communicate with
11290 the server. SSLv3 is generally less expensive than the TLS counterparts for
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011291 high connection rates. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011292 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020011293
11294force-tlsv10
11295 This option enforces use of TLSv1.0 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011296 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011297 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020011298
11299force-tlsv11
11300 This option enforces use of TLSv1.1 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011301 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011302 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020011303
11304force-tlsv12
11305 This option enforces use of TLSv1.2 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011306 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011307 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020011308
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011309force-tlsv13
11310 This option enforces use of TLSv1.3 only when SSL is used to communicate with
11311 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011312 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011313
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011314id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +020011315 Set a persistent ID for the server. This ID must be positive and unique for
11316 the proxy. An unused ID will automatically be assigned if unset. The first
11317 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011318
Willy Tarreau6a031d12016-11-07 19:42:35 +010011319init-addr {last | libc | none | <ip>},[...]*
11320 Indicate in what order the server's address should be resolved upon startup
11321 if it uses an FQDN. Attempts are made to resolve the address by applying in
11322 turn each of the methods mentionned in the comma-delimited list. The first
11323 method which succeeds is used. If the end of the list is reached without
11324 finding a working method, an error is thrown. Method "last" suggests to pick
11325 the address which appears in the state file (see "server-state-file"). Method
11326 "libc" uses the libc's internal resolver (gethostbyname() or getaddrinfo()
11327 depending on the operating system and build options). Method "none"
11328 specifically indicates that the server should start without any valid IP
11329 address in a down state. It can be useful to ignore some DNS issues upon
11330 startup, waiting for the situation to get fixed later. Finally, an IP address
11331 (IPv4 or IPv6) may be provided. It can be the currently known address of the
11332 server (eg: filled by a configuration generator), or the address of a dummy
11333 server used to catch old sessions and present them with a decent error
11334 message for example. When the "first" load balancing algorithm is used, this
11335 IP address could point to a fake server used to trigger the creation of new
11336 instances on the fly. This option defaults to "last,libc" indicating that the
11337 previous address found in the state file (if any) is used first, otherwise
11338 the libc's resolver is used. This ensures continued compatibility with the
11339 historic behaviour.
11340
11341 Example:
11342 defaults
11343 # never fail on address resolution
11344 default-server init-addr last,libc,none
11345
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011346inter <delay>
11347fastinter <delay>
11348downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011349 The "inter" parameter sets the interval between two consecutive health checks
11350 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
11351 It is also possible to use "fastinter" and "downinter" to optimize delays
11352 between checks depending on the server state :
11353
Pieter Baauw44fc9df2015-09-17 21:30:46 +020011354 Server state | Interval used
11355 ----------------------------------------+----------------------------------
11356 UP 100% (non-transitional) | "inter"
11357 ----------------------------------------+----------------------------------
11358 Transitionally UP (going down "fall"), | "fastinter" if set,
11359 Transitionally DOWN (going up "rise"), | "inter" otherwise.
11360 or yet unchecked. |
11361 ----------------------------------------+----------------------------------
11362 DOWN 100% (non-transitional) | "downinter" if set,
11363 | "inter" otherwise.
11364 ----------------------------------------+----------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +010011365
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011366 Just as with every other time-based parameter, they can be entered in any
11367 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
11368 serves as a timeout for health checks sent to servers if "timeout check" is
11369 not set. In order to reduce "resonance" effects when multiple servers are
Simon Hormand60d6912013-11-25 10:46:36 +090011370 hosted on the same hardware, the agent and health checks of all servers
11371 are started with a small time offset between them. It is also possible to
11372 add some random noise in the agent and health checks interval using the
11373 global "spread-checks" keyword. This makes sense for instance when a lot
11374 of backends use the same servers.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011375
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011376maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011377 The "maxconn" parameter specifies the maximal number of concurrent
11378 connections that will be sent to this server. If the number of incoming
11379 concurrent requests goes higher than this value, they will be queued, waiting
11380 for a connection to be released. This parameter is very important as it can
11381 save fragile servers from going down under extreme loads. If a "minconn"
11382 parameter is specified, the limit becomes dynamic. The default value is "0"
11383 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
11384 the backend's "fullconn" keyword.
11385
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011386maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011387 The "maxqueue" parameter specifies the maximal number of connections which
11388 will wait in the queue for this server. If this limit is reached, next
11389 requests will be redispatched to other servers instead of indefinitely
11390 waiting to be served. This will break persistence but may allow people to
11391 quickly re-log in when the server they try to connect to is dying. The
11392 default value is "0" which means the queue is unlimited. See also the
11393 "maxconn" and "minconn" parameters.
11394
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011395minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011396 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
11397 limit following the backend's load. The server will always accept at least
11398 <minconn> connections, never more than <maxconn>, and the limit will be on
11399 the ramp between both values when the backend has less than <fullconn>
11400 concurrent connections. This makes it possible to limit the load on the
11401 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011402 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011403 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011404
Willy Tarreaud72f0f32015-10-13 14:50:22 +020011405namespace <name>
11406 On Linux, it is possible to specify which network namespace a socket will
11407 belong to. This directive makes it possible to explicitly bind a server to
11408 a namespace different from the default one. Please refer to your operating
11409 system's documentation to find more details about network namespaces.
11410
Frédéric Lécailled2376272017-03-21 18:52:12 +010011411no-agent-check
11412 This option may be used as "server" setting to reset any "agent-check"
11413 setting which would have been inherited from "default-server" directive as
11414 default value.
11415 It may also be used as "default-server" setting to reset any previous
11416 "default-server" "agent-check" setting.
11417
11418no-backup
11419 This option may be used as "server" setting to reset any "backup"
11420 setting which would have been inherited from "default-server" directive as
11421 default value.
11422 It may also be used as "default-server" setting to reset any previous
11423 "default-server" "backup" setting.
11424
11425no-check
11426 This option may be used as "server" setting to reset any "check"
11427 setting which would have been inherited from "default-server" directive as
11428 default value.
11429 It may also be used as "default-server" setting to reset any previous
11430 "default-server" "check" setting.
11431
11432no-check-ssl
11433 This option may be used as "server" setting to reset any "check-ssl"
11434 setting which would have been inherited from "default-server" directive as
11435 default value.
11436 It may also be used as "default-server" setting to reset any previous
11437 "default-server" "check-ssl" setting.
11438
Frédéric Lécailled2376272017-03-21 18:52:12 +010011439no-send-proxy
11440 This option may be used as "server" setting to reset any "send-proxy"
11441 setting which would have been inherited from "default-server" directive as
11442 default value.
11443 It may also be used as "default-server" setting to reset any previous
11444 "default-server" "send-proxy" setting.
11445
11446no-send-proxy-v2
11447 This option may be used as "server" setting to reset any "send-proxy-v2"
11448 setting which would have been inherited from "default-server" directive as
11449 default value.
11450 It may also be used as "default-server" setting to reset any previous
11451 "default-server" "send-proxy-v2" setting.
11452
11453no-send-proxy-v2-ssl
11454 This option may be used as "server" setting to reset any "send-proxy-v2-ssl"
11455 setting which would have been inherited from "default-server" directive as
11456 default value.
11457 It may also be used as "default-server" setting to reset any previous
11458 "default-server" "send-proxy-v2-ssl" setting.
11459
11460no-send-proxy-v2-ssl-cn
11461 This option may be used as "server" setting to reset any "send-proxy-v2-ssl-cn"
11462 setting which would have been inherited from "default-server" directive as
11463 default value.
11464 It may also be used as "default-server" setting to reset any previous
11465 "default-server" "send-proxy-v2-ssl-cn" setting.
11466
11467no-ssl
11468 This option may be used as "server" setting to reset any "ssl"
11469 setting which would have been inherited from "default-server" directive as
11470 default value.
11471 It may also be used as "default-server" setting to reset any previous
11472 "default-server" "ssl" setting.
11473
Willy Tarreau2a3fb1c2015-02-05 16:47:07 +010011474no-ssl-reuse
11475 This option disables SSL session reuse when SSL is used to communicate with
11476 the server. It will force the server to perform a full handshake for every
11477 new connection. It's probably only useful for benchmarking, troubleshooting,
11478 and for paranoid users.
11479
Emeric Brun9b3009b2012-10-05 11:55:06 +020011480no-sslv3
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011481 This option disables support for SSLv3 when SSL is used to communicate with
11482 the server. Note that SSLv2 is disabled in the code and cannot be enabled
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011483 using any configuration option. Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011484
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020011485 Supported in default-server: No
11486
Emeric Brunf9c5c472012-10-11 15:28:34 +020011487no-tls-tickets
11488 This setting is only available when support for OpenSSL was built in. It
11489 disables the stateless session resumption (RFC 5077 TLS Ticket
11490 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011491 session resumption is more expensive in CPU usage for servers. This option
11492 is also available on global statement "ssl-default-server-options".
Frédéric Lécailled2376272017-03-21 18:52:12 +010011493 See also "tls-tickets".
Emeric Brunf9c5c472012-10-11 15:28:34 +020011494
Emeric Brun9b3009b2012-10-05 11:55:06 +020011495no-tlsv10
Emeric Brun8694b9a2012-10-05 14:39:07 +020011496 This option disables support for TLSv1.0 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020011497 the server. Note that SSLv2 is disabled in the code and cannot be enabled
11498 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011499 often makes sense to disable it when communicating with local servers. This
11500 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011501 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011502
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020011503 Supported in default-server: No
11504
Emeric Brun9b3009b2012-10-05 11:55:06 +020011505no-tlsv11
Emeric Brun8694b9a2012-10-05 14:39:07 +020011506 This option disables support for TLSv1.1 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020011507 the server. Note that SSLv2 is disabled in the code and cannot be enabled
11508 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011509 often makes sense to disable it when communicating with local servers. This
11510 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011511 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011512
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020011513 Supported in default-server: No
11514
Emeric Brun9b3009b2012-10-05 11:55:06 +020011515no-tlsv12
Emeric Brun8694b9a2012-10-05 14:39:07 +020011516 This option disables support for TLSv1.2 when SSL is used to communicate with
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011517 the server. Note that SSLv2 is disabled in the code and cannot be enabled
11518 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011519 often makes sense to disable it when communicating with local servers. This
11520 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011521 Use "ssl-min-ver" and "ssl-max-ver" instead.
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011522
11523 Supported in default-server: No
11524
11525no-tlsv13
11526 This option disables support for TLSv1.3 when SSL is used to communicate with
11527 the server. Note that SSLv2 is disabled in the code and cannot be enabled
11528 using any configuration option. TLSv1 is more expensive than SSLv3 so it
11529 often makes sense to disable it when communicating with local servers. This
11530 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011531 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011532
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020011533 Supported in default-server: No
11534
Frédéric Lécailled2376272017-03-21 18:52:12 +010011535no-verifyhost
11536 This option may be used as "server" setting to reset any "verifyhost"
11537 setting which would have been inherited from "default-server" directive as
11538 default value.
11539 It may also be used as "default-server" setting to reset any previous
11540 "default-server" "verifyhost" setting.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011541
Simon Hormanfa461682011-06-25 09:39:49 +090011542non-stick
11543 Never add connections allocated to this sever to a stick-table.
11544 This may be used in conjunction with backup to ensure that
11545 stick-table persistence is disabled for backup servers.
11546
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011547observe <mode>
11548 This option enables health adjusting based on observing communication with
11549 the server. By default this functionality is disabled and enabling it also
11550 requires to enable health checks. There are two supported modes: "layer4" and
11551 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
11552 significant. In layer7, which is only allowed for http proxies, responses
11553 received from server are verified, like valid/wrong http code, unparsable
Willy Tarreau150d1462012-03-10 08:19:02 +010011554 headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011555
11556 See also the "check", "on-error" and "error-limit".
11557
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011558on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010011559 Select what should happen when enough consecutive errors are detected.
11560 Currently, four modes are available:
11561 - fastinter: force fastinter
11562 - fail-check: simulate a failed check, also forces fastinter (default)
11563 - sudden-death: simulate a pre-fatal failed health check, one more failed
11564 check will mark a server down, forces fastinter
11565 - mark-down: mark the server immediately down and force fastinter
11566
11567 See also the "check", "observe" and "error-limit".
11568
Simon Hormane0d1bfb2011-06-21 14:34:58 +090011569on-marked-down <action>
11570 Modify what occurs when a server is marked down.
11571 Currently one action is available:
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070011572 - shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
11573 all connections to the server are immediately terminated when the server
11574 goes down. It might be used if the health check detects more complex cases
11575 than a simple connection status, and long timeouts would cause the service
11576 to remain unresponsive for too long a time. For instance, a health check
11577 might detect that a database is stuck and that there's no chance to reuse
11578 existing connections anymore. Connections killed this way are logged with
11579 a 'D' termination code (for "Down").
Simon Hormane0d1bfb2011-06-21 14:34:58 +090011580
11581 Actions are disabled by default
11582
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070011583on-marked-up <action>
11584 Modify what occurs when a server is marked up.
11585 Currently one action is available:
11586 - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
11587 done only if the server is not in backup state and if it is not disabled
11588 (it must have an effective weight > 0). This can be used sometimes to force
11589 an active server to take all the traffic back after recovery when dealing
11590 with long sessions (eg: LDAP, SQL, ...). Doing this can cause more trouble
11591 than it tries to solve (eg: incomplete transactions), so use this feature
11592 with extreme care. Sessions killed because a server comes up are logged
11593 with an 'U' termination code (for "Up").
11594
11595 Actions are disabled by default
11596
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011597port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011598 Using the "port" parameter, it becomes possible to use a different port to
11599 send health-checks. On some servers, it may be desirable to dedicate a port
11600 to a specific component able to perform complex tests which are more suitable
11601 to health-checks than the application. It is common to run a simple script in
11602 inetd for instance. This parameter is ignored if the "check" parameter is not
11603 set. See also the "addr" parameter.
11604
11605redir <prefix>
11606 The "redir" parameter enables the redirection mode for all GET and HEAD
11607 requests addressing this server. This means that instead of having HAProxy
11608 forward the request to the server, it will send an "HTTP 302" response with
11609 the "Location" header composed of this prefix immediately followed by the
11610 requested URI beginning at the leading '/' of the path component. That means
11611 that no trailing slash should be used after <prefix>. All invalid requests
11612 will be rejected, and all non-GET or HEAD requests will be normally served by
11613 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011614 mangling nor cookie insertion is possible in the response. However, cookies in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011615 requests are still analysed, making this solution completely usable to direct
11616 users to a remote location in case of local disaster. Main use consists in
11617 increasing bandwidth for static servers by having the clients directly
11618 connect to them. Note: never use a relative location here, it would cause a
11619 loop between the client and HAProxy!
11620
11621 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
11622
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011623rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011624 The "rise" parameter states that a server will be considered as operational
11625 after <count> consecutive successful health checks. This value defaults to 2
11626 if unspecified. See also the "check", "inter" and "fall" parameters.
11627
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011628resolve-prefer <family>
11629 When DNS resolution is enabled for a server and multiple IP addresses from
11630 different families are returned, HAProxy will prefer using an IP address
11631 from the family mentioned in the "resolve-prefer" parameter.
11632 Available families: "ipv4" and "ipv6"
11633
Baptiste Assmannc4aabae2015-08-04 22:43:06 +020011634 Default value: ipv6
11635
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020011636 Example:
11637
11638 server s1 app1.domain.com:80 resolvers mydns resolve-prefer ipv6
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011639
Thierry Fournierac88cfe2016-02-17 22:05:30 +010011640resolve-net <network>[,<network[,...]]
11641 This options prioritize th choice of an ip address matching a network. This is
11642 useful with clouds to prefer a local ip. In some cases, a cloud high
Tim Düsterhus4896c442016-11-29 02:15:19 +010011643 availability service can be announced with many ip addresses on many
Thierry Fournierac88cfe2016-02-17 22:05:30 +010011644 differents datacenters. The latency between datacenter is not negligible, so
11645 this patch permitsto prefers a local datacenter. If none address matchs the
11646 configured network, another address is selected.
11647
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020011648 Example:
11649
11650 server s1 app1.domain.com:80 resolvers mydns resolve-net 10.0.0.0/8
Thierry Fournierac88cfe2016-02-17 22:05:30 +010011651
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011652resolvers <id>
11653 Points to an existing "resolvers" section to resolve current server's
11654 hostname.
11655
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020011656 Example:
11657
11658 server s1 app1.domain.com:80 check resolvers mydns
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011659
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020011660 See also section 5.3
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011661
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010011662send-proxy
11663 The "send-proxy" parameter enforces use of the PROXY protocol over any
11664 connection established to this server. The PROXY protocol informs the other
11665 end about the layer 3/4 addresses of the incoming connection, so that it can
11666 know the client's address or the public address it accessed to, whatever the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010011667 upper layer protocol. For connections accepted by an "accept-proxy" or
11668 "accept-netscaler-cip" listener, the advertised address will be used. Only
11669 TCPv4 and TCPv6 address families are supported. Other families such as
11670 Unix sockets, will report an UNKNOWN family. Servers using this option can
11671 fully be chained to another instance of haproxy listening with an
11672 "accept-proxy" setting. This setting must not be used if the server isn't
11673 aware of the protocol. When health checks are sent to the server, the PROXY
11674 protocol is automatically used when this option is set, unless there is an
11675 explicit "port" or "addr" directive, in which case an explicit
11676 "check-send-proxy" directive would also be needed to use the PROXY protocol.
Frédéric Lécailled2376272017-03-21 18:52:12 +010011677 See also the "no-send-proxy" option of this section and "accept-proxy" and
11678 "accept-netscaler-cip" option of the "bind" keyword.
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010011679
David Safb76832014-05-08 23:42:08 -040011680send-proxy-v2
11681 The "send-proxy-v2" parameter enforces use of the PROXY protocol version 2
11682 over any connection established to this server. The PROXY protocol informs
11683 the other end about the layer 3/4 addresses of the incoming connection, so
11684 that it can know the client's address or the public address it accessed to,
Emmanuel Hocdet404d9782017-10-24 10:55:14 +020011685 whatever the upper layer protocol. It also send ALPN information if an alpn
11686 have been negotiated. This setting must not be used if the server isn't aware
11687 of this version of the protocol. See also the "no-send-proxy-v2" option of
11688 this section and send-proxy" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040011689
11690send-proxy-v2-ssl
11691 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
11692 2 over any connection established to this server. The PROXY protocol informs
11693 the other end about the layer 3/4 addresses of the incoming connection, so
11694 that it can know the client's address or the public address it accessed to,
11695 whatever the upper layer protocol. In addition, the SSL information extension
11696 of the PROXY protocol is added to the PROXY protocol header. This setting
11697 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 +010011698 See also the "no-send-proxy-v2-ssl" option of this section and the
11699 "send-proxy-v2" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040011700
11701send-proxy-v2-ssl-cn
11702 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
11703 2 over any connection established to this server. The PROXY protocol informs
11704 the other end about the layer 3/4 addresses of the incoming connection, so
11705 that it can know the client's address or the public address it accessed to,
11706 whatever the upper layer protocol. In addition, the SSL information extension
11707 of the PROXY protocol, along along with the Common Name from the subject of
11708 the client certificate (if any), is added to the PROXY protocol header. This
11709 setting must not be used if the server isn't aware of this version of the
Frédéric Lécailled2376272017-03-21 18:52:12 +010011710 protocol. See also the "no-send-proxy-v2-ssl-cn" option of this section and the
11711 "send-proxy-v2" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040011712
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011713slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011714 The "slowstart" parameter for a server accepts a value in milliseconds which
11715 indicates after how long a server which has just come back up will run at
11716 full speed. Just as with every other time-based parameter, it can be entered
11717 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
11718 linearly from 0 to 100% during this time. The limitation applies to two
11719 parameters :
11720
11721 - maxconn: the number of connections accepted by the server will grow from 1
11722 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
11723
11724 - weight: when the backend uses a dynamic weighted algorithm, the weight
11725 grows linearly from 1 to 100%. In this case, the weight is updated at every
11726 health-check. For this reason, it is important that the "inter" parameter
11727 is smaller than the "slowstart", in order to maximize the number of steps.
11728
11729 The slowstart never applies when haproxy starts, otherwise it would cause
11730 trouble to running servers. It only applies when a server has been previously
11731 seen as failed.
11732
Willy Tarreau732eac42015-07-09 11:40:25 +020011733sni <expression>
11734 The "sni" parameter evaluates the sample fetch expression, converts it to a
11735 string and uses the result as the host name sent in the SNI TLS extension to
11736 the server. A typical use case is to send the SNI received from the client in
11737 a bridged HTTPS scenario, using the "ssl_fc_sni" sample fetch for the
Willy Tarreau2ab88672017-07-05 18:23:03 +020011738 expression, though alternatives such as req.hdr(host) can also make sense. If
11739 "verify required" is set (which is the recommended setting), the resulting
Willy Tarreauad92a9a2017-07-28 11:38:41 +020011740 name will also be matched against the server certificate's names. See the
11741 "verify" directive for more details.
Willy Tarreau732eac42015-07-09 11:40:25 +020011742
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020011743source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +020011744source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020011745source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011746 The "source" parameter sets the source address which will be used when
11747 connecting to the server. It follows the exact same parameters and principle
11748 as the backend "source" keyword, except that it only applies to the server
11749 referencing it. Please consult the "source" keyword for details.
11750
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020011751 Additionally, the "source" statement on a server line allows one to specify a
11752 source port range by indicating the lower and higher bounds delimited by a
11753 dash ('-'). Some operating systems might require a valid IP address when a
11754 source port range is specified. It is permitted to have the same IP/range for
11755 several servers. Doing so makes it possible to bypass the maximum of 64k
11756 total concurrent connections. The limit will then reach 64k connections per
11757 server.
11758
Lukas Tribus7d56c6d2016-09-13 09:51:15 +000011759 Since Linux 4.2/libc 2.23 IP_BIND_ADDRESS_NO_PORT is set for connections
11760 specifying the source address without port(s).
11761
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011762ssl
Willy Tarreau44f65392013-06-25 07:56:20 +020011763 This option enables SSL ciphering on outgoing connections to the server. It
11764 is critical to verify server certificates using "verify" when using SSL to
11765 connect to servers, otherwise the communication is prone to trivial man in
11766 the-middle attacks rendering SSL useless. When this option is used, health
11767 checks are automatically sent in SSL too unless there is a "port" or an
11768 "addr" directive indicating the check should be sent to a different location.
Frédéric Lécailled2376272017-03-21 18:52:12 +010011769 See the "no-ssl" to disable "ssl" option and "check-ssl" option to force
11770 SSL health checks.
Willy Tarreau763a95b2012-10-04 23:15:39 +020011771
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011772ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
11773 This option enforces use of <version> or lower when SSL is used to communicate
11774 with the server. This option is also available on global statement
11775 "ssl-default-server-options". See also "ssl-min-ver".
11776
11777ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
11778 This option enforces use of <version> or upper when SSL is used to communicate
11779 with the server. This option is also available on global statement
11780 "ssl-default-server-options". See also "ssl-max-ver".
11781
Frédéric Lécailled2376272017-03-21 18:52:12 +010011782ssl-reuse
11783 This option may be used as "server" setting to reset any "no-ssl-reuse"
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" "no-ssl-reuse" setting.
11788
11789stick
11790 This option may be used as "server" setting to reset any "non-stick"
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" "non-stick" setting.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020011795
Willy Tarreau163d4622015-10-13 16:16:41 +020011796tcp-ut <delay>
11797 Sets the TCP User Timeout for all outgoing connections to this server. This
11798 option is available on Linux since version 2.6.37. It allows haproxy to
11799 configure a timeout for sockets which contain data not receiving an
Tim Düsterhus4896c442016-11-29 02:15:19 +010011800 acknowledgement for the configured delay. This is especially useful on
Willy Tarreau163d4622015-10-13 16:16:41 +020011801 long-lived connections experiencing long idle periods such as remote
11802 terminals or database connection pools, where the client and server timeouts
11803 must remain high to allow a long period of idle, but where it is important to
11804 detect that the server has disappeared in order to release all resources
11805 associated with its connection (and the client's session). One typical use
11806 case is also to force dead server connections to die when health checks are
11807 too slow or during a soft reload since health checks are then disabled. The
11808 argument is a delay expressed in milliseconds by default. This only works for
11809 regular TCP connections, and is ignored for other protocols.
11810
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011811track [<proxy>/]<server>
Willy Tarreau32091232014-05-16 13:52:00 +020011812 This option enables ability to set the current state of the server by tracking
11813 another one. It is possible to track a server which itself tracks another
11814 server, provided that at the end of the chain, a server has health checks
11815 enabled. If <proxy> is omitted the current one is used. If disable-on-404 is
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011816 used, it has to be enabled on both proxies.
11817
Frédéric Lécailled2376272017-03-21 18:52:12 +010011818tls-tickets
11819 This option may be used as "server" setting to reset any "no-tls-tickets"
11820 setting which would have been inherited from "default-server" directive as
11821 default value.
11822 It may also be used as "default-server" setting to reset any previous
11823 "default-server" "no-tlsv-tickets" setting.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011824
Emeric Brunef42d922012-10-11 16:11:36 +020011825verify [none|required]
11826 This setting is only available when support for OpenSSL was built in. If set
Emeric Brun850efd52014-01-29 12:24:34 +010011827 to 'none', server certificate is not verified. In the other case, The
Willy Tarreauad92a9a2017-07-28 11:38:41 +020011828 certificate provided by the server is verified using CAs from 'ca-file' and
11829 optional CRLs from 'crl-file' after having checked that the names provided in
11830 the certificate's subject and subjectAlternateNames attributs match either
11831 the name passed using the "sni" directive, or if not provided, the static
11832 host name passed using the "verifyhost" directive. When no name is found, the
11833 certificate's names are ignored. For this reason, without SNI it's important
11834 to use "verifyhost". On verification failure the handshake is aborted. It is
11835 critically important to verify server certificates when using SSL to connect
11836 to servers, otherwise the communication is prone to trivial man-in-the-middle
11837 attacks rendering SSL totally useless. Unless "ssl_server_verify" appears in
11838 the global section, "verify" is set to "required" by default.
Emeric Brunef42d922012-10-11 16:11:36 +020011839
Evan Broderbe554312013-06-27 00:05:25 -070011840verifyhost <hostname>
11841 This setting is only available when support for OpenSSL was built in, and
Willy Tarreauad92a9a2017-07-28 11:38:41 +020011842 only takes effect if 'verify required' is also specified. This directive sets
11843 a default static hostname to check the server's certificate against when no
11844 SNI was used to connect to the server. If SNI is not used, this is the only
11845 way to enable hostname verification. This static hostname, when set, will
11846 also be used for health checks (which cannot provide an SNI value). If none
11847 of the hostnames in the certificate match the specified hostname, the
11848 handshake is aborted. The hostnames in the server-provided certificate may
11849 include wildcards. See also "verify", "sni" and "no-verifyhost" options.
Evan Broderbe554312013-06-27 00:05:25 -070011850
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010011851weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011852 The "weight" parameter is used to adjust the server's weight relative to
11853 other servers. All servers will receive a load proportional to their weight
11854 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +020011855 load. The default weight is 1, and the maximal value is 256. A value of 0
11856 means the server will not participate in load-balancing but will still accept
11857 persistent connections. If this parameter is used to distribute the load
11858 according to server's capacity, it is recommended to start with values which
11859 can both grow and shrink, for instance between 10 and 100 to leave enough
11860 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011861
11862
Cyril Bonté46175dd2015-07-02 22:45:32 +0200118635.3. Server IP address resolution using DNS
11864-------------------------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011865
Baptiste Assmann62b75b42015-09-09 01:11:36 +020011866HAProxy allows using a host name on the server line to retrieve its IP address
11867using name servers. By default, HAProxy resolves the name when parsing the
11868configuration file, at startup and cache the result for the process' life.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011869This is not sufficient in some cases, such as in Amazon where a server's IP
11870can change after a reboot or an ELB Virtual IP can change based on current
11871workload.
11872This chapter describes how HAProxy can be configured to process server's name
11873resolution at run time.
11874Whether run time server name resolution has been enable or not, HAProxy will
11875carry on doing the first resolution when parsing the configuration.
11876
11877
Cyril Bonté46175dd2015-07-02 22:45:32 +0200118785.3.1. Global overview
11879----------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011880
11881As we've seen in introduction, name resolution in HAProxy occurs at two
11882different steps of the process life:
11883
11884 1. when starting up, HAProxy parses the server line definition and matches a
11885 host name. It uses libc functions to get the host name resolved. This
11886 resolution relies on /etc/resolv.conf file.
11887
Christopher Faulet67957bd2017-09-27 11:00:59 +020011888 2. at run time, HAProxy performs periodically name resolutions for servers
11889 requiring DNS resolutions.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011890
11891A few other events can trigger a name resolution at run time:
11892 - when a server's health check ends up in a connection timeout: this may be
11893 because the server has a new IP address. So we need to trigger a name
11894 resolution to know this new IP.
11895
Christopher Faulet67957bd2017-09-27 11:00:59 +020011896When using resolvers, the server name can either be a hostname, or a SRV label.
11897HAProxy considers anything that starts with an underscore as a SRV label. If a
11898SRV label is specified, then the corresponding SRV records will be retrieved
11899from the DNS server, and the provided hostnames will be used. The SRV label
11900will be checked periodically, and if any server are added or removed, haproxy
11901will automatically do the same.
Olivier Houchardecfa18d2017-08-07 17:30:03 +020011902
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011903A few things important to notice:
11904 - all the name servers are queried in the mean time. HAProxy will process the
11905 first valid response.
11906
11907 - a resolution is considered as invalid (NX, timeout, refused), when all the
11908 servers return an error.
11909
11910
Cyril Bonté46175dd2015-07-02 22:45:32 +0200119115.3.2. The resolvers section
11912----------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011913
11914This section is dedicated to host information related to name resolution in
Christopher Faulet67957bd2017-09-27 11:00:59 +020011915HAProxy. There can be as many as resolvers section as needed. Each section can
11916contain many name servers.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011917
Baptiste Assmann62b75b42015-09-09 01:11:36 +020011918When multiple name servers are configured in a resolvers section, then HAProxy
11919uses the first valid response. In case of invalid responses, only the last one
11920is treated. Purpose is to give the chance to a slow server to deliver a valid
11921answer after a fast faulty or outdated server.
11922
11923When each server returns a different error type, then only the last error is
Christopher Faulet67957bd2017-09-27 11:00:59 +020011924used by HAProxy. The following processing is applied on this error:
Baptiste Assmann62b75b42015-09-09 01:11:36 +020011925
Christopher Faulet67957bd2017-09-27 11:00:59 +020011926 1. HAProxy retries the same DNS query with a new query type. The A queries are
11927 switch to AAAA or the opposite. SRV queries are not concerned here. Timeout
11928 errors are also excluded.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020011929
Christopher Faulet67957bd2017-09-27 11:00:59 +020011930 2. When the fallback on the query type was done (or not applicable), HAProxy
11931 retries the original DNS query, with the preferred query type.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020011932
Christopher Faulet67957bd2017-09-27 11:00:59 +020011933 3. HAProxy retries previous steps <resolve_retires> times. If no valid
11934 response is received after that, it stops the DNS resolution and reports
11935 the error.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020011936
Christopher Faulet67957bd2017-09-27 11:00:59 +020011937For example, with 2 name servers configured in a resolvers section, the
11938following scenarios are possible:
11939
11940 - First response is valid and is applied directly, second response is
11941 ignored
11942
11943 - First response is invalid and second one is valid, then second response is
11944 applied
11945
11946 - First response is a NX domain and second one a truncated response, then
11947 HAProxy retries the query with a new type
11948
11949 - First response is a NX domain and second one is a timeout, then HAProxy
11950 retries the query with a new type
11951
11952 - Query timed out for both name servers, then HAProxy retries it with the
11953 same query type
Baptiste Assmann62b75b42015-09-09 01:11:36 +020011954
Olivier Houcharda8c6db82017-07-06 18:46:47 +020011955As a DNS server may not answer all the IPs in one DNS request, haproxy keeps
11956a cache of previous answers, an answer will be considered obsolete after
Christopher Faulet67957bd2017-09-27 11:00:59 +020011957<hold obsolete> seconds without the IP returned.
Olivier Houcharda8c6db82017-07-06 18:46:47 +020011958
Baptiste Assmann62b75b42015-09-09 01:11:36 +020011959
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011960resolvers <resolvers id>
11961 Creates a new name server list labelled <resolvers id>
11962
11963A resolvers section accept the following parameters:
11964
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020011965accepted_payload_size <nb>
11966 Defines the maxium payload size accepted by HAProxy and announced to all the
Christopher Faulet67957bd2017-09-27 11:00:59 +020011967 name servers configured in this resolvers section.
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020011968 <nb> is in bytes. If not set, HAProxy announces 512. (minimal value defined
11969 by RFC 6891)
11970
Baptiste Assmann9d8dbbc2017-08-18 23:35:08 +020011971 Note: to get bigger responses but still be sure that responses won't be
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020011972 dropped on the wire, one can choose a value between 1280 and 1410.
11973
Baptiste Assmann9d8dbbc2017-08-18 23:35:08 +020011974 Note: the maximum allowed value is 8192.
11975
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011976nameserver <id> <ip>:<port>
11977 DNS server description:
11978 <id> : label of the server, should be unique
11979 <ip> : IP address of the server
11980 <port> : port where the DNS service actually runs
11981
11982hold <status> <period>
11983 Defines <period> during which the last name resolution should be kept based
11984 on last resolution <status>
Baptiste Assmann987e16d2016-11-02 22:23:31 +010011985 <status> : last name resolution status. Acceptable values are "nx",
Olivier Houcharda8c6db82017-07-06 18:46:47 +020011986 "other", "refused", "timeout", "valid", "obsolete".
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011987 <period> : interval between two successive name resolution when the last
11988 answer was in <status>. It follows the HAProxy time format.
11989 <period> is in milliseconds by default.
11990
Baptiste Assmann686408b2017-08-18 10:15:42 +020011991 Default value is 10s for "valid", 0s for "obsolete" and 30s for others.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011992
Christopher Faulet67957bd2017-09-27 11:00:59 +020011993resolution_pool_size <nb> (deprecated)
Baptiste Assmann201c07f2017-05-22 15:17:15 +020011994 Defines the number of resolutions available in the pool for this resolvers.
11995 If not defines, it defaults to 64. If your configuration requires more than
11996 <nb>, then HAProxy will return an error when parsing the configuration.
11997
Baptiste Assmann1fa66662015-04-14 00:28:47 +020011998resolve_retries <nb>
11999 Defines the number <nb> of queries to send to resolve a server name before
12000 giving up.
12001 Default value: 3
12002
Baptiste Assmann62b75b42015-09-09 01:11:36 +020012003 A retry occurs on name server timeout or when the full sequence of DNS query
12004 type failover is over and we need to start up from the default ANY query
12005 type.
12006
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012007timeout <event> <time>
12008 Defines timeouts related to name resolution
12009 <event> : the event on which the <time> timeout period applies to.
12010 events available are:
Christopher Faulet67957bd2017-09-27 11:00:59 +020012011 - resolve : default time to trigger name resolutions when no
12012 other time applied.
12013 Default value: 1s
12014 - retry : time between two DNS queries, when no valid response
12015 have been received.
12016 Default value: 1s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012017 <time> : time related to the event. It follows the HAProxy time format.
12018 <time> is expressed in milliseconds.
12019
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020012020 Example:
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012021
12022 resolvers mydns
12023 nameserver dns1 10.0.0.1:53
12024 nameserver dns2 10.0.0.2:53
12025 resolve_retries 3
Christopher Faulet67957bd2017-09-27 11:00:59 +020012026 timeout resolve 1s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012027 timeout retry 1s
Baptiste Assmann987e16d2016-11-02 22:23:31 +010012028 hold other 30s
12029 hold refused 30s
12030 hold nx 30s
12031 hold timeout 30s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012032 hold valid 10s
Olivier Houcharda8c6db82017-07-06 18:46:47 +020012033 hold obsolete 30s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012034
12035
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200120366. HTTP header manipulation
12037---------------------------
12038
12039In HTTP mode, it is possible to rewrite, add or delete some of the request and
12040response headers based on regular expressions. It is also possible to block a
12041request or a response if a particular header matches a regular expression,
12042which is enough to stop most elementary protocol attacks, and to protect
Willy Tarreau70dffda2014-01-30 03:07:23 +010012043against information leak from the internal network.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012044
Willy Tarreau70dffda2014-01-30 03:07:23 +010012045If HAProxy encounters an "Informational Response" (status code 1xx), it is able
12046to process all rsp* rules which can allow, deny, rewrite or delete a header,
12047but it will refuse to add a header to any such messages as this is not
12048HTTP-compliant. The reason for still processing headers in such responses is to
12049stop and/or fix any possible information leak which may happen, for instance
12050because another downstream equipment would unconditionally add a header, or if
12051a server name appears there. When such messages are seen, normal processing
12052still occurs on the next non-informational messages.
Willy Tarreau816b9792009-09-15 21:25:21 +020012053
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012054This section covers common usage of the following keywords, described in detail
12055in section 4.2 :
12056
12057 - reqadd <string>
12058 - reqallow <search>
12059 - reqiallow <search>
12060 - reqdel <search>
12061 - reqidel <search>
12062 - reqdeny <search>
12063 - reqideny <search>
12064 - reqpass <search>
12065 - reqipass <search>
12066 - reqrep <search> <replace>
12067 - reqirep <search> <replace>
12068 - reqtarpit <search>
12069 - reqitarpit <search>
12070 - rspadd <string>
12071 - rspdel <search>
12072 - rspidel <search>
12073 - rspdeny <search>
12074 - rspideny <search>
12075 - rsprep <search> <replace>
12076 - rspirep <search> <replace>
12077
12078With all these keywords, the same conventions are used. The <search> parameter
12079is a POSIX extended regular expression (regex) which supports grouping through
12080parenthesis (without the backslash). Spaces and other delimiters must be
12081prefixed with a backslash ('\') to avoid confusion with a field delimiter.
12082Other characters may be prefixed with a backslash to change their meaning :
12083
12084 \t for a tab
12085 \r for a carriage return (CR)
12086 \n for a new line (LF)
12087 \ to mark a space and differentiate it from a delimiter
12088 \# to mark a sharp and differentiate it from a comment
12089 \\ to use a backslash in a regex
12090 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
12091 \xXX to write the ASCII hex code XX as in the C language
12092
12093The <replace> parameter contains the string to be used to replace the largest
12094portion of text matching the regex. It can make use of the special characters
12095above, and can reference a substring which is delimited by parenthesis in the
12096regex, by writing a backslash ('\') immediately followed by one digit from 0 to
120979 indicating the group position (0 designating the entire line). This practice
12098is very common to users of the "sed" program.
12099
12100The <string> parameter represents the string which will systematically be added
12101after the last header line. It can also use special character sequences above.
12102
12103Notes related to these keywords :
12104---------------------------------
12105 - these keywords are not always convenient to allow/deny based on header
12106 contents. It is strongly recommended to use ACLs with the "block" keyword
12107 instead, resulting in far more flexible and manageable rules.
12108
12109 - lines are always considered as a whole. It is not possible to reference
12110 a header name only or a value only. This is important because of the way
12111 headers are written (notably the number of spaces after the colon).
12112
12113 - the first line is always considered as a header, which makes it possible to
12114 rewrite or filter HTTP requests URIs or response codes, but in turn makes
12115 it harder to distinguish between headers and request line. The regex prefix
12116 ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix
12117 ^[^ \t:]*: matches any header name followed by a colon.
12118
12119 - for performances reasons, the number of characters added to a request or to
12120 a response is limited at build time to values between 1 and 4 kB. This
12121 should normally be far more than enough for most usages. If it is too short
12122 on occasional usages, it is possible to gain some space by removing some
12123 useless headers before adding new ones.
12124
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012125 - keywords beginning with "reqi" and "rspi" are the same as their counterpart
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012126 without the 'i' letter except that they ignore case when matching patterns.
12127
12128 - when a request passes through a frontend then a backend, all req* rules
12129 from the frontend will be evaluated, then all req* rules from the backend
12130 will be evaluated. The reverse path is applied to responses.
12131
12132 - req* statements are applied after "block" statements, so that "block" is
12133 always the first one, but before "use_backend" in order to permit rewriting
Willy Tarreaud72758d2010-01-12 10:42:19 +010012134 before switching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012135
12136
Willy Tarreau74ca5042013-06-11 23:12:07 +0200121377. Using ACLs and fetching samples
12138----------------------------------
12139
12140Haproxy is capable of extracting data from request or response streams, from
12141client or server information, from tables, environmental information etc...
12142The action of extracting such data is called fetching a sample. Once retrieved,
12143these samples may be used for various purposes such as a key to a stick-table,
12144but most common usages consist in matching them against predefined constant
12145data called patterns.
12146
12147
121487.1. ACL basics
12149---------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012150
12151The use of Access Control Lists (ACL) provides a flexible solution to perform
12152content switching and generally to take decisions based on content extracted
12153from the request, the response or any environmental status. The principle is
12154simple :
12155
Willy Tarreau74ca5042013-06-11 23:12:07 +020012156 - extract a data sample from a stream, table or the environment
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012157 - optionally apply some format conversion to the extracted sample
Willy Tarreau74ca5042013-06-11 23:12:07 +020012158 - apply one or multiple pattern matching methods on this sample
12159 - perform actions only when a pattern matches the sample
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012160
Willy Tarreau74ca5042013-06-11 23:12:07 +020012161The actions generally consist in blocking a request, selecting a backend, or
12162adding a header.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012163
12164In order to define a test, the "acl" keyword is used. The syntax is :
12165
Willy Tarreau74ca5042013-06-11 23:12:07 +020012166 acl <aclname> <criterion> [flags] [operator] [<value>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012167
12168This creates a new ACL <aclname> or completes an existing one with new tests.
12169Those tests apply to the portion of request/response specified in <criterion>
12170and may be adjusted with optional flags [flags]. Some criteria also support
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012171an operator which may be specified before the set of values. Optionally some
12172conversion operators may be applied to the sample, and they will be specified
12173as a comma-delimited list of keywords just after the first keyword. The values
12174are of the type supported by the criterion, and are separated by spaces.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012175
12176ACL names must be formed from upper and lower case letters, digits, '-' (dash),
12177'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
12178which means that "my_acl" and "My_Acl" are two different ACLs.
12179
12180There is no enforced limit to the number of ACLs. The unused ones do not affect
12181performance, they just consume a small amount of memory.
12182
Willy Tarreau74ca5042013-06-11 23:12:07 +020012183The criterion generally is the name of a sample fetch method, or one of its ACL
12184specific declinations. The default test method is implied by the output type of
12185this sample fetch method. The ACL declinations can describe alternate matching
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012186methods of a same sample fetch method. The sample fetch methods are the only
12187ones supporting a conversion.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012188
12189Sample fetch methods return data which can be of the following types :
12190 - boolean
12191 - integer (signed or unsigned)
12192 - IPv4 or IPv6 address
12193 - string
12194 - data block
12195
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012196Converters transform any of these data into any of these. For example, some
12197converters might convert a string to a lower-case string while other ones
12198would turn a string to an IPv4 address, or apply a netmask to an IP address.
12199The resulting sample is of the type of the last converter applied to the list,
12200which defaults to the type of the sample fetch method.
12201
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012202Each sample or converter returns data of a specific type, specified with its
12203keyword in this documentation. When an ACL is declared using a standard sample
12204fetch method, certain types automatically involved a default matching method
12205which are summarized in the table below :
12206
12207 +---------------------+-----------------+
12208 | Sample or converter | Default |
12209 | output type | matching method |
12210 +---------------------+-----------------+
12211 | boolean | bool |
12212 +---------------------+-----------------+
12213 | integer | int |
12214 +---------------------+-----------------+
12215 | ip | ip |
12216 +---------------------+-----------------+
12217 | string | str |
12218 +---------------------+-----------------+
12219 | binary | none, use "-m" |
12220 +---------------------+-----------------+
12221
12222Note that in order to match a binary samples, it is mandatory to specify a
12223matching method, see below.
12224
Willy Tarreau74ca5042013-06-11 23:12:07 +020012225The ACL engine can match these types against patterns of the following types :
12226 - boolean
12227 - integer or integer range
12228 - IP address / network
12229 - string (exact, substring, suffix, prefix, subdir, domain)
12230 - regular expression
12231 - hex block
12232
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012233The following ACL flags are currently supported :
12234
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012235 -i : ignore case during matching of all subsequent patterns.
12236 -f : load patterns from a file.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012237 -m : use a specific pattern matching method
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010012238 -n : forbid the DNS resolutions
Thierry FOURNIER9860c412014-01-29 14:23:29 +010012239 -M : load the file pointed by -f like a map file.
Thierry FOURNIER3534d882014-01-20 17:01:44 +010012240 -u : force the unique id of the ACL
Willy Tarreau6a06a402007-07-15 20:15:28 +020012241 -- : force end of flags. Useful when a string looks like one of the flags.
12242
Willy Tarreau74ca5042013-06-11 23:12:07 +020012243The "-f" flag is followed by the name of a file from which all lines will be
12244read as individual values. It is even possible to pass multiple "-f" arguments
12245if the patterns are to be loaded from multiple files. Empty lines as well as
12246lines beginning with a sharp ('#') will be ignored. All leading spaces and tabs
12247will be stripped. If it is absolutely necessary to insert a valid pattern
12248beginning with a sharp, just prefix it with a space so that it is not taken for
12249a comment. Depending on the data type and match method, haproxy may load the
12250lines into a binary tree, allowing very fast lookups. This is true for IPv4 and
12251exact string matching. In this case, duplicates will automatically be removed.
12252
Thierry FOURNIER9860c412014-01-29 14:23:29 +010012253The "-M" flag allows an ACL to use a map file. If this flag is set, the file is
12254parsed as two column file. The first column contains the patterns used by the
12255ACL, and the second column contain the samples. The sample can be used later by
12256a map. This can be useful in some rare cases where an ACL would just be used to
12257check for the existence of a pattern in a map before a mapping is applied.
12258
Thierry FOURNIER3534d882014-01-20 17:01:44 +010012259The "-u" flag forces the unique id of the ACL. This unique id is used with the
12260socket interface to identify ACL and dynamically change its values. Note that a
12261file is always identified by its name even if an id is set.
12262
Willy Tarreau74ca5042013-06-11 23:12:07 +020012263Also, note that the "-i" flag applies to subsequent entries and not to entries
12264loaded from files preceding it. For instance :
12265
12266 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
12267
12268In this example, each line of "exact-ua.lst" will be exactly matched against
12269the "user-agent" header of the request. Then each line of "generic-ua" will be
12270case-insensitively matched. Then the word "test" will be insensitively matched
12271as well.
12272
12273The "-m" flag is used to select a specific pattern matching method on the input
12274sample. All ACL-specific criteria imply a pattern matching method and generally
12275do not need this flag. However, this flag is useful with generic sample fetch
12276methods to describe how they're going to be matched against the patterns. This
12277is required for sample fetches which return data type for which there is no
12278obvious matching method (eg: string or binary). When "-m" is specified and
12279followed by a pattern matching method name, this method is used instead of the
12280default one for the criterion. This makes it possible to match contents in ways
12281that were not initially planned, or with sample fetch methods which return a
12282string. The matching method also affects the way the patterns are parsed.
12283
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010012284The "-n" flag forbids the dns resolutions. It is used with the load of ip files.
12285By default, if the parser cannot parse ip address it considers that the parsed
12286string is maybe a domain name and try dns resolution. The flag "-n" disable this
12287resolution. It is useful for detecting malformed ip lists. Note that if the DNS
12288server is not reachable, the haproxy configuration parsing may last many minutes
12289waiting fir the timeout. During this time no error messages are displayed. The
12290flag "-n" disable this behavior. Note also that during the runtime, this
12291function is disabled for the dynamic acl modifications.
12292
Willy Tarreau74ca5042013-06-11 23:12:07 +020012293There are some restrictions however. Not all methods can be used with all
12294sample fetch methods. Also, if "-m" is used in conjunction with "-f", it must
12295be placed first. The pattern matching method must be one of the following :
Willy Tarreau5adeda12013-03-31 22:13:34 +020012296
12297 - "found" : only check if the requested sample could be found in the stream,
12298 but do not compare it against any pattern. It is recommended not
Willy Tarreau74ca5042013-06-11 23:12:07 +020012299 to pass any pattern to avoid confusion. This matching method is
12300 particularly useful to detect presence of certain contents such
12301 as headers, cookies, etc... even if they are empty and without
12302 comparing them to anything nor counting them.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012303
12304 - "bool" : check the value as a boolean. It can only be applied to fetches
12305 which return a boolean or integer value, and takes no pattern.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012306 Value zero or false does not match, all other values do match.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012307
12308 - "int" : match the value as an integer. It can be used with integer and
Willy Tarreau74ca5042013-06-11 23:12:07 +020012309 boolean samples. Boolean false is integer 0, true is integer 1.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012310
12311 - "ip" : match the value as an IPv4 or IPv6 address. It is compatible
Willy Tarreau74ca5042013-06-11 23:12:07 +020012312 with IP address samples only, so it is implied and never needed.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012313
12314 - "bin" : match the contents against an hexadecimal string representing a
12315 binary sequence. This may be used with binary or string samples.
12316
12317 - "len" : match the sample's length as an integer. This may be used with
12318 binary or string samples.
12319
Willy Tarreau74ca5042013-06-11 23:12:07 +020012320 - "str" : exact match : match the contents against a string. This may be
12321 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012322
Willy Tarreau74ca5042013-06-11 23:12:07 +020012323 - "sub" : substring match : check that the contents contain at least one of
12324 the provided string patterns. This may be used with binary or
12325 string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012326
Willy Tarreau74ca5042013-06-11 23:12:07 +020012327 - "reg" : regex match : match the contents against a list of regular
12328 expressions. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012329
Willy Tarreau74ca5042013-06-11 23:12:07 +020012330 - "beg" : prefix match : check that the contents begin like the provided
12331 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012332
Willy Tarreau74ca5042013-06-11 23:12:07 +020012333 - "end" : suffix match : check that the contents end like the provided
12334 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012335
Willy Tarreau74ca5042013-06-11 23:12:07 +020012336 - "dir" : subdir match : check that a slash-delimited portion of the
12337 contents exactly matches one of the provided string patterns.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012338 This may be used with binary or string samples.
12339
Willy Tarreau74ca5042013-06-11 23:12:07 +020012340 - "dom" : domain match : check that a dot-delimited portion of the contents
12341 exactly match one of the provided string patterns. This may be
12342 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020012343
12344For example, to quickly detect the presence of cookie "JSESSIONID" in an HTTP
12345request, it is possible to do :
12346
12347 acl jsess_present cook(JSESSIONID) -m found
12348
12349In order to apply a regular expression on the 500 first bytes of data in the
12350buffer, one would use the following acl :
12351
12352 acl script_tag payload(0,500) -m reg -i <script>
12353
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012354On systems where the regex library is much slower when using "-i", it is
12355possible to convert the sample to lowercase before matching, like this :
12356
12357 acl script_tag payload(0,500),lower -m reg <script>
12358
Willy Tarreau74ca5042013-06-11 23:12:07 +020012359All ACL-specific criteria imply a default matching method. Most often, these
12360criteria are composed by concatenating the name of the original sample fetch
12361method and the matching method. For example, "hdr_beg" applies the "beg" match
12362to samples retrieved using the "hdr" fetch method. Since all ACL-specific
12363criteria rely on a sample fetch method, it is always possible instead to use
12364the original sample fetch method and the explicit matching method using "-m".
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012365
Willy Tarreau74ca5042013-06-11 23:12:07 +020012366If an alternate match is specified using "-m" on an ACL-specific criterion,
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012367the matching method is simply applied to the underlying sample fetch method.
12368For example, all ACLs below are exact equivalent :
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012369
Willy Tarreau74ca5042013-06-11 23:12:07 +020012370 acl short_form hdr_beg(host) www.
12371 acl alternate1 hdr_beg(host) -m beg www.
12372 acl alternate2 hdr_dom(host) -m beg www.
12373 acl alternate3 hdr(host) -m beg www.
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012374
Willy Tarreau2b5285d2010-05-09 23:45:24 +020012375
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012376The table below summarizes the compatibility matrix between sample or converter
12377types and the pattern types to fetch against. It indicates for each compatible
12378combination the name of the matching method to be used, surrounded with angle
12379brackets ">" and "<" when the method is the default one and will work by
12380default without "-m".
Willy Tarreau0ba27502007-12-24 16:55:16 +010012381
Willy Tarreau74ca5042013-06-11 23:12:07 +020012382 +-------------------------------------------------+
12383 | Input sample type |
12384 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012385 | pattern type | boolean | integer | ip | string | binary |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012386 +----------------------+---------+---------+---------+---------+---------+
12387 | none (presence only) | found | found | found | found | found |
12388 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012389 | none (boolean value) |> bool <| bool | | bool | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012390 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012391 | integer (value) | int |> int <| int | int | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012392 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012393 | integer (length) | len | len | len | len | len |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012394 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012395 | IP address | | |> ip <| ip | ip |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012396 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020012397 | exact string | str | str | str |> str <| str |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012398 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012399 | prefix | beg | beg | beg | beg | beg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012400 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012401 | suffix | end | end | end | end | end |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012402 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012403 | substring | sub | sub | sub | sub | sub |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012404 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012405 | subdir | dir | dir | dir | dir | dir |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012406 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012407 | domain | dom | dom | dom | dom | dom |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012408 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010012409 | regex | reg | reg | reg | reg | reg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020012410 +----------------------+---------+---------+---------+---------+---------+
12411 | hex block | | | | bin | bin |
12412 +----------------------+---------+---------+---------+---------+---------+
Willy Tarreau6a06a402007-07-15 20:15:28 +020012413
12414
Willy Tarreau74ca5042013-06-11 23:12:07 +0200124157.1.1. Matching booleans
12416------------------------
12417
12418In order to match a boolean, no value is needed and all values are ignored.
12419Boolean matching is used by default for all fetch methods of type "boolean".
12420When boolean matching is used, the fetched value is returned as-is, which means
12421that a boolean "true" will always match and a boolean "false" will never match.
12422
12423Boolean matching may also be enforced using "-m bool" on fetch methods which
12424return an integer value. Then, integer value 0 is converted to the boolean
12425"false" and all other values are converted to "true".
12426
Willy Tarreau6a06a402007-07-15 20:15:28 +020012427
Willy Tarreau74ca5042013-06-11 23:12:07 +0200124287.1.2. Matching integers
12429------------------------
12430
12431Integer matching applies by default to integer fetch methods. It can also be
12432enforced on boolean fetches using "-m int". In this case, "false" is converted
12433to the integer 0, and "true" is converted to the integer 1.
12434
12435Integer matching also supports integer ranges and operators. Note that integer
12436matching only applies to positive values. A range is a value expressed with a
12437lower and an upper bound separated with a colon, both of which may be omitted.
Willy Tarreau6a06a402007-07-15 20:15:28 +020012438
12439For instance, "1024:65535" is a valid range to represent a range of
12440unprivileged ports, and "1024:" would also work. "0:1023" is a valid
12441representation of privileged ports, and ":1023" would also work.
12442
Willy Tarreau62644772008-07-16 18:36:06 +020012443As a special case, some ACL functions support decimal numbers which are in fact
12444two integers separated by a dot. This is used with some version checks for
12445instance. All integer properties apply to those decimal numbers, including
12446ranges and operators.
12447
Willy Tarreau6a06a402007-07-15 20:15:28 +020012448For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +010012449operators with ranges does not make much sense and is strongly discouraged.
12450Similarly, it does not make much sense to perform order comparisons with a set
12451of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +020012452
Willy Tarreau0ba27502007-12-24 16:55:16 +010012453Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +020012454
12455 eq : true if the tested value equals at least one value
12456 ge : true if the tested value is greater than or equal to at least one value
12457 gt : true if the tested value is greater than at least one value
12458 le : true if the tested value is less than or equal to at least one value
12459 lt : true if the tested value is less than at least one value
12460
Willy Tarreau0ba27502007-12-24 16:55:16 +010012461For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +020012462
12463 acl negative-length hdr_val(content-length) lt 0
12464
Willy Tarreau62644772008-07-16 18:36:06 +020012465This one matches SSL versions between 3.0 and 3.1 (inclusive) :
12466
12467 acl sslv3 req_ssl_ver 3:3.1
12468
Willy Tarreau6a06a402007-07-15 20:15:28 +020012469
Willy Tarreau74ca5042013-06-11 23:12:07 +0200124707.1.3. Matching strings
12471-----------------------
12472
12473String matching applies to string or binary fetch methods, and exists in 6
12474different forms :
12475
12476 - exact match (-m str) : the extracted string must exactly match the
12477 patterns ;
12478
12479 - substring match (-m sub) : the patterns are looked up inside the
12480 extracted string, and the ACL matches if any of them is found inside ;
12481
12482 - prefix match (-m beg) : the patterns are compared with the beginning of
12483 the extracted string, and the ACL matches if any of them matches.
12484
12485 - suffix match (-m end) : the patterns are compared with the end of the
12486 extracted string, and the ACL matches if any of them matches.
12487
Baptiste Assmann33db6002016-03-06 23:32:10 +010012488 - subdir match (-m dir) : the patterns are looked up inside the extracted
Willy Tarreau74ca5042013-06-11 23:12:07 +020012489 string, delimited with slashes ("/"), and the ACL matches if any of them
12490 matches.
12491
12492 - domain match (-m dom) : the patterns are looked up inside the extracted
12493 string, delimited with dots ("."), and the ACL matches if any of them
12494 matches.
Willy Tarreau6a06a402007-07-15 20:15:28 +020012495
12496String matching applies to verbatim strings as they are passed, with the
12497exception of the backslash ("\") which makes it possible to escape some
12498characters such as the space. If the "-i" flag is passed before the first
12499string, then the matching will be performed ignoring the case. In order
12500to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +010012501before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020012502
12503
Willy Tarreau74ca5042013-06-11 23:12:07 +0200125047.1.4. Matching regular expressions (regexes)
12505---------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020012506
12507Just like with string matching, regex matching applies to verbatim strings as
12508they are passed, with the exception of the backslash ("\") which makes it
12509possible to escape some characters such as the space. If the "-i" flag is
12510passed before the first regex, then the matching will be performed ignoring
12511the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +010012512the "--" flag before the first string. Same principle applies of course to
12513match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020012514
12515
Willy Tarreau74ca5042013-06-11 23:12:07 +0200125167.1.5. Matching arbitrary data blocks
12517-------------------------------------
12518
12519It is possible to match some extracted samples against a binary block which may
12520not safely be represented as a string. For this, the patterns must be passed as
12521a series of hexadecimal digits in an even number, when the match method is set
12522to binary. Each sequence of two digits will represent a byte. The hexadecimal
12523digits may be used upper or lower case.
12524
12525Example :
12526 # match "Hello\n" in the input stream (\x48 \x65 \x6c \x6c \x6f \x0a)
12527 acl hello payload(0,6) -m bin 48656c6c6f0a
12528
12529
125307.1.6. Matching IPv4 and IPv6 addresses
12531---------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020012532
12533IPv4 addresses values can be specified either as plain addresses or with a
12534netmask appended, in which case the IPv4 address matches whenever it is
12535within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010012536host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +010012537difficult to read and debug configurations. If hostnames are used, you should
12538at least ensure that they are present in /etc/hosts so that the configuration
12539does not depend on any random DNS match at the moment the configuration is
12540parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +020012541
Daniel Schnellereba56342016-04-13 00:26:52 +020012542The dotted IPv4 address notation is supported in both regular as well as the
12543abbreviated form with all-0-octets omitted:
12544
12545 +------------------+------------------+------------------+
12546 | Example 1 | Example 2 | Example 3 |
12547 +------------------+------------------+------------------+
12548 | 192.168.0.1 | 10.0.0.12 | 127.0.0.1 |
12549 | 192.168.1 | 10.12 | 127.1 |
12550 | 192.168.0.1/22 | 10.0.0.12/8 | 127.0.0.1/8 |
12551 | 192.168.1/22 | 10.12/8 | 127.1/8 |
12552 +------------------+------------------+------------------+
12553
12554Notice that this is different from RFC 4632 CIDR address notation in which
12555192.168.42/24 would be equivalent to 192.168.42.0/24.
12556
Willy Tarreauceb4ac92012-04-28 00:41:46 +020012557IPv6 may be entered in their usual form, with or without a netmask appended.
12558Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of
12559trouble with randomly resolved IP addresses, host names are never allowed in
12560IPv6 patterns.
12561
12562HAProxy is also able to match IPv4 addresses with IPv6 addresses in the
12563following situations :
12564 - tested address is IPv4, pattern address is IPv4, the match applies
12565 in IPv4 using the supplied mask if any.
12566 - tested address is IPv6, pattern address is IPv6, the match applies
12567 in IPv6 using the supplied mask if any.
12568 - tested address is IPv6, pattern address is IPv4, the match applies in IPv4
12569 using the pattern's mask if the IPv6 address matches with 2002:IPV4::,
12570 ::IPV4 or ::ffff:IPV4, otherwise it fails.
12571 - tested address is IPv4, pattern address is IPv6, the IPv4 address is first
12572 converted to IPv6 by prefixing ::ffff: in front of it, then the match is
12573 applied in IPv6 using the supplied IPv6 mask.
12574
Willy Tarreau74ca5042013-06-11 23:12:07 +020012575
125767.2. Using ACLs to form conditions
12577----------------------------------
12578
12579Some actions are only performed upon a valid condition. A condition is a
12580combination of ACLs with operators. 3 operators are supported :
12581
12582 - AND (implicit)
12583 - OR (explicit with the "or" keyword or the "||" operator)
12584 - Negation with the exclamation mark ("!")
Willy Tarreau6a06a402007-07-15 20:15:28 +020012585
Willy Tarreau74ca5042013-06-11 23:12:07 +020012586A condition is formed as a disjunctive form:
Willy Tarreau6a06a402007-07-15 20:15:28 +020012587
Willy Tarreau74ca5042013-06-11 23:12:07 +020012588 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreaubef91e72013-03-31 23:14:46 +020012589
Willy Tarreau74ca5042013-06-11 23:12:07 +020012590Such conditions are generally used after an "if" or "unless" statement,
12591indicating when the condition will trigger the action.
Willy Tarreaubef91e72013-03-31 23:14:46 +020012592
Willy Tarreau74ca5042013-06-11 23:12:07 +020012593For instance, to block HTTP requests to the "*" URL with methods other than
12594"OPTIONS", as well as POST requests without content-length, and GET or HEAD
12595requests with a content-length greater than 0, and finally every request which
12596is not either GET/HEAD/POST/OPTIONS !
12597
12598 acl missing_cl hdr_cnt(Content-length) eq 0
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030012599 http-request deny if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
12600 http-request deny if METH_GET HTTP_CONTENT
12601 http-request deny unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreau74ca5042013-06-11 23:12:07 +020012602
12603To select a different backend for requests to static contents on the "www" site
12604and to every request on the "img", "video", "download" and "ftp" hosts :
12605
12606 acl url_static path_beg /static /images /img /css
12607 acl url_static path_end .gif .png .jpg .css .js
12608 acl host_www hdr_beg(host) -i www
12609 acl host_static hdr_beg(host) -i img. video. download. ftp.
12610
12611 # now use backend "static" for all static-only hosts, and for static urls
12612 # of host "www". Use backend "www" for the rest.
12613 use_backend static if host_static or host_www url_static
12614 use_backend www if host_www
12615
12616It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
12617expressions that are built on the fly without needing to be declared. They must
12618be enclosed between braces, with a space before and after each brace (because
12619the braces must be seen as independent words). Example :
12620
12621 The following rule :
12622
12623 acl missing_cl hdr_cnt(Content-length) eq 0
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030012624 http-request deny if METH_POST missing_cl
Willy Tarreau74ca5042013-06-11 23:12:07 +020012625
12626 Can also be written that way :
12627
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030012628 http-request deny if METH_POST { hdr_cnt(Content-length) eq 0 }
Willy Tarreau74ca5042013-06-11 23:12:07 +020012629
12630It is generally not recommended to use this construct because it's a lot easier
12631to leave errors in the configuration when written that way. However, for very
12632simple rules matching only one source IP address for instance, it can make more
12633sense to use them than to declare ACLs with random names. Another example of
12634good use is the following :
12635
12636 With named ACLs :
12637
12638 acl site_dead nbsrv(dynamic) lt 2
12639 acl site_dead nbsrv(static) lt 2
12640 monitor fail if site_dead
12641
12642 With anonymous ACLs :
12643
12644 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
12645
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030012646See section 4.2 for detailed help on the "http-request deny" and "use_backend"
12647keywords.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012648
12649
126507.3. Fetching samples
12651---------------------
12652
12653Historically, sample fetch methods were only used to retrieve data to match
12654against patterns using ACLs. With the arrival of stick-tables, a new class of
12655sample fetch methods was created, most often sharing the same syntax as their
12656ACL counterpart. These sample fetch methods are also known as "fetches". As
12657of now, ACLs and fetches have converged. All ACL fetch methods have been made
12658available as fetch methods, and ACLs may use any sample fetch method as well.
12659
12660This section details all available sample fetch methods and their output type.
12661Some sample fetch methods have deprecated aliases that are used to maintain
12662compatibility with existing configurations. They are then explicitly marked as
12663deprecated and should not be used in new setups.
12664
12665The ACL derivatives are also indicated when available, with their respective
12666matching methods. These ones all have a well defined default pattern matching
12667method, so it is never necessary (though allowed) to pass the "-m" option to
12668indicate how the sample will be matched using ACLs.
12669
12670As indicated in the sample type versus matching compatibility matrix above,
12671when using a generic sample fetch method in an ACL, the "-m" option is
12672mandatory unless the sample type is one of boolean, integer, IPv4 or IPv6. When
12673the same keyword exists as an ACL keyword and as a standard fetch method, the
12674ACL engine will automatically pick the ACL-only one by default.
12675
12676Some of these keywords support one or multiple mandatory arguments, and one or
12677multiple optional arguments. These arguments are strongly typed and are checked
12678when the configuration is parsed so that there is no risk of running with an
12679incorrect argument (eg: an unresolved backend name). Fetch function arguments
12680are passed between parenthesis and are delimited by commas. When an argument
12681is optional, it will be indicated below between square brackets ('[ ]'). When
12682all arguments are optional, the parenthesis may be omitted.
12683
12684Thus, the syntax of a standard sample fetch method is one of the following :
12685 - name
12686 - name(arg1)
12687 - name(arg1,arg2)
12688
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012689
126907.3.1. Converters
12691-----------------
12692
Willy Tarreaue6b11e42013-11-26 19:02:32 +010012693Sample fetch methods may be combined with transformations to be applied on top
12694of the fetched sample (also called "converters"). These combinations form what
12695is called "sample expressions" and the result is a "sample". Initially this
12696was only supported by "stick on" and "stick store-request" directives but this
12697has now be extended to all places where samples may be used (acls, log-format,
12698unique-id-format, add-header, ...).
12699
12700These transformations are enumerated as a series of specific keywords after the
12701sample fetch method. These keywords may equally be appended immediately after
12702the fetch keyword's argument, delimited by a comma. These keywords can also
12703support some arguments (eg: a netmask) which must be passed in parenthesis.
Willy Tarreau0ba27502007-12-24 16:55:16 +010012704
Willy Tarreau97707872015-01-27 15:12:13 +010012705A certain category of converters are bitwise and arithmetic operators which
12706support performing basic operations on integers. Some bitwise operations are
12707supported (and, or, xor, cpl) and some arithmetic operations are supported
12708(add, sub, mul, div, mod, neg). Some comparators are provided (odd, even, not,
12709bool) which make it possible to report a match without having to write an ACL.
12710
Willy Tarreau74ca5042013-06-11 23:12:07 +020012711The currently available list of transformation keywords include :
Willy Tarreau0ba27502007-12-24 16:55:16 +010012712
Ben Shillitof25e8e52016-12-02 14:25:37 +00001271351d.single(<prop>[,<prop>*])
12714 Returns values for the properties requested as a string, where values are
12715 separated by the delimiter specified with "51degrees-property-separator".
12716 The device is identified using the User-Agent header passed to the
12717 converter. The function can be passed up to five property names, and if a
12718 property name can't be found, the value "NoData" is returned.
12719
12720 Example :
12721 # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request
12722 # containg values for the three properties requested by using the
12723 # User-Agent passed to the converter.
12724 frontend http-in
12725 bind *:8081
12726 default_backend servers
12727 http-request set-header X-51D-DeviceTypeMobileTablet \
12728 %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)]
12729
Willy Tarreau97707872015-01-27 15:12:13 +010012730add(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020012731 Adds <value> to the input value of type signed integer, and returns the
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020012732 result as a signed integer. <value> can be a numeric value or a variable
Daniel Schneller0b547052016-03-21 20:46:57 +010012733 name. The name of the variable starts with an indication about its scope. The
12734 scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010012735 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010012736 "sess" : the variable is shared with the whole session
12737 "txn" : the variable is shared with the transaction (request and response)
12738 "req" : the variable is shared only during request processing
12739 "res" : the variable is shared only during response processing
12740 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010012741 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010012742
12743and(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020012744 Performs a bitwise "AND" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020012745 integer, and returns the result as an signed integer. <value> can be a
Daniel Schneller0b547052016-03-21 20:46:57 +010012746 numeric value or a variable name. The name of the variable starts with an
12747 indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010012748 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010012749 "sess" : the variable is shared with the whole session
12750 "txn" : the variable is shared with the transaction (request and response)
12751 "req" : the variable is shared only during request processing
12752 "res" : the variable is shared only during response processing
12753 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010012754 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010012755
Holger Just1bfc24b2017-05-06 00:56:53 +020012756b64dec
12757 Converts (decodes) a base64 encoded input string to its binary
12758 representation. It performs the inverse operation of base64().
12759
Emeric Brun53d1a982014-04-30 18:21:37 +020012760base64
12761 Converts a binary input sample to a base64 string. It is used to log or
12762 transfer binary content in a way that can be reliably transferred (eg:
12763 an SSL ID can be copied in a header).
12764
Willy Tarreau97707872015-01-27 15:12:13 +010012765bool
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020012766 Returns a boolean TRUE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010012767 non-null, otherwise returns FALSE. Used in conjunction with and(), it can be
12768 used to report true/false for bit testing on input values (eg: verify the
12769 presence of a flag).
12770
Emeric Brun54c4ac82014-11-03 15:32:43 +010012771bytes(<offset>[,<length>])
12772 Extracts some bytes from an input binary sample. The result is a binary
12773 sample starting at an offset (in bytes) of the original sample and
Tim Düsterhus4896c442016-11-29 02:15:19 +010012774 optionally truncated at the given length.
Emeric Brun54c4ac82014-11-03 15:32:43 +010012775
Willy Tarreau97707872015-01-27 15:12:13 +010012776cpl
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020012777 Takes the input value of type signed integer, applies a ones-complement
12778 (flips all bits) and returns the result as an signed integer.
Willy Tarreau97707872015-01-27 15:12:13 +010012779
Willy Tarreau80599772015-01-20 19:35:24 +010012780crc32([<avalanche>])
12781 Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32
12782 hash function. Optionally, it is possible to apply a full avalanche hash
12783 function to the output if the optional <avalanche> argument equals 1. This
12784 converter uses the same functions as used by the various hash-based load
12785 balancing algorithms, so it will provide exactly the same results. It is
12786 provided for compatibility with other software which want a CRC32 to be
12787 computed on some input keys, so it follows the most common implementation as
12788 found in Ethernet, Gzip, PNG, etc... It is slower than the other algorithms
12789 but may provide a better or at least less predictable distribution. It must
12790 not be used for security purposes as a 32-bit hash is trivial to break. See
12791 also "djb2", "sdbm", "wt6" and the "hash-type" directive.
12792
David Carlier29b3ca32015-09-25 14:09:21 +010012793da-csv-conv(<prop>[,<prop>*])
David Carlier4542b102015-06-01 13:54:29 +020012794 Asks the DeviceAtlas converter to identify the User Agent string passed on
12795 input, and to emit a string made of the concatenation of the properties
12796 enumerated in argument, delimited by the separator defined by the global
12797 keyword "deviceatlas-property-separator", or by default the pipe character
David Carlier840b0242016-03-16 10:09:55 +000012798 ('|'). There's a limit of 12 different properties imposed by the haproxy
David Carlier4542b102015-06-01 13:54:29 +020012799 configuration language.
12800
12801 Example:
12802 frontend www
Cyril Bonté307ee1e2015-09-28 23:16:06 +020012803 bind *:8881
12804 default_backend servers
David Carlier840b0242016-03-16 10:09:55 +000012805 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 +020012806
Thierry FOURNIER9687c772015-05-07 15:46:29 +020012807debug
12808 This converter is used as debug tool. It dumps on screen the content and the
12809 type of the input sample. The sample is returned as is on its output. This
12810 converter only exists when haproxy was built with debugging enabled.
12811
Willy Tarreau97707872015-01-27 15:12:13 +010012812div(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020012813 Divides the input value of type signed integer by <value>, and returns the
12814 result as an signed integer. If <value> is null, the largest unsigned
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020012815 integer is returned (typically 2^63-1). <value> can be a numeric value or a
Daniel Schneller0b547052016-03-21 20:46:57 +010012816 variable name. The name of the variable starts with an indication about its
12817 scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010012818 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010012819 "sess" : the variable is shared with the whole session
12820 "txn" : the variable is shared with the transaction (request and response)
12821 "req" : the variable is shared only during request processing
12822 "res" : the variable is shared only during response processing
12823 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010012824 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010012825
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020012826djb2([<avalanche>])
12827 Hashes a binary input sample into an unsigned 32-bit quantity using the DJB2
12828 hash function. Optionally, it is possible to apply a full avalanche hash
12829 function to the output if the optional <avalanche> argument equals 1. This
12830 converter uses the same functions as used by the various hash-based load
12831 balancing algorithms, so it will provide exactly the same results. It is
12832 mostly intended for debugging, but can be used as a stick-table entry to
12833 collect rough statistics. It must not be used for security purposes as a
Willy Tarreau80599772015-01-20 19:35:24 +010012834 32-bit hash is trivial to break. See also "crc32", "sdbm", "wt6" and the
12835 "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020012836
Willy Tarreau97707872015-01-27 15:12:13 +010012837even
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020012838 Returns a boolean TRUE if the input value of type signed integer is even
Willy Tarreau97707872015-01-27 15:12:13 +010012839 otherwise returns FALSE. It is functionally equivalent to "not,and(1),bool".
12840
Emeric Brunf399b0d2014-11-03 17:07:03 +010012841field(<index>,<delimiters>)
12842 Extracts the substring at the given index considering given delimiters from
12843 an input string. Indexes start at 1 and delimiters are a string formatted
12844 list of chars.
12845
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012846hex
12847 Converts a binary input sample to an hex string containing two hex digits per
12848 input byte. It is used to log or transfer hex dumps of some binary input data
12849 in a way that can be reliably transferred (eg: an SSL ID can be copied in a
12850 header).
Thierry FOURNIER2f49d6d2014-03-12 15:01:52 +010012851
Dragan Dosen3f957b22017-10-24 09:27:34 +020012852hex2i
12853 Converts a hex string containing two hex digits per input byte to an
12854 integer. If the input value can not be converted, then zero is returned.
12855
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012856http_date([<offset>])
12857 Converts an integer supposed to contain a date since epoch to a string
12858 representing this date in a format suitable for use in HTTP header fields. If
12859 an offset value is specified, then it is a number of seconds that is added to
12860 the date before the conversion is operated. This is particularly useful to
12861 emit Date header fields, Expires values in responses when combined with a
12862 positive offset, or Last-Modified values when the offset is negative.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012863
Willy Tarreaud9f316a2014-07-10 14:03:38 +020012864in_table(<table>)
12865 Uses the string representation of the input sample to perform a look up in
12866 the specified table. If the key is not found in the table, a boolean false
12867 is returned. Otherwise a boolean true is returned. This can be used to verify
12868 the presence of a certain key in a table tracking some elements (eg: whether
12869 or not a source IP address or an Authorization header was already seen).
12870
Willy Tarreauffcb2e42014-07-10 16:29:08 +020012871ipmask(<mask>)
12872 Apply a mask to an IPv4 address, and use the result for lookups and storage.
12873 This can be used to make all hosts within a certain mask to share the same
12874 table entries and as such use the same server. The mask can be passed in
12875 dotted form (eg: 255.255.255.0) or in CIDR form (eg: 24).
12876
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020012877json([<input-code>])
12878 Escapes the input string and produces an ASCII ouput string ready to use as a
12879 JSON string. The converter tries to decode the input string according to the
Herve COMMOWICK8dfe8632016-08-05 12:01:20 +020012880 <input-code> parameter. It can be "ascii", "utf8", "utf8s", "utf8p" or
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020012881 "utf8ps". The "ascii" decoder never fails. The "utf8" decoder detects 3 types
12882 of errors:
12883 - bad UTF-8 sequence (lone continuation byte, bad number of continuation
12884 bytes, ...)
12885 - invalid range (the decoded value is within a UTF-8 prohibited range),
12886 - code overlong (the value is encoded with more bytes than necessary).
12887
12888 The UTF-8 JSON encoding can produce a "too long value" error when the UTF-8
12889 character is greater than 0xffff because the JSON string escape specification
12890 only authorizes 4 hex digits for the value encoding. The UTF-8 decoder exists
12891 in 4 variants designated by a combination of two suffix letters : "p" for
12892 "permissive" and "s" for "silently ignore". The behaviors of the decoders
12893 are :
12894 - "ascii" : never fails ;
12895 - "utf8" : fails on any detected errors ;
12896 - "utf8s" : never fails, but removes characters corresponding to errors ;
12897 - "utf8p" : accepts and fixes the overlong errors, but fails on any other
12898 error ;
12899 - "utf8ps" : never fails, accepts and fixes the overlong errors, but removes
12900 characters corresponding to the other errors.
12901
12902 This converter is particularly useful for building properly escaped JSON for
12903 logging to servers which consume JSON-formated traffic logs.
12904
12905 Example:
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020012906 capture request header Host len 15
Herve COMMOWICK8dfe8632016-08-05 12:01:20 +020012907 capture request header user-agent len 150
12908 log-format '{"ip":"%[src]","user-agent":"%[capture.req.hdr(1),json(utf8s)]"}'
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020012909
12910 Input request from client 127.0.0.1:
12911 GET / HTTP/1.0
12912 User-Agent: Very "Ugly" UA 1/2
12913
12914 Output log:
12915 {"ip":"127.0.0.1","user-agent":"Very \"Ugly\" UA 1\/2"}
12916
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012917language(<value>[,<default>])
12918 Returns the value with the highest q-factor from a list as extracted from the
12919 "accept-language" header using "req.fhdr". Values with no q-factor have a
12920 q-factor of 1. Values with a q-factor of 0 are dropped. Only values which
12921 belong to the list of semi-colon delimited <values> will be considered. The
12922 argument <value> syntax is "lang[;lang[;lang[;...]]]". If no value matches the
12923 given list and a default value is provided, it is returned. Note that language
12924 names may have a variant after a dash ('-'). If this variant is present in the
12925 list, it will be matched, but if it is not, only the base language is checked.
12926 The match is case-sensitive, and the output string is always one of those
12927 provided in arguments. The ordering of arguments is meaningless, only the
12928 ordering of the values in the request counts, as the first value among
12929 multiple sharing the same q-factor is used.
Thierry FOURNIERad903512014-04-11 17:51:01 +020012930
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012931 Example :
Thierry FOURNIERad903512014-04-11 17:51:01 +020012932
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012933 # this configuration switches to the backend matching a
12934 # given language based on the request :
Thierry FOURNIERad903512014-04-11 17:51:01 +020012935
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012936 acl es req.fhdr(accept-language),language(es;fr;en) -m str es
12937 acl fr req.fhdr(accept-language),language(es;fr;en) -m str fr
12938 acl en req.fhdr(accept-language),language(es;fr;en) -m str en
12939 use_backend spanish if es
12940 use_backend french if fr
12941 use_backend english if en
12942 default_backend choose_your_language
Thierry FOURNIERad903512014-04-11 17:51:01 +020012943
Willy Tarreauffcb2e42014-07-10 16:29:08 +020012944lower
12945 Convert a string sample to lower case. This can only be placed after a string
12946 sample fetch function or after a transformation keyword returning a string
12947 type. The result is of type string.
12948
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020012949ltime(<format>[,<offset>])
12950 Converts an integer supposed to contain a date since epoch to a string
12951 representing this date in local time using a format defined by the <format>
12952 string using strftime(3). The purpose is to allow any date format to be used
12953 in logs. An optional <offset> in seconds may be applied to the input date
12954 (positive or negative). See the strftime() man page for the format supported
12955 by your operating system. See also the utime converter.
12956
12957 Example :
12958
12959 # Emit two colons, one with the local time and another with ip:port
12960 # Eg: 20140710162350 127.0.0.1:57325
12961 log-format %[date,ltime(%Y%m%d%H%M%S)]\ %ci:%cp
12962
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012963map(<map_file>[,<default_value>])
12964map_<match_type>(<map_file>[,<default_value>])
12965map_<match_type>_<output_type>(<map_file>[,<default_value>])
12966 Search the input value from <map_file> using the <match_type> matching method,
12967 and return the associated value converted to the type <output_type>. If the
12968 input value cannot be found in the <map_file>, the converter returns the
12969 <default_value>. If the <default_value> is not set, the converter fails and
12970 acts as if no input value could be fetched. If the <match_type> is not set, it
12971 defaults to "str". Likewise, if the <output_type> is not set, it defaults to
12972 "str". For convenience, the "map" keyword is an alias for "map_str" and maps a
12973 string to another string.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010012974
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012975 It is important to avoid overlapping between the keys : IP addresses and
12976 strings are stored in trees, so the first of the finest match will be used.
12977 Other keys are stored in lists, so the first matching occurrence will be used.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010012978
Tim Düsterhus4896c442016-11-29 02:15:19 +010012979 The following array contains the list of all map functions available sorted by
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012980 input type, match type and output type.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010012981
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012982 input type | match method | output type str | output type int | output type ip
12983 -----------+--------------+-----------------+-----------------+---------------
12984 str | str | map_str | map_str_int | map_str_ip
12985 -----------+--------------+-----------------+-----------------+---------------
Willy Tarreau787a4c02014-05-10 07:55:30 +020012986 str | beg | map_beg | map_beg_int | map_end_ip
12987 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012988 str | sub | map_sub | map_sub_int | map_sub_ip
12989 -----------+--------------+-----------------+-----------------+---------------
12990 str | dir | map_dir | map_dir_int | map_dir_ip
12991 -----------+--------------+-----------------+-----------------+---------------
12992 str | dom | map_dom | map_dom_int | map_dom_ip
12993 -----------+--------------+-----------------+-----------------+---------------
12994 str | end | map_end | map_end_int | map_end_ip
12995 -----------+--------------+-----------------+-----------------+---------------
Ruoshan Huang3c5e3742016-12-02 16:25:31 +080012996 str | reg | map_reg | map_reg_int | map_reg_ip
12997 -----------+--------------+-----------------+-----------------+---------------
12998 str | reg | map_regm | map_reg_int | map_reg_ip
Thierry FOURNIER060762e2014-04-23 13:29:15 +020012999 -----------+--------------+-----------------+-----------------+---------------
13000 int | int | map_int | map_int_int | map_int_ip
13001 -----------+--------------+-----------------+-----------------+---------------
13002 ip | ip | map_ip | map_ip_int | map_ip_ip
13003 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013004
Thierry Fournier8feaa662016-02-10 22:55:20 +010013005 The special map called "map_regm" expect matching zone in the regular
13006 expression and modify the output replacing back reference (like "\1") by
13007 the corresponding match text.
13008
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013009 The file contains one key + value per line. Lines which start with '#' are
13010 ignored, just like empty lines. Leading tabs and spaces are stripped. The key
13011 is then the first "word" (series of non-space/tabs characters), and the value
13012 is what follows this series of space/tab till the end of the line excluding
13013 trailing spaces/tabs.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013014
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013015 Example :
13016
13017 # this is a comment and is ignored
13018 2.22.246.0/23 United Kingdom \n
13019 <-><-----------><--><------------><---->
13020 | | | | `- trailing spaces ignored
13021 | | | `---------- value
13022 | | `-------------------- middle spaces ignored
13023 | `---------------------------- key
13024 `------------------------------------ leading spaces ignored
13025
Willy Tarreau97707872015-01-27 15:12:13 +010013026mod(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013027 Divides the input value of type signed integer by <value>, and returns the
13028 remainder as an signed integer. If <value> is null, then zero is returned.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013029 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010013030 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013031 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013032 "sess" : the variable is shared with the whole session
13033 "txn" : the variable is shared with the transaction (request and response)
13034 "req" : the variable is shared only during request processing
13035 "res" : the variable is shared only during response processing
13036 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013037 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013038
13039mul(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013040 Multiplies the input value of type signed integer by <value>, and returns
Thierry FOURNIER00c005c2015-07-08 01:10:21 +020013041 the product as an signed integer. In case of overflow, the largest possible
13042 value for the sign is returned so that the operation doesn't wrap around.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013043 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010013044 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013045 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013046 "sess" : the variable is shared with the whole session
13047 "txn" : the variable is shared with the transaction (request and response)
13048 "req" : the variable is shared only during request processing
13049 "res" : the variable is shared only during response processing
13050 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013051 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013052
Nenad Merdanovicb7e7c472017-03-12 21:56:55 +010013053nbsrv
13054 Takes an input value of type string, interprets it as a backend name and
13055 returns the number of usable servers in that backend. Can be used in places
13056 where we want to look up a backend from a dynamic name, like a result of a
13057 map lookup.
13058
Willy Tarreau97707872015-01-27 15:12:13 +010013059neg
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013060 Takes the input value of type signed integer, computes the opposite value,
13061 and returns the remainder as an signed integer. 0 is identity. This operator
13062 is provided for reversed subtracts : in order to subtract the input from a
13063 constant, simply perform a "neg,add(value)".
Willy Tarreau97707872015-01-27 15:12:13 +010013064
13065not
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013066 Returns a boolean FALSE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010013067 non-null, otherwise returns TRUE. Used in conjunction with and(), it can be
13068 used to report true/false for bit testing on input values (eg: verify the
13069 absence of a flag).
13070
13071odd
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013072 Returns a boolean TRUE if the input value of type signed integer is odd
Willy Tarreau97707872015-01-27 15:12:13 +010013073 otherwise returns FALSE. It is functionally equivalent to "and(1),bool".
13074
13075or(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013076 Performs a bitwise "OR" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013077 integer, and returns the result as an signed integer. <value> can be a
Daniel Schneller0b547052016-03-21 20:46:57 +010013078 numeric value or a variable name. The name of the variable starts with an
13079 indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013080 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013081 "sess" : the variable is shared with the whole session
13082 "txn" : the variable is shared with the transaction (request and response)
13083 "req" : the variable is shared only during request processing
13084 "res" : the variable is shared only during response processing
13085 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013086 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013087
Willy Tarreauc4dc3502015-01-23 20:39:28 +010013088regsub(<regex>,<subst>[,<flags>])
Willy Tarreau7eda8492015-01-20 19:47:06 +010013089 Applies a regex-based substitution to the input string. It does the same
13090 operation as the well-known "sed" utility with "s/<regex>/<subst>/". By
13091 default it will replace in the input string the first occurrence of the
13092 largest part matching the regular expression <regex> with the substitution
13093 string <subst>. It is possible to replace all occurrences instead by adding
13094 the flag "g" in the third argument <flags>. It is also possible to make the
13095 regex case insensitive by adding the flag "i" in <flags>. Since <flags> is a
13096 string, it is made up from the concatenation of all desired flags. Thus if
13097 both "i" and "g" are desired, using "gi" or "ig" will have the same effect.
13098 It is important to note that due to the current limitations of the
Baptiste Assmann66025d82016-03-06 23:36:48 +010013099 configuration parser, some characters such as closing parenthesis, closing
13100 square brackets or comma are not possible to use in the arguments. The first
13101 use of this converter is to replace certain characters or sequence of
13102 characters with other ones.
Willy Tarreau7eda8492015-01-20 19:47:06 +010013103
13104 Example :
13105
13106 # de-duplicate "/" in header "x-path".
13107 # input: x-path: /////a///b/c/xzxyz/
13108 # output: x-path: /a/b/c/xzxyz/
13109 http-request set-header x-path %[hdr(x-path),regsub(/+,/,g)]
13110
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020013111capture-req(<id>)
13112 Capture the string entry in the request slot <id> and returns the entry as
13113 is. If the slot doesn't exist, the capture fails silently.
13114
13115 See also: "declare capture", "http-request capture",
Baptiste Assmann5ac425c2015-10-21 23:13:46 +020013116 "http-response capture", "capture.req.hdr" and
13117 "capture.res.hdr" (sample fetches).
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020013118
13119capture-res(<id>)
13120 Capture the string entry in the response slot <id> and returns the entry as
13121 is. If the slot doesn't exist, the capture fails silently.
13122
13123 See also: "declare capture", "http-request capture",
Baptiste Assmann5ac425c2015-10-21 23:13:46 +020013124 "http-response capture", "capture.req.hdr" and
13125 "capture.res.hdr" (sample fetches).
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020013126
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013127sdbm([<avalanche>])
13128 Hashes a binary input sample into an unsigned 32-bit quantity using the SDBM
13129 hash function. Optionally, it is possible to apply a full avalanche hash
13130 function to the output if the optional <avalanche> argument equals 1. This
13131 converter uses the same functions as used by the various hash-based load
13132 balancing algorithms, so it will provide exactly the same results. It is
13133 mostly intended for debugging, but can be used as a stick-table entry to
13134 collect rough statistics. It must not be used for security purposes as a
Willy Tarreau80599772015-01-20 19:35:24 +010013135 32-bit hash is trivial to break. See also "crc32", "djb2", "wt6" and the
13136 "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013137
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013138set-var(<var name>)
Daniel Schneller0b547052016-03-21 20:46:57 +010013139 Sets a variable with the input content and returns the content on the output as
13140 is. The variable keeps the value and the associated input type. The name of the
13141 variable starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013142 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013143 "sess" : the variable is shared with the whole session
13144 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013145 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010013146 "req" : the variable is shared only during request processing,
13147 "res" : the variable is shared only during response processing.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013148 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013149 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013150
Dragan Dosen6e5a9ca2017-10-24 09:18:23 +020013151sha1
13152 Converts a binary input sample to a SHA1 digest. The result is a binary
13153 sample with length of 20 bytes.
13154
Willy Tarreau97707872015-01-27 15:12:13 +010013155sub(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013156 Subtracts <value> from the input value of type signed integer, and returns
13157 the result as an signed integer. Note: in order to subtract the input from
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013158 a constant, simply perform a "neg,add(value)". <value> can be a numeric value
Daniel Schneller0b547052016-03-21 20:46:57 +010013159 or a variable name. The name of the variable starts with an indication about
13160 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013161 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013162 "sess" : the variable is shared with the whole session
13163 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013164 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010013165 "req" : the variable is shared only during request processing,
13166 "res" : the variable is shared only during response processing.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013167 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013168 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013169
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013170table_bytes_in_rate(<table>)
13171 Uses the string representation of the input sample to perform a look up in
13172 the specified table. If the key is not found in the table, integer value zero
13173 is returned. Otherwise the converter returns the average client-to-server
13174 bytes rate associated with the input sample in the designated table, measured
13175 in amount of bytes over the period configured in the table. See also the
13176 sc_bytes_in_rate sample fetch keyword.
13177
13178
13179table_bytes_out_rate(<table>)
13180 Uses the string representation of the input sample to perform a look up in
13181 the specified table. If the key is not found in the table, integer value zero
13182 is returned. Otherwise the converter returns the average server-to-client
13183 bytes rate associated with the input sample in the designated table, measured
13184 in amount of bytes over the period configured in the table. See also the
13185 sc_bytes_out_rate sample fetch keyword.
13186
13187table_conn_cnt(<table>)
13188 Uses the string representation of the input sample to perform a look up in
13189 the specified table. If the key is not found in the table, integer value zero
13190 is returned. Otherwise the converter returns the cumulated amount of incoming
13191 connections associated with the input sample in the designated table. See
13192 also the sc_conn_cnt sample fetch keyword.
13193
13194table_conn_cur(<table>)
13195 Uses the string representation of the input sample to perform a look up in
13196 the specified table. If the key is not found in the table, integer value zero
13197 is returned. Otherwise the converter returns the current amount of concurrent
13198 tracked connections associated with the input sample in the designated table.
13199 See also the sc_conn_cur sample fetch keyword.
13200
13201table_conn_rate(<table>)
13202 Uses the string representation of the input sample to perform a look up in
13203 the specified table. If the key is not found in the table, integer value zero
13204 is returned. Otherwise the converter returns the average incoming connection
13205 rate associated with the input sample in the designated table. See also the
13206 sc_conn_rate sample fetch keyword.
13207
Thierry FOURNIER236657b2015-08-19 08:25:14 +020013208table_gpt0(<table>)
13209 Uses the string representation of the input sample to perform a look up in
13210 the specified table. If the key is not found in the table, boolean value zero
13211 is returned. Otherwise the converter returns the current value of the first
13212 general purpose tag associated with the input sample in the designated table.
13213 See also the sc_get_gpt0 sample fetch keyword.
13214
Willy Tarreaud9f316a2014-07-10 14:03:38 +020013215table_gpc0(<table>)
13216 Uses the string representation of the input sample to perform a look up in
13217 the specified table. If the key is not found in the table, integer value zero
13218 is returned. Otherwise the converter returns the current value of the first
13219 general purpose counter associated with the input sample in the designated
13220 table. See also the sc_get_gpc0 sample fetch keyword.
13221
13222table_gpc0_rate(<table>)
13223 Uses the string representation of the input sample to perform a look up in
13224 the specified table. If the key is not found in the table, integer value zero
13225 is returned. Otherwise the converter returns the frequency which the gpc0
13226 counter was incremented over the configured period in the table, associated
13227 with the input sample in the designated table. See also the sc_get_gpc0_rate
13228 sample fetch keyword.
13229
13230table_http_err_cnt(<table>)
13231 Uses the string representation of the input sample to perform a look up in
13232 the specified table. If the key is not found in the table, integer value zero
13233 is returned. Otherwise the converter returns the cumulated amount of HTTP
13234 errors associated with the input sample in the designated table. See also the
13235 sc_http_err_cnt sample fetch keyword.
13236
13237table_http_err_rate(<table>)
13238 Uses the string representation of the input sample to perform a look up in
13239 the specified table. If the key is not found in the table, integer value zero
13240 is returned. Otherwise the average rate of HTTP errors associated with the
13241 input sample in the designated table, measured in amount of errors over the
13242 period configured in the table. See also the sc_http_err_rate sample fetch
13243 keyword.
13244
13245table_http_req_cnt(<table>)
13246 Uses the string representation of the input sample to perform a look up in
13247 the specified table. If the key is not found in the table, integer value zero
13248 is returned. Otherwise the converter returns the cumulated amount of HTTP
13249 requests associated with the input sample in the designated table. See also
13250 the sc_http_req_cnt sample fetch keyword.
13251
13252table_http_req_rate(<table>)
13253 Uses the string representation of the input sample to perform a look up in
13254 the specified table. If the key is not found in the table, integer value zero
13255 is returned. Otherwise the average rate of HTTP requests associated with the
13256 input sample in the designated table, measured in amount of requests over the
13257 period configured in the table. See also the sc_http_req_rate sample fetch
13258 keyword.
13259
13260table_kbytes_in(<table>)
13261 Uses the string representation of the input sample to perform a look up in
13262 the specified table. If the key is not found in the table, integer value zero
13263 is returned. Otherwise the converter returns the cumulated amount of client-
13264 to-server data associated with the input sample in the designated table,
13265 measured in kilobytes. The test is currently performed on 32-bit integers,
13266 which limits values to 4 terabytes. See also the sc_kbytes_in sample fetch
13267 keyword.
13268
13269table_kbytes_out(<table>)
13270 Uses the string representation of the input sample to perform a look up in
13271 the specified table. If the key is not found in the table, integer value zero
13272 is returned. Otherwise the converter returns the cumulated amount of server-
13273 to-client data associated with the input sample in the designated table,
13274 measured in kilobytes. The test is currently performed on 32-bit integers,
13275 which limits values to 4 terabytes. See also the sc_kbytes_out sample fetch
13276 keyword.
13277
13278table_server_id(<table>)
13279 Uses the string representation of the input sample to perform a look up in
13280 the specified table. If the key is not found in the table, integer value zero
13281 is returned. Otherwise the converter returns the server ID associated with
13282 the input sample in the designated table. A server ID is associated to a
13283 sample by a "stick" rule when a connection to a server succeeds. A server ID
13284 zero means that no server is associated with this key.
13285
13286table_sess_cnt(<table>)
13287 Uses the string representation of the input sample to perform a look up in
13288 the specified table. If the key is not found in the table, integer value zero
13289 is returned. Otherwise the converter returns the cumulated amount of incoming
13290 sessions associated with the input sample in the designated table. Note that
13291 a session here refers to an incoming connection being accepted by the
13292 "tcp-request connection" rulesets. See also the sc_sess_cnt sample fetch
13293 keyword.
13294
13295table_sess_rate(<table>)
13296 Uses the string representation of the input sample to perform a look up in
13297 the specified table. If the key is not found in the table, integer value zero
13298 is returned. Otherwise the converter returns the average incoming session
13299 rate associated with the input sample in the designated table. Note that a
13300 session here refers to an incoming connection being accepted by the
13301 "tcp-request connection" rulesets. See also the sc_sess_rate sample fetch
13302 keyword.
13303
13304table_trackers(<table>)
13305 Uses the string representation of the input sample to perform a look up in
13306 the specified table. If the key is not found in the table, integer value zero
13307 is returned. Otherwise the converter returns the current amount of concurrent
13308 connections tracking the same key as the input sample in the designated
13309 table. It differs from table_conn_cur in that it does not rely on any stored
13310 information but on the table's reference count (the "use" value which is
13311 returned by "show table" on the CLI). This may sometimes be more suited for
13312 layer7 tracking. It can be used to tell a server how many concurrent
13313 connections there are from a given address for example. See also the
13314 sc_trackers sample fetch keyword.
13315
Willy Tarreauffcb2e42014-07-10 16:29:08 +020013316upper
13317 Convert a string sample to upper case. This can only be placed after a string
13318 sample fetch function or after a transformation keyword returning a string
13319 type. The result is of type string.
13320
Thierry FOURNIER82ff3c92015-05-07 15:46:20 +020013321url_dec
13322 Takes an url-encoded string provided as input and returns the decoded
13323 version as output. The input and the output are of type string.
13324
Christopher Faulet85d79c92016-11-09 16:54:56 +010013325unset-var(<var name>)
13326 Unsets a variable if the input content is defined. The name of the variable
13327 starts with an indication about its scope. The scopes allowed are:
13328 "proc" : the variable is shared with the whole process
13329 "sess" : the variable is shared with the whole session
13330 "txn" : the variable is shared with the transaction (request and
13331 response),
13332 "req" : the variable is shared only during request processing,
13333 "res" : the variable is shared only during response processing.
13334 This prefix is followed by a name. The separator is a '.'. The name may only
13335 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
13336
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020013337utime(<format>[,<offset>])
13338 Converts an integer supposed to contain a date since epoch to a string
13339 representing this date in UTC time using a format defined by the <format>
13340 string using strftime(3). The purpose is to allow any date format to be used
13341 in logs. An optional <offset> in seconds may be applied to the input date
13342 (positive or negative). See the strftime() man page for the format supported
13343 by your operating system. See also the ltime converter.
13344
13345 Example :
13346
13347 # Emit two colons, one with the UTC time and another with ip:port
13348 # Eg: 20140710162350 127.0.0.1:57325
13349 log-format %[date,utime(%Y%m%d%H%M%S)]\ %ci:%cp
13350
Emeric Brunc9a0f6d2014-11-25 14:09:01 +010013351word(<index>,<delimiters>)
13352 Extracts the nth word considering given delimiters from an input string.
13353 Indexes start at 1 and delimiters are a string formatted list of chars.
13354
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013355wt6([<avalanche>])
13356 Hashes a binary input sample into an unsigned 32-bit quantity using the WT6
13357 hash function. Optionally, it is possible to apply a full avalanche hash
13358 function to the output if the optional <avalanche> argument equals 1. This
13359 converter uses the same functions as used by the various hash-based load
13360 balancing algorithms, so it will provide exactly the same results. It is
13361 mostly intended for debugging, but can be used as a stick-table entry to
13362 collect rough statistics. It must not be used for security purposes as a
Willy Tarreau80599772015-01-20 19:35:24 +010013363 32-bit hash is trivial to break. See also "crc32", "djb2", "sdbm", and the
13364 "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020013365
Willy Tarreau97707872015-01-27 15:12:13 +010013366xor(<value>)
13367 Performs a bitwise "XOR" (exclusive OR) between <value> and the input value
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013368 of type signed integer, and returns the result as an signed integer.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013369 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010013370 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013371 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013372 "sess" : the variable is shared with the whole session
13373 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013374 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010013375 "req" : the variable is shared only during request processing,
13376 "res" : the variable is shared only during response processing.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013377 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013378 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013379
Thierry FOURNIER01e09742016-12-26 11:46:11 +010013380xxh32([<seed>])
13381 Hashes a binary input sample into an unsigned 32-bit quantity using the 32-bit
13382 variant of the XXHash hash function. This hash supports a seed which defaults
13383 to zero but a different value maybe passed as the <seed> argument. This hash
13384 is known to be very good and very fast so it can be used to hash URLs and/or
13385 URL parameters for use as stick-table keys to collect statistics with a low
13386 collision rate, though care must be taken as the algorithm is not considered
13387 as cryptographically secure.
13388
13389xxh64([<seed>])
13390 Hashes a binary input sample into a signed 64-bit quantity using the 64-bit
13391 variant of the XXHash hash function. This hash supports a seed which defaults
13392 to zero but a different value maybe passed as the <seed> argument. This hash
13393 is known to be very good and very fast so it can be used to hash URLs and/or
13394 URL parameters for use as stick-table keys to collect statistics with a low
13395 collision rate, though care must be taken as the algorithm is not considered
13396 as cryptographically secure.
13397
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010013398
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200133997.3.2. Fetching samples from internal states
Willy Tarreau74ca5042013-06-11 23:12:07 +020013400--------------------------------------------
13401
13402A first set of sample fetch methods applies to internal information which does
13403not even relate to any client information. These ones are sometimes used with
13404"monitor-fail" directives to report an internal status to external watchers.
13405The sample fetch methods described in this section are usable anywhere.
13406
13407always_false : boolean
13408 Always returns the boolean "false" value. It may be used with ACLs as a
13409 temporary replacement for another one when adjusting configurations.
13410
13411always_true : boolean
13412 Always returns the boolean "true" value. It may be used with ACLs as a
13413 temporary replacement for another one when adjusting configurations.
13414
13415avg_queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010013416 Returns the total number of queued connections of the designated backend
Willy Tarreau74ca5042013-06-11 23:12:07 +020013417 divided by the number of active servers. The current backend is used if no
13418 backend is specified. This is very similar to "queue" except that the size of
13419 the farm is considered, in order to give a more accurate measurement of the
13420 time it may take for a new connection to be processed. The main usage is with
13421 ACL to return a sorry page to new users when it becomes certain they will get
13422 a degraded service, or to pass to the backend servers in a header so that
13423 they decide to work in degraded mode or to disable some functions to speed up
13424 the processing a bit. Note that in the event there would not be any active
13425 server anymore, twice the number of queued connections would be considered as
13426 the measured value. This is a fair estimate, as we expect one server to get
13427 back soon anyway, but we still prefer to send new traffic to another backend
13428 if in better shape. See also the "queue", "be_conn", and "be_sess_rate"
13429 sample fetches.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +010013430
Willy Tarreau74ca5042013-06-11 23:12:07 +020013431be_conn([<backend>]) : integer
Willy Tarreaua36af912009-10-10 12:02:45 +020013432 Applies to the number of currently established connections on the backend,
13433 possibly including the connection being evaluated. If no backend name is
13434 specified, the current one is used. But it is also possible to check another
13435 backend. It can be used to use a specific farm when the nominal one is full.
13436 See also the "fe_conn", "queue" and "be_sess_rate" criteria.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013437
Willy Tarreau74ca5042013-06-11 23:12:07 +020013438be_sess_rate([<backend>]) : integer
13439 Returns an integer value corresponding to the sessions creation rate on the
13440 backend, in number of new sessions per second. This is used with ACLs to
13441 switch to an alternate backend when an expensive or fragile one reaches too
13442 high a session rate, or to limit abuse of service (eg. prevent sucking of an
13443 online dictionary). It can also be useful to add this element to logs using a
13444 log-format directive.
Willy Tarreaud63335a2010-02-26 12:56:52 +010013445
13446 Example :
13447 # Redirect to an error page if the dictionary is requested too often
13448 backend dynamic
13449 mode http
13450 acl being_scanned be_sess_rate gt 100
13451 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +010013452
Thierry FOURNIERcc103292015-06-06 19:30:17 +020013453bin(<hexa>) : bin
13454 Returns a binary chain. The input is the hexadecimal representation
13455 of the string.
13456
13457bool(<bool>) : bool
13458 Returns a boolean value. <bool> can be 'true', 'false', '1' or '0'.
13459 'false' and '0' are the same. 'true' and '1' are the same.
13460
Willy Tarreau74ca5042013-06-11 23:12:07 +020013461connslots([<backend>]) : integer
13462 Returns an integer value corresponding to the number of connection slots
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013463 still available in the backend, by totaling the maximum amount of
Willy Tarreau74ca5042013-06-11 23:12:07 +020013464 connections on all servers and the maximum queue size. This is probably only
13465 used with ACLs.
Tait Clarridge7896d522012-12-05 21:39:31 -050013466
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080013467 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +020013468 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080013469 usage; see "use_backend" keyword) can be redirected to a different backend.
13470
Willy Tarreau55165fe2009-05-10 12:02:55 +020013471 'connslots' = number of available server connection slots, + number of
13472 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080013473
Willy Tarreaua36af912009-10-10 12:02:45 +020013474 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +020013475 useful when you have a case of traffic going to one single ip, splitting into
Willy Tarreau74ca5042013-06-11 23:12:07 +020013476 multiple backends (perhaps using ACLs to do name-based load balancing) and
Willy Tarreau55165fe2009-05-10 12:02:55 +020013477 you want to be able to differentiate between different backends, and their
13478 available "connslots". Also, whereas "nbsrv" only measures servers that are
Willy Tarreau74ca5042013-06-11 23:12:07 +020013479 actually *down*, this fetch is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +020013480 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080013481
Willy Tarreau55165fe2009-05-10 12:02:55 +020013482 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
13483 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
Willy Tarreau74ca5042013-06-11 23:12:07 +020013484 then this fetch clearly does not make sense, in which case the value returned
Willy Tarreau55165fe2009-05-10 12:02:55 +020013485 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080013486
Willy Tarreau6236d3a2013-07-25 14:28:25 +020013487date([<offset>]) : integer
13488 Returns the current date as the epoch (number of seconds since 01/01/1970).
13489 If an offset value is specified, then it is a number of seconds that is added
13490 to the current date before returning the value. This is particularly useful
13491 to compute relative dates, as both positive and negative offsets are allowed.
Willy Tarreau276fae92013-07-25 14:36:01 +020013492 It is useful combined with the http_date converter.
13493
13494 Example :
13495
13496 # set an expires header to now+1 hour in every response
13497 http-response set-header Expires %[date(3600),http_date]
Willy Tarreau6236d3a2013-07-25 14:28:25 +020013498
Willy Tarreaud716f9b2017-10-13 11:03:15 +020013499distcc_body(<token>[,<occ>]) : binary
13500 Parses a distcc message and returns the body associated to occurrence #<occ>
13501 of the token <token>. Occurrences start at 1, and when unspecified, any may
13502 match though in practice only the first one is checked for now. This can be
13503 used to extract file names or arguments in files built using distcc through
13504 haproxy. Please refer to distcc's protocol documentation for the complete
13505 list of supported tokens.
13506
13507distcc_param(<token>[,<occ>]) : integer
13508 Parses a distcc message and returns the parameter associated to occurrence
13509 #<occ> of the token <token>. Occurrences start at 1, and when unspecified,
13510 any may match though in practice only the first one is checked for now. This
13511 can be used to extract certain information such as the protocol version, the
13512 file size or the argument in files built using distcc through haproxy.
13513 Another use case consists in waiting for the start of the preprocessed file
13514 contents before connecting to the server to avoid keeping idle connections.
13515 Please refer to distcc's protocol documentation for the complete list of
13516 supported tokens.
13517
13518 Example :
13519 # wait up to 20s for the pre-processed file to be uploaded
13520 tcp-request inspect-delay 20s
13521 tcp-request content accept if { distcc_param(DOTI) -m found }
13522 # send large files to the big farm
13523 use_backend big_farm if { distcc_param(DOTI) gt 1000000 }
13524
Willy Tarreau595ec542013-06-12 21:34:28 +020013525env(<name>) : string
13526 Returns a string containing the value of environment variable <name>. As a
13527 reminder, environment variables are per-process and are sampled when the
13528 process starts. This can be useful to pass some information to a next hop
13529 server, or with ACLs to take specific action when the process is started a
13530 certain way.
13531
13532 Examples :
13533 # Pass the Via header to next hop with the local hostname in it
13534 http-request add-header Via 1.1\ %[env(HOSTNAME)]
13535
13536 # reject cookie-less requests when the STOP environment variable is set
13537 http-request deny if !{ cook(SESSIONID) -m found } { env(STOP) -m found }
13538
Willy Tarreau74ca5042013-06-11 23:12:07 +020013539fe_conn([<frontend>]) : integer
13540 Returns the number of currently established connections on the frontend,
Willy Tarreaud63335a2010-02-26 12:56:52 +010013541 possibly including the connection being evaluated. If no frontend name is
13542 specified, the current one is used. But it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020013543 frontend. It can be used to return a sorry page before hard-blocking, or to
13544 use a specific backend to drain new requests when the farm is considered
13545 full. This is mostly used with ACLs but can also be used to pass some
13546 statistics to servers in HTTP headers. See also the "dst_conn", "be_conn",
13547 "fe_sess_rate" fetches.
Willy Tarreaua36af912009-10-10 12:02:45 +020013548
Nenad Merdanovicad9a7e92016-10-03 04:57:37 +020013549fe_req_rate([<frontend>]) : integer
13550 Returns an integer value corresponding to the number of HTTP requests per
13551 second sent to a frontend. This number can differ from "fe_sess_rate" in
13552 situations where client-side keep-alive is enabled.
13553
Willy Tarreau74ca5042013-06-11 23:12:07 +020013554fe_sess_rate([<frontend>]) : integer
13555 Returns an integer value corresponding to the sessions creation rate on the
13556 frontend, in number of new sessions per second. This is used with ACLs to
13557 limit the incoming session rate to an acceptable range in order to prevent
13558 abuse of service at the earliest moment, for example when combined with other
13559 layer 4 ACLs in order to force the clients to wait a bit for the rate to go
13560 down below the limit. It can also be useful to add this element to logs using
13561 a log-format directive. See also the "rate-limit sessions" directive for use
13562 in frontends.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010013563
13564 Example :
13565 # This frontend limits incoming mails to 10/s with a max of 100
13566 # concurrent connections. We accept any connection below 10/s, and
13567 # force excess clients to wait for 100 ms. Since clients are limited to
13568 # 100 max, there cannot be more than 10 incoming mails per second.
13569 frontend mail
13570 bind :25
13571 mode tcp
13572 maxconn 100
13573 acl too_fast fe_sess_rate ge 10
13574 tcp-request inspect-delay 100ms
13575 tcp-request content accept if ! too_fast
13576 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +010013577
Nenad Merdanovic807a6e72017-03-12 22:00:00 +010013578hostname : string
13579 Returns the system hostname.
13580
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013581int(<integer>) : signed integer
13582 Returns a signed integer.
13583
Thierry FOURNIERcc103292015-06-06 19:30:17 +020013584ipv4(<ipv4>) : ipv4
13585 Returns an ipv4.
13586
13587ipv6(<ipv6>) : ipv6
13588 Returns an ipv6.
13589
13590meth(<method>) : method
13591 Returns a method.
13592
Willy Tarreau0f30d262014-11-24 16:02:05 +010013593nbproc : integer
13594 Returns an integer value corresponding to the number of processes that were
13595 started (it equals the global "nbproc" setting). This is useful for logging
13596 and debugging purposes.
13597
Willy Tarreau74ca5042013-06-11 23:12:07 +020013598nbsrv([<backend>]) : integer
13599 Returns an integer value corresponding to the number of usable servers of
13600 either the current backend or the named backend. This is mostly used with
13601 ACLs but can also be useful when added to logs. This is normally used to
Willy Tarreaud63335a2010-02-26 12:56:52 +010013602 switch to an alternate backend when the number of servers is too low to
13603 to handle some load. It is useful to report a failure when combined with
13604 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +010013605
Willy Tarreau0f30d262014-11-24 16:02:05 +010013606proc : integer
13607 Returns an integer value corresponding to the position of the process calling
13608 the function, between 1 and global.nbproc. This is useful for logging and
13609 debugging purposes.
13610
Willy Tarreau74ca5042013-06-11 23:12:07 +020013611queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010013612 Returns the total number of queued connections of the designated backend,
13613 including all the connections in server queues. If no backend name is
13614 specified, the current one is used, but it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020013615 one. This is useful with ACLs or to pass statistics to backend servers. This
13616 can be used to take actions when queuing goes above a known level, generally
13617 indicating a surge of traffic or a massive slowdown on the servers. One
13618 possible action could be to reject new users but still accept old ones. See
13619 also the "avg_queue", "be_conn", and "be_sess_rate" fetches.
13620
Willy Tarreau84310e22014-02-14 11:59:04 +010013621rand([<range>]) : integer
13622 Returns a random integer value within a range of <range> possible values,
13623 starting at zero. If the range is not specified, it defaults to 2^32, which
13624 gives numbers between 0 and 4294967295. It can be useful to pass some values
13625 needed to take some routing decisions for example, or just for debugging
13626 purposes. This random must not be used for security purposes.
13627
Willy Tarreau74ca5042013-06-11 23:12:07 +020013628srv_conn([<backend>/]<server>) : integer
13629 Returns an integer value corresponding to the number of currently established
13630 connections on the designated server, possibly including the connection being
13631 evaluated. If <backend> is omitted, then the server is looked up in the
13632 current backend. It can be used to use a specific farm when one server is
13633 full, or to inform the server about our view of the number of active
13634 connections with it. See also the "fe_conn", "be_conn" and "queue" fetch
13635 methods.
13636
13637srv_is_up([<backend>/]<server>) : boolean
13638 Returns true when the designated server is UP, and false when it is either
13639 DOWN or in maintenance mode. If <backend> is omitted, then the server is
13640 looked up in the current backend. It is mainly used to take action based on
13641 an external status reported via a health check (eg: a geographical site's
13642 availability). Another possible use which is more of a hack consists in
13643 using dummy servers as boolean variables that can be enabled or disabled from
13644 the CLI, so that rules depending on those ACLs can be tweaked in realtime.
13645
Willy Tarreauff2b7af2017-10-13 11:46:26 +020013646srv_queue([<backend>/]<server>) : integer
13647 Returns an integer value corresponding to the number of connections currently
13648 pending in the designated server's queue. If <backend> is omitted, then the
13649 server is looked up in the current backend. It can sometimes be used together
13650 with the "use-server" directive to force to use a known faster server when it
13651 is not much loaded. See also the "srv_conn", "avg_queue" and "queue" sample
13652 fetch methods.
13653
Willy Tarreau74ca5042013-06-11 23:12:07 +020013654srv_sess_rate([<backend>/]<server>) : integer
13655 Returns an integer corresponding to the sessions creation rate on the
13656 designated server, in number of new sessions per second. If <backend> is
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013657 omitted, then the server is looked up in the current backend. This is mostly
Willy Tarreau74ca5042013-06-11 23:12:07 +020013658 used with ACLs but can make sense with logs too. This is used to switch to an
13659 alternate backend when an expensive or fragile one reaches too high a session
13660 rate, or to limit abuse of service (eg. prevent latent requests from
13661 overloading servers).
13662
13663 Example :
13664 # Redirect to a separate back
13665 acl srv1_full srv_sess_rate(be1/srv1) gt 50
13666 acl srv2_full srv_sess_rate(be1/srv2) gt 50
13667 use_backend be2 if srv1_full or srv2_full
13668
Willy Tarreau0f30d262014-11-24 16:02:05 +010013669stopping : boolean
13670 Returns TRUE if the process calling the function is currently stopping. This
13671 can be useful for logging, or for relaxing certain checks or helping close
13672 certain connections upon graceful shutdown.
13673
Thierry FOURNIERcc103292015-06-06 19:30:17 +020013674str(<string>) : string
13675 Returns a string.
13676
Willy Tarreau74ca5042013-06-11 23:12:07 +020013677table_avl([<table>]) : integer
13678 Returns the total number of available entries in the current proxy's
13679 stick-table or in the designated stick-table. See also table_cnt.
13680
13681table_cnt([<table>]) : integer
13682 Returns the total number of entries currently in use in the current proxy's
13683 stick-table or in the designated stick-table. See also src_conn_cnt and
13684 table_avl for other entry counting methods.
13685
Christopher Faulet34adb2a2017-11-21 21:45:38 +010013686thread : integer
13687 Returns an integer value corresponding to the position of the thread calling
13688 the function, between 0 and (global.nbthread-1). This is useful for logging
13689 and debugging purposes.
13690
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013691var(<var-name>) : undefined
13692 Returns a variable with the stored type. If the variable is not set, the
Daniel Schneller0b547052016-03-21 20:46:57 +010013693 sample fetch fails. The name of the variable starts with an indication
13694 about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013695 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013696 "sess" : the variable is shared with the whole session
13697 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013698 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010013699 "req" : the variable is shared only during request processing,
13700 "res" : the variable is shared only during response processing.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013701 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013702 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020013703
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200137047.3.3. Fetching samples at Layer 4
Willy Tarreau74ca5042013-06-11 23:12:07 +020013705----------------------------------
13706
13707The layer 4 usually describes just the transport layer which in haproxy is
13708closest to the connection, where no content is yet made available. The fetch
13709methods described here are usable as low as the "tcp-request connection" rule
13710sets unless they require some future information. Those generally include
13711TCP/IP addresses and ports, as well as elements from stick-tables related to
Willy Tarreau4d4149c2013-07-23 19:33:46 +020013712the incoming connection. For retrieving a value from a sticky counters, the
13713counter number can be explicitly set as 0, 1, or 2 using the pre-defined
13714"sc0_", "sc1_", or "sc2_" prefix, or it can be specified as the first integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013715argument when using the "sc_" prefix. An optional table may be specified with
13716the "sc*" form, in which case the currently tracked key will be looked up into
13717this alternate table instead of the table currently being tracked.
Willy Tarreau74ca5042013-06-11 23:12:07 +020013718
13719be_id : integer
13720 Returns an integer containing the current backend's id. It can be used in
13721 frontends with responses to check which backend processed the request.
13722
Marcin Deranekd2471c22016-12-12 14:08:05 +010013723be_name : string
13724 Returns a string containing the current backend's name. It can be used in
13725 frontends with responses to check which backend processed the request.
13726
Willy Tarreau74ca5042013-06-11 23:12:07 +020013727dst : ip
13728 This is the destination IPv4 address of the connection on the client side,
13729 which is the address the client connected to. It can be useful when running
13730 in transparent mode. It is of type IP and works on both IPv4 and IPv6 tables.
13731 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent, according to
13732 RFC 4291.
13733
13734dst_conn : integer
13735 Returns an integer value corresponding to the number of currently established
13736 connections on the same socket including the one being evaluated. It is
13737 normally used with ACLs but can as well be used to pass the information to
13738 servers in an HTTP header or in logs. It can be used to either return a sorry
13739 page before hard-blocking, or to use a specific backend to drain new requests
13740 when the socket is considered saturated. This offers the ability to assign
13741 different limits to different listening ports or addresses. See also the
13742 "fe_conn" and "be_conn" fetches.
Willy Tarreaud63335a2010-02-26 12:56:52 +010013743
Willy Tarreau16e01562016-08-09 16:46:18 +020013744dst_is_local : boolean
13745 Returns true if the destination address of the incoming connection is local
13746 to the system, or false if the address doesn't exist on the system, meaning
13747 that it was intercepted in transparent mode. It can be useful to apply
13748 certain rules by default to forwarded traffic and other rules to the traffic
13749 targetting the real address of the machine. For example the stats page could
13750 be delivered only on this address, or SSH access could be locally redirected.
13751 Please note that the check involves a few system calls, so it's better to do
13752 it only once per connection.
13753
Willy Tarreau74ca5042013-06-11 23:12:07 +020013754dst_port : integer
13755 Returns an integer value corresponding to the destination TCP port of the
13756 connection on the client side, which is the port the client connected to.
13757 This might be used when running in transparent mode, when assigning dynamic
13758 ports to some clients for a whole application session, to stick all users to
13759 a same server, or to pass the destination port information to a server using
13760 an HTTP header.
13761
Willy Tarreau60ca10a2017-08-18 15:26:54 +020013762fc_http_major : integer
13763 Reports the front connection's HTTP major version encoding, which may be 1
13764 for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire
13765 encoding and not on the version present in the request header.
13766
Emeric Brun4f603012017-01-05 15:11:44 +010013767fc_rcvd_proxy : boolean
13768 Returns true if the client initiated the connection with a PROXY protocol
13769 header.
13770
Thierry Fournier / OZON.IO6310bef2016-07-24 20:16:50 +020013771fc_rtt(<unit>) : integer
13772 Returns the Round Trip Time (RTT) measured by the kernel for the client
13773 connection. <unit> is facultative, by default the unit is milliseconds. <unit>
13774 can be set to "ms" for milliseconds or "us" for microseconds. If the server
13775 connection is not established, if the connection is not TCP or if the
13776 operating system does not support TCP_INFO, for example Linux kernels before
13777 2.4, the sample fetch fails.
13778
13779fc_rttvar(<unit>) : integer
13780 Returns the Round Trip Time (RTT) variance measured by the kernel for the
13781 client connection. <unit> is facultative, by default the unit is milliseconds.
13782 <unit> can be set to "ms" for milliseconds or "us" for microseconds. If the
13783 server connection is not established, if the connection is not TCP or if the
13784 operating system does not support TCP_INFO, for example Linux kernels before
13785 2.4, the sample fetch fails.
13786
Joe Williams30fcd392016-08-10 07:06:44 -070013787fc_unacked(<unit>) : integer
13788 Returns the unacked counter measured by the kernel for the client connection.
13789 If the server connection is not established, if the connection is not TCP or
13790 if the operating system does not support TCP_INFO, for example Linux kernels
13791 before 2.4, the sample fetch fails.
13792
13793fc_sacked(<unit>) : integer
13794 Returns the sacked counter measured by the kernel for the client connection.
13795 If the server connection is not established, if the connection is not TCP or
13796 if the operating system does not support TCP_INFO, for example Linux kernels
13797 before 2.4, the sample fetch fails.
13798
13799fc_retrans(<unit>) : integer
13800 Returns the retransmits counter measured by the kernel for the client
13801 connection. If the server connection is not established, if the connection is
13802 not TCP or if the operating system does not support TCP_INFO, for example
13803 Linux kernels before 2.4, the sample fetch fails.
13804
13805fc_fackets(<unit>) : integer
13806 Returns the fack counter measured by the kernel for the client
13807 connection. If the server connection is not established, if the connection is
13808 not TCP or if the operating system does not support TCP_INFO, for example
13809 Linux kernels before 2.4, the sample fetch fails.
13810
13811fc_lost(<unit>) : integer
13812 Returns the lost counter measured by the kernel for the client
13813 connection. If the server connection is not established, if the connection is
13814 not TCP or if the operating system does not support TCP_INFO, for example
13815 Linux kernels before 2.4, the sample fetch fails.
13816
13817fc_reordering(<unit>) : integer
13818 Returns the reordering counter measured by the kernel for the client
13819 connection. If the server connection is not established, if the connection is
13820 not TCP or if the operating system does not support TCP_INFO, for example
13821 Linux kernels before 2.4, the sample fetch fails.
13822
Willy Tarreau74ca5042013-06-11 23:12:07 +020013823fe_id : integer
13824 Returns an integer containing the current frontend's id. It can be used in
Marcin Deranek6e413ed2016-12-13 12:40:01 +010013825 backends to check from which frontend it was called, or to stick all users
Willy Tarreau74ca5042013-06-11 23:12:07 +020013826 coming via a same frontend to the same server.
13827
Marcin Deranekd2471c22016-12-12 14:08:05 +010013828fe_name : string
13829 Returns a string containing the current frontend's name. It can be used in
13830 backends to check from which frontend it was called, or to stick all users
13831 coming via a same frontend to the same server.
13832
Cyril Bonté62ba8702014-04-22 23:52:25 +020013833sc_bytes_in_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013834sc0_bytes_in_rate([<table>]) : integer
13835sc1_bytes_in_rate([<table>]) : integer
13836sc2_bytes_in_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013837 Returns the average client-to-server bytes rate from the currently tracked
13838 counters, measured in amount of bytes over the period configured in the
13839 table. See also src_bytes_in_rate.
13840
Cyril Bonté62ba8702014-04-22 23:52:25 +020013841sc_bytes_out_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013842sc0_bytes_out_rate([<table>]) : integer
13843sc1_bytes_out_rate([<table>]) : integer
13844sc2_bytes_out_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013845 Returns the average server-to-client bytes rate from the currently tracked
13846 counters, measured in amount of bytes over the period configured in the
13847 table. See also src_bytes_out_rate.
13848
Cyril Bonté62ba8702014-04-22 23:52:25 +020013849sc_clr_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013850sc0_clr_gpc0([<table>]) : integer
13851sc1_clr_gpc0([<table>]) : integer
13852sc2_clr_gpc0([<table>]) : integer
Willy Tarreauf73cd112011-08-13 01:45:16 +020013853 Clears the first General Purpose Counter associated to the currently tracked
13854 counters, and returns its previous value. Before the first invocation, the
Willy Tarreau869948b2013-01-04 14:14:57 +010013855 stored value is zero, so first invocation will always return zero. This is
13856 typically used as a second ACL in an expression in order to mark a connection
13857 when a first ACL was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020013858
Jarno Huuskonen676f6222017-03-30 09:19:45 +030013859 Example:
Willy Tarreauf73cd112011-08-13 01:45:16 +020013860 # block if 5 consecutive requests continue to come faster than 10 sess
13861 # per second, and reset the counter as soon as the traffic slows down.
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020013862 acl abuse sc0_http_req_rate gt 10
13863 acl kill sc0_inc_gpc0 gt 5
13864 acl save sc0_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020013865 tcp-request connection accept if !abuse save
13866 tcp-request connection reject if abuse kill
13867
Cyril Bonté62ba8702014-04-22 23:52:25 +020013868sc_conn_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013869sc0_conn_cnt([<table>]) : integer
13870sc1_conn_cnt([<table>]) : integer
13871sc2_conn_cnt([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013872 Returns the cumulated number of incoming connections from currently tracked
13873 counters. See also src_conn_cnt.
13874
Cyril Bonté62ba8702014-04-22 23:52:25 +020013875sc_conn_cur(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013876sc0_conn_cur([<table>]) : integer
13877sc1_conn_cur([<table>]) : integer
13878sc2_conn_cur([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013879 Returns the current amount of concurrent connections tracking the same
13880 tracked counters. This number is automatically incremented when tracking
13881 begins and decremented when tracking stops. See also src_conn_cur.
13882
Cyril Bonté62ba8702014-04-22 23:52:25 +020013883sc_conn_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013884sc0_conn_rate([<table>]) : integer
13885sc1_conn_rate([<table>]) : integer
13886sc2_conn_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013887 Returns the average connection rate from the currently tracked counters,
13888 measured in amount of connections over the period configured in the table.
13889 See also src_conn_rate.
13890
Cyril Bonté62ba8702014-04-22 23:52:25 +020013891sc_get_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013892sc0_get_gpc0([<table>]) : integer
13893sc1_get_gpc0([<table>]) : integer
13894sc2_get_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013895 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020013896 currently tracked counters. See also src_get_gpc0 and sc/sc0/sc1/sc2_inc_gpc0.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020013897
Thierry FOURNIER236657b2015-08-19 08:25:14 +020013898sc_get_gpt0(<ctr>[,<table>]) : integer
13899sc0_get_gpt0([<table>]) : integer
13900sc1_get_gpt0([<table>]) : integer
13901sc2_get_gpt0([<table>]) : integer
13902 Returns the value of the first General Purpose Tag associated to the
13903 currently tracked counters. See also src_get_gpt0.
13904
Cyril Bonté62ba8702014-04-22 23:52:25 +020013905sc_gpc0_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013906sc0_gpc0_rate([<table>]) : integer
13907sc1_gpc0_rate([<table>]) : integer
13908sc2_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020013909 Returns the average increment rate of the first General Purpose Counter
13910 associated to the currently tracked counters. It reports the frequency
13911 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020013912 src_gpc0_rate, sc/sc0/sc1/sc2_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
13913 that the "gpc0_rate" counter must be stored in the stick-table for a value to
13914 be returned, as "gpc0" only holds the event count.
Willy Tarreaue9656522010-08-17 15:40:09 +020013915
Cyril Bonté62ba8702014-04-22 23:52:25 +020013916sc_http_err_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013917sc0_http_err_cnt([<table>]) : integer
13918sc1_http_err_cnt([<table>]) : integer
13919sc2_http_err_cnt([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013920 Returns the cumulated number of HTTP errors from the currently tracked
13921 counters. This includes the both request errors and 4xx error responses.
13922 See also src_http_err_cnt.
13923
Cyril Bonté62ba8702014-04-22 23:52:25 +020013924sc_http_err_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013925sc0_http_err_rate([<table>]) : integer
13926sc1_http_err_rate([<table>]) : integer
13927sc2_http_err_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013928 Returns the average rate of HTTP errors from the currently tracked counters,
13929 measured in amount of errors over the period configured in the table. This
13930 includes the both request errors and 4xx error responses. See also
13931 src_http_err_rate.
13932
Cyril Bonté62ba8702014-04-22 23:52:25 +020013933sc_http_req_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013934sc0_http_req_cnt([<table>]) : integer
13935sc1_http_req_cnt([<table>]) : integer
13936sc2_http_req_cnt([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013937 Returns the cumulated number of HTTP requests from the currently tracked
13938 counters. This includes every started request, valid or not. See also
13939 src_http_req_cnt.
13940
Cyril Bonté62ba8702014-04-22 23:52:25 +020013941sc_http_req_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013942sc0_http_req_rate([<table>]) : integer
13943sc1_http_req_rate([<table>]) : integer
13944sc2_http_req_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013945 Returns the average rate of HTTP requests from the currently tracked
13946 counters, measured in amount of requests over the period configured in
13947 the table. This includes every started request, valid or not. See also
13948 src_http_req_rate.
13949
Cyril Bonté62ba8702014-04-22 23:52:25 +020013950sc_inc_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013951sc0_inc_gpc0([<table>]) : integer
13952sc1_inc_gpc0([<table>]) : integer
13953sc2_inc_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013954 Increments the first General Purpose Counter associated to the currently
Willy Tarreau869948b2013-01-04 14:14:57 +010013955 tracked counters, and returns its new value. Before the first invocation,
13956 the stored value is zero, so first invocation will increase it to 1 and will
13957 return 1. This is typically used as a second ACL in an expression in order
13958 to mark a connection when a first ACL was verified :
Willy Tarreaue9656522010-08-17 15:40:09 +020013959
Jarno Huuskonen676f6222017-03-30 09:19:45 +030013960 Example:
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020013961 acl abuse sc0_http_req_rate gt 10
13962 acl kill sc0_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020013963 tcp-request connection reject if abuse kill
13964
Cyril Bonté62ba8702014-04-22 23:52:25 +020013965sc_kbytes_in(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013966sc0_kbytes_in([<table>]) : integer
13967sc1_kbytes_in([<table>]) : integer
13968sc2_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020013969 Returns the total amount of client-to-server data from the currently tracked
13970 counters, measured in kilobytes. The test is currently performed on 32-bit
13971 integers, which limits values to 4 terabytes. See also src_kbytes_in.
Willy Tarreaue9656522010-08-17 15:40:09 +020013972
Cyril Bonté62ba8702014-04-22 23:52:25 +020013973sc_kbytes_out(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013974sc0_kbytes_out([<table>]) : integer
13975sc1_kbytes_out([<table>]) : integer
13976sc2_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020013977 Returns the total amount of server-to-client data from the currently tracked
13978 counters, measured in kilobytes. The test is currently performed on 32-bit
13979 integers, which limits values to 4 terabytes. See also src_kbytes_out.
Willy Tarreaue9656522010-08-17 15:40:09 +020013980
Cyril Bonté62ba8702014-04-22 23:52:25 +020013981sc_sess_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013982sc0_sess_cnt([<table>]) : integer
13983sc1_sess_cnt([<table>]) : integer
13984sc2_sess_cnt([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013985 Returns the cumulated number of incoming connections that were transformed
13986 into sessions, which means that they were accepted by a "tcp-request
13987 connection" rule, from the currently tracked counters. A backend may count
13988 more sessions than connections because each connection could result in many
Jamie Gloudonaaa21002012-08-25 00:18:33 -040013989 backend sessions if some HTTP keep-alive is performed over the connection
Willy Tarreaue9656522010-08-17 15:40:09 +020013990 with the client. See also src_sess_cnt.
13991
Cyril Bonté62ba8702014-04-22 23:52:25 +020013992sc_sess_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020013993sc0_sess_rate([<table>]) : integer
13994sc1_sess_rate([<table>]) : integer
13995sc2_sess_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020013996 Returns the average session rate from the currently tracked counters,
13997 measured in amount of sessions over the period configured in the table. A
13998 session is a connection that got past the early "tcp-request connection"
13999 rules. A backend may count more sessions than connections because each
14000 connection could result in many backend sessions if some HTTP keep-alive is
Jamie Gloudonaaa21002012-08-25 00:18:33 -040014001 performed over the connection with the client. See also src_sess_rate.
Willy Tarreaue9656522010-08-17 15:40:09 +020014002
Cyril Bonté62ba8702014-04-22 23:52:25 +020014003sc_tracked(<ctr>[,<table>]) : boolean
Willy Tarreau0f791d42013-07-23 19:56:43 +020014004sc0_tracked([<table>]) : boolean
14005sc1_tracked([<table>]) : boolean
14006sc2_tracked([<table>]) : boolean
Willy Tarreau6f1615f2013-06-03 15:15:22 +020014007 Returns true if the designated session counter is currently being tracked by
14008 the current session. This can be useful when deciding whether or not we want
14009 to set some values in a header passed to the server.
14010
Cyril Bonté62ba8702014-04-22 23:52:25 +020014011sc_trackers(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020014012sc0_trackers([<table>]) : integer
14013sc1_trackers([<table>]) : integer
14014sc2_trackers([<table>]) : integer
Willy Tarreau2406db42012-12-09 12:16:43 +010014015 Returns the current amount of concurrent connections tracking the same
14016 tracked counters. This number is automatically incremented when tracking
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020014017 begins and decremented when tracking stops. It differs from sc0_conn_cur in
Willy Tarreau2406db42012-12-09 12:16:43 +010014018 that it does not rely on any stored information but on the table's reference
14019 count (the "use" value which is returned by "show table" on the CLI). This
Willy Tarreau74ca5042013-06-11 23:12:07 +020014020 may sometimes be more suited for layer7 tracking. It can be used to tell a
14021 server how many concurrent connections there are from a given address for
14022 example.
Willy Tarreau2406db42012-12-09 12:16:43 +010014023
Willy Tarreau74ca5042013-06-11 23:12:07 +020014024so_id : integer
14025 Returns an integer containing the current listening socket's id. It is useful
14026 in frontends involving many "bind" lines, or to stick all users coming via a
14027 same socket to the same server.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014028
Willy Tarreau74ca5042013-06-11 23:12:07 +020014029src : ip
14030 This is the source IPv4 address of the client of the session. It is of type
14031 IP and works on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are
14032 mapped to their IPv6 equivalent, according to RFC 4291. Note that it is the
14033 TCP-level source address which is used, and not the address of a client
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010014034 behind a proxy. However if the "accept-proxy" or "accept-netscaler-cip" bind
14035 directive is used, it can be the address of a client behind another
14036 PROXY-protocol compatible component for all rule sets except
14037 "tcp-request connection" which sees the real address.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014038
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010014039 Example:
14040 # add an HTTP header in requests with the originating address' country
14041 http-request set-header X-Country %[src,map_ip(geoip.lst)]
14042
Willy Tarreau74ca5042013-06-11 23:12:07 +020014043src_bytes_in_rate([<table>]) : integer
14044 Returns the average bytes rate from the incoming connection's source address
14045 in the current proxy's stick-table or in the designated stick-table, measured
14046 in amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014047 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014048
Willy Tarreau74ca5042013-06-11 23:12:07 +020014049src_bytes_out_rate([<table>]) : integer
14050 Returns the average bytes rate to the incoming connection's source address in
14051 the current proxy's stick-table or in the designated stick-table, measured in
Willy Tarreauc9705a12010-07-27 20:05:50 +020014052 amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014053 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014054
Willy Tarreau74ca5042013-06-11 23:12:07 +020014055src_clr_gpc0([<table>]) : integer
14056 Clears the first General Purpose Counter associated to the incoming
14057 connection's source address in the current proxy's stick-table or in the
14058 designated stick-table, and returns its previous value. If the address is not
14059 found, an entry is created and 0 is returned. This is typically used as a
14060 second ACL in an expression in order to mark a connection when a first ACL
14061 was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020014062
Jarno Huuskonen676f6222017-03-30 09:19:45 +030014063 Example:
Willy Tarreauf73cd112011-08-13 01:45:16 +020014064 # block if 5 consecutive requests continue to come faster than 10 sess
14065 # per second, and reset the counter as soon as the traffic slows down.
14066 acl abuse src_http_req_rate gt 10
14067 acl kill src_inc_gpc0 gt 5
Willy Tarreau869948b2013-01-04 14:14:57 +010014068 acl save src_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020014069 tcp-request connection accept if !abuse save
14070 tcp-request connection reject if abuse kill
14071
Willy Tarreau74ca5042013-06-11 23:12:07 +020014072src_conn_cnt([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020014073 Returns the cumulated number of connections initiated from the current
Willy Tarreau74ca5042013-06-11 23:12:07 +020014074 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020014075 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014076 See also sc/sc0/sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014077
Willy Tarreau74ca5042013-06-11 23:12:07 +020014078src_conn_cur([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020014079 Returns the current amount of concurrent connections initiated from the
Willy Tarreau74ca5042013-06-11 23:12:07 +020014080 current incoming connection's source address in the current proxy's
14081 stick-table or in the designated stick-table. If the address is not found,
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014082 zero is returned. See also sc/sc0/sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014083
Willy Tarreau74ca5042013-06-11 23:12:07 +020014084src_conn_rate([<table>]) : integer
14085 Returns the average connection rate from the incoming connection's source
14086 address in the current proxy's stick-table or in the designated stick-table,
14087 measured in amount of connections over the period configured in the table. If
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014088 the address is not found, zero is returned. See also sc/sc0/sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014089
Willy Tarreau74ca5042013-06-11 23:12:07 +020014090src_get_gpc0([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020014091 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau74ca5042013-06-11 23:12:07 +020014092 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020014093 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014094 See also sc/sc0/sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014095
Thierry FOURNIER236657b2015-08-19 08:25:14 +020014096src_get_gpt0([<table>]) : integer
14097 Returns the value of the first General Purpose Tag associated to the
14098 incoming connection's source address in the current proxy's stick-table or in
14099 the designated stick-table. If the address is not found, zero is returned.
14100 See also sc/sc0/sc1/sc2_get_gpt0.
14101
Willy Tarreau74ca5042013-06-11 23:12:07 +020014102src_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014103 Returns the average increment rate of the first General Purpose Counter
Willy Tarreau74ca5042013-06-11 23:12:07 +020014104 associated to the incoming connection's source address in the current proxy's
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014105 stick-table or in the designated stick-table. It reports the frequency
14106 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014107 sc/sc0/sc1/sc2_gpc0_rate, src_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
14108 that the "gpc0_rate" counter must be stored in the stick-table for a value to
14109 be returned, as "gpc0" only holds the event count.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020014110
Willy Tarreau74ca5042013-06-11 23:12:07 +020014111src_http_err_cnt([<table>]) : integer
14112 Returns the cumulated number of HTTP errors from the incoming connection's
14113 source address in the current proxy's stick-table or in the designated
Willy Tarreauc9705a12010-07-27 20:05:50 +020014114 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014115 See also sc/sc0/sc1/sc2_http_err_cnt. If the address is not found, zero is
Willy Tarreau74ca5042013-06-11 23:12:07 +020014116 returned.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014117
Willy Tarreau74ca5042013-06-11 23:12:07 +020014118src_http_err_rate([<table>]) : integer
14119 Returns the average rate of HTTP errors from the incoming connection's source
14120 address in the current proxy's stick-table or in the designated stick-table,
14121 measured in amount of errors over the period configured in the table. This
14122 includes the both request errors and 4xx error responses. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014123 not found, zero is returned. See also sc/sc0/sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014124
Willy Tarreau74ca5042013-06-11 23:12:07 +020014125src_http_req_cnt([<table>]) : integer
14126 Returns the cumulated number of HTTP requests from the incoming connection's
14127 source address in the current proxy's stick-table or in the designated stick-
14128 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014129 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014130
Willy Tarreau74ca5042013-06-11 23:12:07 +020014131src_http_req_rate([<table>]) : integer
14132 Returns the average rate of HTTP requests from the incoming connection's
14133 source address in the current proxy's stick-table or in the designated stick-
14134 table, measured in amount of requests over the period configured in the
Willy Tarreauc9705a12010-07-27 20:05:50 +020014135 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014136 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014137
Willy Tarreau74ca5042013-06-11 23:12:07 +020014138src_inc_gpc0([<table>]) : integer
14139 Increments the first General Purpose Counter associated to the incoming
14140 connection's source address in the current proxy's stick-table or in the
14141 designated stick-table, and returns its new value. If the address is not
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020014142 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc0.
Willy Tarreau74ca5042013-06-11 23:12:07 +020014143 This is typically used as a second ACL in an expression in order to mark a
14144 connection when a first ACL was verified :
Willy Tarreauc9705a12010-07-27 20:05:50 +020014145
Jarno Huuskonen676f6222017-03-30 09:19:45 +030014146 Example:
Willy Tarreauc9705a12010-07-27 20:05:50 +020014147 acl abuse src_http_req_rate gt 10
Willy Tarreau869948b2013-01-04 14:14:57 +010014148 acl kill src_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020014149 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +020014150
Willy Tarreau16e01562016-08-09 16:46:18 +020014151src_is_local : boolean
14152 Returns true if the source address of the incoming connection is local to the
14153 system, or false if the address doesn't exist on the system, meaning that it
14154 comes from a remote machine. Note that UNIX addresses are considered local.
14155 It can be useful to apply certain access restrictions based on where the
14156 client comes from (eg: require auth or https for remote machines). Please
14157 note that the check involves a few system calls, so it's better to do it only
14158 once per connection.
14159
Willy Tarreau74ca5042013-06-11 23:12:07 +020014160src_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020014161 Returns the total amount of data received from the incoming connection's
14162 source address in the current proxy's stick-table or in the designated
14163 stick-table, measured in kilobytes. If the address is not found, zero is
14164 returned. The test is currently performed on 32-bit integers, which limits
14165 values to 4 terabytes. See also sc/sc0/sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014166
Willy Tarreau74ca5042013-06-11 23:12:07 +020014167src_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020014168 Returns the total amount of data sent to the incoming connection's source
14169 address in the current proxy's stick-table or in the designated stick-table,
14170 measured in kilobytes. If the address is not found, zero is returned. The
14171 test is currently performed on 32-bit integers, which limits values to 4
14172 terabytes. See also sc/sc0/sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020014173
Willy Tarreau74ca5042013-06-11 23:12:07 +020014174src_port : integer
14175 Returns an integer value corresponding to the TCP source port of the
14176 connection on the client side, which is the port the client connected from.
14177 Usage of this function is very limited as modern protocols do not care much
14178 about source ports nowadays.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010014179
Willy Tarreau74ca5042013-06-11 23:12:07 +020014180src_sess_cnt([<table>]) : integer
14181 Returns the cumulated number of connections initiated from the incoming
Willy Tarreauc9705a12010-07-27 20:05:50 +020014182 connection's source IPv4 address in the current proxy's stick-table or in the
14183 designated stick-table, that were transformed into sessions, which means that
14184 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014185 is returned. See also sc/sc0/sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014186
Willy Tarreau74ca5042013-06-11 23:12:07 +020014187src_sess_rate([<table>]) : integer
14188 Returns the average session rate from the incoming connection's source
14189 address in the current proxy's stick-table or in the designated stick-table,
14190 measured in amount of sessions over the period configured in the table. A
14191 session is a connection that went past the early "tcp-request" rules. If the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020014192 address is not found, zero is returned. See also sc/sc0/sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020014193
Willy Tarreau74ca5042013-06-11 23:12:07 +020014194src_updt_conn_cnt([<table>]) : integer
14195 Creates or updates the entry associated to the incoming connection's source
14196 address in the current proxy's stick-table or in the designated stick-table.
14197 This table must be configured to store the "conn_cnt" data type, otherwise
14198 the match will be ignored. The current count is incremented by one, and the
14199 expiration timer refreshed. The updated count is returned, so this match
14200 can't return zero. This was used to reject service abusers based on their
14201 source address. Note: it is recommended to use the more complete "track-sc*"
14202 actions in "tcp-request" rules instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020014203
14204 Example :
14205 # This frontend limits incoming SSH connections to 3 per 10 second for
14206 # each source address, and rejects excess connections until a 10 second
14207 # silence is observed. At most 20 addresses are tracked.
14208 listen ssh
14209 bind :22
14210 mode tcp
14211 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +020014212 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreau74ca5042013-06-11 23:12:07 +020014213 tcp-request content reject if { src_updt_conn_cnt gt 3 }
Willy Tarreaua975b8f2010-06-05 19:13:27 +020014214 server local 127.0.0.1:22
14215
Willy Tarreau74ca5042013-06-11 23:12:07 +020014216srv_id : integer
14217 Returns an integer containing the server's id when processing the response.
14218 While it's almost only used with ACLs, it may be used for logging or
14219 debugging.
Hervé COMMOWICKdaa824e2011-08-05 12:09:44 +020014220
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200142217.3.4. Fetching samples at Layer 5
Willy Tarreau74ca5042013-06-11 23:12:07 +020014222----------------------------------
Willy Tarreau0b1cd942010-05-16 22:18:27 +020014223
Willy Tarreau74ca5042013-06-11 23:12:07 +020014224The layer 5 usually describes just the session layer which in haproxy is
14225closest to the session once all the connection handshakes are finished, but
14226when no content is yet made available. The fetch methods described here are
14227usable as low as the "tcp-request content" rule sets unless they require some
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014228future information. Those generally include the results of SSL negotiations.
Willy Tarreauc735a072011-03-29 00:57:02 +020014229
Ben Shillitof25e8e52016-12-02 14:25:37 +00001423051d.all(<prop>[,<prop>*]) : string
14231 Returns values for the properties requested as a string, where values are
14232 separated by the delimiter specified with "51degrees-property-separator".
14233 The device is identified using all the important HTTP headers from the
14234 request. The function can be passed up to five property names, and if a
14235 property name can't be found, the value "NoData" is returned.
14236
14237 Example :
14238 # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request
14239 # containing the three properties requested using all relevant headers from
14240 # the request.
14241 frontend http-in
14242 bind *:8081
14243 default_backend servers
14244 http-request set-header X-51D-DeviceTypeMobileTablet \
14245 %[51d.all(DeviceType,IsMobile,IsTablet)]
14246
Emeric Brun645ae792014-04-30 14:21:06 +020014247ssl_bc : boolean
14248 Returns true when the back connection was made via an SSL/TLS transport
14249 layer and is locally deciphered. This means the outgoing connection was made
14250 other a server with the "ssl" option.
14251
14252ssl_bc_alg_keysize : integer
14253 Returns the symmetric cipher key size supported in bits when the outgoing
14254 connection was made over an SSL/TLS transport layer.
14255
14256ssl_bc_cipher : string
14257 Returns the name of the used cipher when the outgoing connection was made
14258 over an SSL/TLS transport layer.
14259
14260ssl_bc_protocol : string
14261 Returns the name of the used protocol when the outgoing connection was made
14262 over an SSL/TLS transport layer.
14263
Emeric Brunb73a9b02014-04-30 18:49:19 +020014264ssl_bc_unique_id : binary
Emeric Brun645ae792014-04-30 14:21:06 +020014265 When the outgoing connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020014266 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
14267 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".
Emeric Brun645ae792014-04-30 14:21:06 +020014268
14269ssl_bc_session_id : binary
14270 Returns the SSL ID of the back connection when the outgoing connection was
14271 made over an SSL/TLS transport layer. It is useful to log if we want to know
14272 if session was reused or not.
14273
14274ssl_bc_use_keysize : integer
14275 Returns the symmetric cipher key size used in bits when the outgoing
14276 connection was made over an SSL/TLS transport layer.
14277
Willy Tarreau74ca5042013-06-11 23:12:07 +020014278ssl_c_ca_err : integer
14279 When the incoming connection was made over an SSL/TLS transport layer,
14280 returns the ID of the first error detected during verification of the client
14281 certificate at depth > 0, or 0 if no error was encountered during this
14282 verification process. Please refer to your SSL library's documentation to
14283 find the exhaustive list of error codes.
Willy Tarreauc735a072011-03-29 00:57:02 +020014284
Willy Tarreau74ca5042013-06-11 23:12:07 +020014285ssl_c_ca_err_depth : integer
14286 When the incoming connection was made over an SSL/TLS transport layer,
14287 returns the depth in the CA chain of the first error detected during the
14288 verification of the client certificate. If no error is encountered, 0 is
14289 returned.
Willy Tarreau0ba27502007-12-24 16:55:16 +010014290
Emeric Brun43e79582014-10-29 19:03:26 +010014291ssl_c_der : binary
14292 Returns the DER formatted certificate presented by the client when the
14293 incoming connection was made over an SSL/TLS transport layer. When used for
14294 an ACL, the value(s) to match against can be passed in hexadecimal form.
14295
Willy Tarreau74ca5042013-06-11 23:12:07 +020014296ssl_c_err : integer
14297 When the incoming connection was made over an SSL/TLS transport layer,
14298 returns the ID of the first error detected during verification at depth 0, or
14299 0 if no error was encountered during this verification process. Please refer
14300 to your SSL library's documentation to find the exhaustive list of error
14301 codes.
Willy Tarreau62644772008-07-16 18:36:06 +020014302
Willy Tarreau74ca5042013-06-11 23:12:07 +020014303ssl_c_i_dn([<entry>[,<occ>]]) : string
14304 When the incoming connection was made over an SSL/TLS transport layer,
14305 returns the full distinguished name of the issuer of the certificate
14306 presented by the client when no <entry> is specified, or the value of the
14307 first given entry found from the beginning of the DN. If a positive/negative
14308 occurrence number is specified as the optional second argument, it returns
14309 the value of the nth given entry value from the beginning/end of the DN.
14310 For instance, "ssl_c_i_dn(OU,2)" the second organization unit, and
14311 "ssl_c_i_dn(CN)" retrieves the common name.
Willy Tarreau62644772008-07-16 18:36:06 +020014312
Willy Tarreau74ca5042013-06-11 23:12:07 +020014313ssl_c_key_alg : string
14314 Returns the name of the algorithm used to generate the key of the certificate
14315 presented by the client when the incoming connection was made over an SSL/TLS
14316 transport layer.
Willy Tarreau62644772008-07-16 18:36:06 +020014317
Willy Tarreau74ca5042013-06-11 23:12:07 +020014318ssl_c_notafter : string
14319 Returns the end date presented by the client as a formatted string
14320 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
14321 transport layer.
Emeric Brunbede3d02009-06-30 17:54:00 +020014322
Willy Tarreau74ca5042013-06-11 23:12:07 +020014323ssl_c_notbefore : string
14324 Returns the start date presented by the client as a formatted string
14325 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
14326 transport layer.
Willy Tarreaub6672b52011-12-12 17:23:41 +010014327
Willy Tarreau74ca5042013-06-11 23:12:07 +020014328ssl_c_s_dn([<entry>[,<occ>]]) : string
14329 When the incoming connection was made over an SSL/TLS transport layer,
14330 returns the full distinguished name of the subject of the certificate
14331 presented by the client when no <entry> is specified, or the value of the
14332 first given entry found from the beginning of the DN. If a positive/negative
14333 occurrence number is specified as the optional second argument, it returns
14334 the value of the nth given entry value from the beginning/end of the DN.
14335 For instance, "ssl_c_s_dn(OU,2)" the second organization unit, and
14336 "ssl_c_s_dn(CN)" retrieves the common name.
Willy Tarreaub6672b52011-12-12 17:23:41 +010014337
Willy Tarreau74ca5042013-06-11 23:12:07 +020014338ssl_c_serial : binary
14339 Returns the serial of the certificate presented by the client when the
14340 incoming connection was made over an SSL/TLS transport layer. When used for
14341 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun2525b6b2012-10-18 15:59:43 +020014342
Willy Tarreau74ca5042013-06-11 23:12:07 +020014343ssl_c_sha1 : binary
14344 Returns the SHA-1 fingerprint of the certificate presented by the client when
14345 the incoming connection was made over an SSL/TLS transport layer. This can be
14346 used to stick a client to a server, or to pass this information to a server.
Willy Tarreau2d0caa32014-07-02 19:01:22 +020014347 Note that the output is binary, so if you want to pass that signature to the
14348 server, you need to encode it in hex or base64, such as in the example below:
14349
Jarno Huuskonen676f6222017-03-30 09:19:45 +030014350 Example:
Willy Tarreau2d0caa32014-07-02 19:01:22 +020014351 http-request set-header X-SSL-Client-SHA1 %[ssl_c_sha1,hex]
Emeric Brun2525b6b2012-10-18 15:59:43 +020014352
Willy Tarreau74ca5042013-06-11 23:12:07 +020014353ssl_c_sig_alg : string
14354 Returns the name of the algorithm used to sign the certificate presented by
14355 the client when the incoming connection was made over an SSL/TLS transport
14356 layer.
Emeric Brun87855892012-10-17 17:39:35 +020014357
Willy Tarreau74ca5042013-06-11 23:12:07 +020014358ssl_c_used : boolean
14359 Returns true if current SSL session uses a client certificate even if current
14360 connection uses SSL session resumption. See also "ssl_fc_has_crt".
Emeric Brun7f56e742012-10-19 18:15:40 +020014361
Willy Tarreau74ca5042013-06-11 23:12:07 +020014362ssl_c_verify : integer
14363 Returns the verify result error ID when the incoming connection was made over
14364 an SSL/TLS transport layer, otherwise zero if no error is encountered. Please
14365 refer to your SSL library's documentation for an exhaustive list of error
14366 codes.
Emeric Brunce5ad802012-10-22 14:11:22 +020014367
Willy Tarreau74ca5042013-06-11 23:12:07 +020014368ssl_c_version : integer
14369 Returns the version of the certificate presented by the client when the
14370 incoming connection was made over an SSL/TLS transport layer.
Emeric Brunce5ad802012-10-22 14:11:22 +020014371
Emeric Brun43e79582014-10-29 19:03:26 +010014372ssl_f_der : binary
14373 Returns the DER formatted certificate presented by the frontend when the
14374 incoming connection was made over an SSL/TLS transport layer. When used for
14375 an ACL, the value(s) to match against can be passed in hexadecimal form.
14376
Willy Tarreau74ca5042013-06-11 23:12:07 +020014377ssl_f_i_dn([<entry>[,<occ>]]) : string
14378 When the incoming connection was made over an SSL/TLS transport layer,
14379 returns the full distinguished name of the issuer of the certificate
14380 presented by the frontend when no <entry> is specified, or the value of the
14381 first given entry found from the beginning of the DN. If a positive/negative
Emeric Brun87855892012-10-17 17:39:35 +020014382 occurrence number is specified as the optional second argument, it returns
Willy Tarreau74ca5042013-06-11 23:12:07 +020014383 the value of the nth given entry value from the beginning/end of the DN.
14384 For instance, "ssl_f_i_dn(OU,2)" the second organization unit, and
14385 "ssl_f_i_dn(CN)" retrieves the common name.
Emeric Brun87855892012-10-17 17:39:35 +020014386
Willy Tarreau74ca5042013-06-11 23:12:07 +020014387ssl_f_key_alg : string
14388 Returns the name of the algorithm used to generate the key of the certificate
14389 presented by the frontend when the incoming connection was made over an
14390 SSL/TLS transport layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020014391
Willy Tarreau74ca5042013-06-11 23:12:07 +020014392ssl_f_notafter : string
14393 Returns the end date presented by the frontend as a formatted string
14394 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
14395 transport layer.
Emeric Brun2525b6b2012-10-18 15:59:43 +020014396
Willy Tarreau74ca5042013-06-11 23:12:07 +020014397ssl_f_notbefore : string
14398 Returns the start date presented by the frontend as a formatted string
14399 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
14400 transport layer.
Emeric Brun87855892012-10-17 17:39:35 +020014401
Willy Tarreau74ca5042013-06-11 23:12:07 +020014402ssl_f_s_dn([<entry>[,<occ>]]) : string
14403 When the incoming connection was made over an SSL/TLS transport layer,
14404 returns the full distinguished name of the subject of the certificate
14405 presented by the frontend when no <entry> is specified, or the value of the
14406 first given entry found from the beginning of the DN. If a positive/negative
14407 occurrence number is specified as the optional second argument, it returns
14408 the value of the nth given entry value from the beginning/end of the DN.
14409 For instance, "ssl_f_s_dn(OU,2)" the second organization unit, and
14410 "ssl_f_s_dn(CN)" retrieves the common name.
Emeric Brunce5ad802012-10-22 14:11:22 +020014411
Willy Tarreau74ca5042013-06-11 23:12:07 +020014412ssl_f_serial : binary
14413 Returns the serial of the certificate presented by the frontend when the
14414 incoming connection was made over an SSL/TLS transport layer. When used for
14415 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun87855892012-10-17 17:39:35 +020014416
Emeric Brun55f4fa82014-04-30 17:11:25 +020014417ssl_f_sha1 : binary
14418 Returns the SHA-1 fingerprint of the certificate presented by the frontend
14419 when the incoming connection was made over an SSL/TLS transport layer. This
14420 can be used to know which certificate was chosen using SNI.
14421
Willy Tarreau74ca5042013-06-11 23:12:07 +020014422ssl_f_sig_alg : string
14423 Returns the name of the algorithm used to sign the certificate presented by
14424 the frontend when the incoming connection was made over an SSL/TLS transport
14425 layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020014426
Willy Tarreau74ca5042013-06-11 23:12:07 +020014427ssl_f_version : integer
14428 Returns the version of the certificate presented by the frontend when the
14429 incoming connection was made over an SSL/TLS transport layer.
14430
14431ssl_fc : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020014432 Returns true when the front connection was made via an SSL/TLS transport
14433 layer and is locally deciphered. This means it has matched a socket declared
14434 with a "bind" line having the "ssl" option.
14435
Willy Tarreau74ca5042013-06-11 23:12:07 +020014436 Example :
14437 # This passes "X-Proto: https" to servers when client connects over SSL
14438 listen http-https
14439 bind :80
14440 bind :443 ssl crt /etc/haproxy.pem
14441 http-request add-header X-Proto https if { ssl_fc }
14442
14443ssl_fc_alg_keysize : integer
14444 Returns the symmetric cipher key size supported in bits when the incoming
14445 connection was made over an SSL/TLS transport layer.
14446
14447ssl_fc_alpn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014448 This extracts the Application Layer Protocol Negotiation field from an
Willy Tarreau74ca5042013-06-11 23:12:07 +020014449 incoming connection made via a TLS transport layer and locally deciphered by
14450 haproxy. The result is a string containing the protocol name advertised by
14451 the client. The SSL library must have been built with support for TLS
14452 extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
14453 not advertised unless the "alpn" keyword on the "bind" line specifies a
14454 protocol list. Also, nothing forces the client to pick a protocol from this
14455 list, any other one may be requested. The TLS ALPN extension is meant to
14456 replace the TLS NPN extension. See also "ssl_fc_npn".
14457
Willy Tarreau74ca5042013-06-11 23:12:07 +020014458ssl_fc_cipher : string
14459 Returns the name of the used cipher when the incoming connection was made
14460 over an SSL/TLS transport layer.
Willy Tarreauab861d32013-04-02 02:30:41 +020014461
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010014462ssl_fc_cipherlist_bin : binary
14463 Returns the binary form of the client hello cipher list. The maximum returned
14464 value length is according with the value of
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010014465 "tune.ssl.capture-cipherlist-size".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010014466
14467ssl_fc_cipherlist_hex : string
14468 Returns the binary form of the client hello cipher list encoded as
14469 hexadecimal. The maximum returned value length is according with the value of
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010014470 "tune.ssl.capture-cipherlist-size".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010014471
14472ssl_fc_cipherlist_str : string
14473 Returns the decoded text form of the client hello cipher list. The maximum
14474 number of ciphers returned is according with the value of
14475 "tune.ssl.capture-cipherlist-size". Note that this sample-fetch is only
Emmanuel Hocdetddcde192017-09-01 17:32:08 +020014476 avaible with OpenSSL >= 1.0.2. If the function is not enabled, this
14477 sample-fetch returns the hash like "ssl_fc_cipherlist_xxh".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010014478
14479ssl_fc_cipherlist_xxh : integer
14480 Returns a xxh64 of the cipher list. This hash can be return only is the value
14481 "tune.ssl.capture-cipherlist-size" is set greater than 0, however the hash
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010014482 take in account all the data of the cipher list.
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010014483
Willy Tarreau74ca5042013-06-11 23:12:07 +020014484ssl_fc_has_crt : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020014485 Returns true if a client certificate is present in an incoming connection over
14486 SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
Emeric Brun9143d372012-12-20 15:44:16 +010014487 Note: on SSL session resumption with Session ID or TLS ticket, client
14488 certificate is not present in the current connection but may be retrieved
14489 from the cache or the ticket. So prefer "ssl_c_used" if you want to check if
14490 current SSL session uses a client certificate.
Emeric Brun2525b6b2012-10-18 15:59:43 +020014491
Olivier Houchardccaa7de2017-10-02 11:51:03 +020014492ssl_fc_has_early : boolean
14493 Returns true if early data were sent, and the handshake didn't happen yet. As
14494 it has security implications, it is useful to be able to refuse those, or
14495 wait until the handshake happened.
14496
Willy Tarreau74ca5042013-06-11 23:12:07 +020014497ssl_fc_has_sni : boolean
14498 This checks for the presence of a Server Name Indication TLS extension (SNI)
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020014499 in an incoming connection was made over an SSL/TLS transport layer. Returns
14500 true when the incoming connection presents a TLS SNI field. This requires
14501 that the SSL library is build with support for TLS extensions enabled (check
14502 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +020014503
Nenad Merdanovic1516fe32016-05-17 03:31:21 +020014504ssl_fc_is_resumed : boolean
Nenad Merdanovic26ea8222015-05-18 02:28:57 +020014505 Returns true if the SSL/TLS session has been resumed through the use of
14506 SSL session cache or TLS tickets.
14507
Willy Tarreau74ca5042013-06-11 23:12:07 +020014508ssl_fc_npn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014509 This extracts the Next Protocol Negotiation field from an incoming connection
Willy Tarreau74ca5042013-06-11 23:12:07 +020014510 made via a TLS transport layer and locally deciphered by haproxy. The result
14511 is a string containing the protocol name advertised by the client. The SSL
14512 library must have been built with support for TLS extensions enabled (check
14513 haproxy -vv). Note that the TLS NPN extension is not advertised unless the
14514 "npn" keyword on the "bind" line specifies a protocol list. Also, nothing
14515 forces the client to pick a protocol from this list, any other one may be
14516 requested. Please note that the TLS NPN extension was replaced with ALPN.
Willy Tarreaua33c6542012-10-15 13:19:06 +020014517
Willy Tarreau74ca5042013-06-11 23:12:07 +020014518ssl_fc_protocol : string
14519 Returns the name of the used protocol when the incoming connection was made
14520 over an SSL/TLS transport layer.
Willy Tarreau7875d092012-09-10 08:20:03 +020014521
Emeric Brunb73a9b02014-04-30 18:49:19 +020014522ssl_fc_unique_id : binary
David Sc1ad52e2014-04-08 18:48:47 -040014523 When the incoming connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020014524 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
14525 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".
David Sc1ad52e2014-04-08 18:48:47 -040014526
Willy Tarreau74ca5042013-06-11 23:12:07 +020014527ssl_fc_session_id : binary
14528 Returns the SSL ID of the front connection when the incoming connection was
14529 made over an SSL/TLS transport layer. It is useful to stick a given client to
14530 a server. It is important to note that some browsers refresh their session ID
14531 every few minutes.
Willy Tarreau7875d092012-09-10 08:20:03 +020014532
Willy Tarreau74ca5042013-06-11 23:12:07 +020014533ssl_fc_sni : string
14534 This extracts the Server Name Indication TLS extension (SNI) field from an
14535 incoming connection made via an SSL/TLS transport layer and locally
14536 deciphered by haproxy. The result (when present) typically is a string
14537 matching the HTTPS host name (253 chars or less). The SSL library must have
14538 been built with support for TLS extensions enabled (check haproxy -vv).
14539
14540 This fetch is different from "req_ssl_sni" above in that it applies to the
14541 connection being deciphered by haproxy and not to SSL contents being blindly
14542 forwarded. See also "ssl_fc_sni_end" and "ssl_fc_sni_reg" below. This
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +020014543 requires that the SSL library is build with support for TLS extensions
14544 enabled (check haproxy -vv).
Willy Tarreau62644772008-07-16 18:36:06 +020014545
Willy Tarreau74ca5042013-06-11 23:12:07 +020014546 ACL derivatives :
Willy Tarreau74ca5042013-06-11 23:12:07 +020014547 ssl_fc_sni_end : suffix match
14548 ssl_fc_sni_reg : regex match
Emeric Brun589fcad2012-10-16 14:13:26 +020014549
Willy Tarreau74ca5042013-06-11 23:12:07 +020014550ssl_fc_use_keysize : integer
14551 Returns the symmetric cipher key size used in bits when the incoming
14552 connection was made over an SSL/TLS transport layer.
Willy Tarreaub6fb4202008-07-20 11:18:28 +020014553
Willy Tarreaub6fb4202008-07-20 11:18:28 +020014554
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200145557.3.5. Fetching samples from buffer contents (Layer 6)
Willy Tarreau74ca5042013-06-11 23:12:07 +020014556------------------------------------------------------
Willy Tarreaub6fb4202008-07-20 11:18:28 +020014557
Willy Tarreau74ca5042013-06-11 23:12:07 +020014558Fetching samples from buffer contents is a bit different from the previous
14559sample fetches above because the sampled data are ephemeral. These data can
14560only be used when they're available and will be lost when they're forwarded.
14561For this reason, samples fetched from buffer contents during a request cannot
14562be used in a response for example. Even while the data are being fetched, they
14563can change. Sometimes it is necessary to set some delays or combine multiple
14564sample fetch methods to ensure that the expected data are complete and usable,
14565for example through TCP request content inspection. Please see the "tcp-request
14566content" keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +020014567
Willy Tarreau74ca5042013-06-11 23:12:07 +020014568payload(<offset>,<length>) : binary (deprecated)
14569 This is an alias for "req.payload" when used in the context of a request (eg:
14570 "stick on", "stick match"), and for "res.payload" when used in the context of
14571 a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010014572
Willy Tarreau74ca5042013-06-11 23:12:07 +020014573payload_lv(<offset1>,<length>[,<offset2>]) : binary (deprecated)
14574 This is an alias for "req.payload_lv" when used in the context of a request
14575 (eg: "stick on", "stick match"), and for "res.payload_lv" when used in the
14576 context of a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010014577
Thierry FOURNIERd7d88812017-04-19 15:15:14 +020014578req.hdrs : string
14579 Returns the current request headers as string including the last empty line
14580 separating headers from the request body. The last empty line can be used to
14581 detect a truncated header block. This sample fetch is useful for some SPOE
14582 headers analyzers and for advanced logging.
14583
Thierry FOURNIER5617dce2017-04-09 05:38:19 +020014584req.hdrs_bin : binary
14585 Returns the current request headers contained in preparsed binary form. This
14586 is useful for offloading some processing with SPOE. Each string is described
14587 by a length followed by the number of bytes indicated in the length. The
14588 length is represented using the variable integer encoding detailed in the
14589 SPOE documentation. The end of the list is marked by a couple of empty header
14590 names and values (length of 0 for both).
14591
14592 *(<str:header-name><str:header-value>)<empty string><empty string>
14593
14594 int: refer to the SPOE documentation for the encoding
14595 str: <int:length><bytes>
14596
Willy Tarreau74ca5042013-06-11 23:12:07 +020014597req.len : integer
14598req_len : integer (deprecated)
14599 Returns an integer value corresponding to the number of bytes present in the
14600 request buffer. This is mostly used in ACL. It is important to understand
14601 that this test does not return false as long as the buffer is changing. This
14602 means that a check with equality to zero will almost always immediately match
14603 at the beginning of the session, while a test for more data will wait for
14604 that data to come in and return false only when haproxy is certain that no
14605 more data will come in. This test was designed to be used with TCP request
14606 content inspection.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020014607
Willy Tarreau74ca5042013-06-11 23:12:07 +020014608req.payload(<offset>,<length>) : binary
14609 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020014610 in the request buffer. As a special case, if the <length> argument is zero,
14611 the the whole buffer from <offset> to the end is extracted. This can be used
14612 with ACLs in order to check for the presence of some content in a buffer at
14613 any location.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020014614
Willy Tarreau74ca5042013-06-11 23:12:07 +020014615 ACL alternatives :
14616 payload(<offset>,<length>) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020014617
Willy Tarreau74ca5042013-06-11 23:12:07 +020014618req.payload_lv(<offset1>,<length>[,<offset2>]) : binary
14619 This extracts a binary block whose size is specified at <offset1> for <length>
14620 bytes, and which starts at <offset2> if specified or just after the length in
14621 the request buffer. The <offset2> parameter also supports relative offsets if
14622 prepended with a '+' or '-' sign.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020014623
Willy Tarreau74ca5042013-06-11 23:12:07 +020014624 ACL alternatives :
14625 payload_lv(<offset1>,<length>[,<offset2>]) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020014626
Willy Tarreau74ca5042013-06-11 23:12:07 +020014627 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020014628
Willy Tarreau74ca5042013-06-11 23:12:07 +020014629req.proto_http : boolean
14630req_proto_http : boolean (deprecated)
14631 Returns true when data in the request buffer look like HTTP and correctly
14632 parses as such. It is the same parser as the common HTTP request parser which
14633 is used so there should be no surprises. The test does not match until the
14634 request is complete, failed or timed out. This test may be used to report the
14635 protocol in TCP logs, but the biggest use is to block TCP request analysis
14636 until a complete HTTP request is present in the buffer, for example to track
14637 a header.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020014638
Willy Tarreau74ca5042013-06-11 23:12:07 +020014639 Example:
14640 # track request counts per "base" (concatenation of Host+URL)
14641 tcp-request inspect-delay 10s
14642 tcp-request content reject if !HTTP
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020014643 tcp-request content track-sc0 base table req-rate
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020014644
Willy Tarreau74ca5042013-06-11 23:12:07 +020014645req.rdp_cookie([<name>]) : string
14646rdp_cookie([<name>]) : string (deprecated)
14647 When the request buffer looks like the RDP protocol, extracts the RDP cookie
14648 <name>, or any cookie if unspecified. The parser only checks for the first
14649 cookie, as illustrated in the RDP protocol specification. The cookie name is
14650 case insensitive. Generally the "MSTS" cookie name will be used, as it can
14651 contain the user name of the client connecting to the server if properly
14652 configured on the client. The "MSTSHASH" cookie is often used as well for
14653 session stickiness to servers.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020014654
Willy Tarreau74ca5042013-06-11 23:12:07 +020014655 This differs from "balance rdp-cookie" in that any balancing algorithm may be
14656 used and thus the distribution of clients to backend servers is not linked to
14657 a hash of the RDP cookie. It is envisaged that using a balancing algorithm
14658 such as "balance roundrobin" or "balance leastconn" will lead to a more even
14659 distribution of clients to backend servers than the hash used by "balance
14660 rdp-cookie".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020014661
Willy Tarreau74ca5042013-06-11 23:12:07 +020014662 ACL derivatives :
14663 req_rdp_cookie([<name>]) : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020014664
Willy Tarreau74ca5042013-06-11 23:12:07 +020014665 Example :
14666 listen tse-farm
14667 bind 0.0.0.0:3389
14668 # wait up to 5s for an RDP cookie in the request
14669 tcp-request inspect-delay 5s
14670 tcp-request content accept if RDP_COOKIE
14671 # apply RDP cookie persistence
14672 persist rdp-cookie
14673 # Persist based on the mstshash cookie
14674 # This is only useful makes sense if
14675 # balance rdp-cookie is not used
14676 stick-table type string size 204800
14677 stick on req.rdp_cookie(mstshash)
14678 server srv1 1.1.1.1:3389
14679 server srv1 1.1.1.2:3389
Willy Tarreau04aa6a92012-04-06 18:57:55 +020014680
Willy Tarreau74ca5042013-06-11 23:12:07 +020014681 See also : "balance rdp-cookie", "persist rdp-cookie", "tcp-request" and the
14682 "req_rdp_cookie" ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020014683
Willy Tarreau74ca5042013-06-11 23:12:07 +020014684req.rdp_cookie_cnt([name]) : integer
14685rdp_cookie_cnt([name]) : integer (deprecated)
14686 Tries to parse the request buffer as RDP protocol, then returns an integer
14687 corresponding to the number of RDP cookies found. If an optional cookie name
14688 is passed, only cookies matching this name are considered. This is mostly
14689 used in ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020014690
Willy Tarreau74ca5042013-06-11 23:12:07 +020014691 ACL derivatives :
14692 req_rdp_cookie_cnt([<name>]) : integer match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020014693
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020014694req.ssl_ec_ext : boolean
14695 Returns a boolean identifying if client sent the Supported Elliptic Curves
14696 Extension as defined in RFC4492, section 5.1. within the SSL ClientHello
Cyril Bonté307ee1e2015-09-28 23:16:06 +020014697 message. This can be used to present ECC compatible clients with EC
14698 certificate and to use RSA for all others, on the same IP address. Note that
14699 this only applies to raw contents found in the request buffer and not to
14700 contents deciphered via an SSL data layer, so this will not work with "bind"
14701 lines having the "ssl" option.
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020014702
Willy Tarreau74ca5042013-06-11 23:12:07 +020014703req.ssl_hello_type : integer
14704req_ssl_hello_type : integer (deprecated)
14705 Returns an integer value containing the type of the SSL hello message found
14706 in the request buffer if the buffer contains data that parse as a complete
14707 SSL (v3 or superior) client hello message. Note that this only applies to raw
14708 contents found in the request buffer and not to contents deciphered via an
14709 SSL data layer, so this will not work with "bind" lines having the "ssl"
14710 option. This is mostly used in ACL to detect presence of an SSL hello message
14711 that is supposed to contain an SSL session ID usable for stickiness.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020014712
Willy Tarreau74ca5042013-06-11 23:12:07 +020014713req.ssl_sni : string
14714req_ssl_sni : string (deprecated)
14715 Returns a string containing the value of the Server Name TLS extension sent
14716 by a client in a TLS stream passing through the request buffer if the buffer
14717 contains data that parse as a complete SSL (v3 or superior) client hello
14718 message. Note that this only applies to raw contents found in the request
14719 buffer and not to contents deciphered via an SSL data layer, so this will not
14720 work with "bind" lines having the "ssl" option. SNI normally contains the
14721 name of the host the client tries to connect to (for recent browsers). SNI is
14722 useful for allowing or denying access to certain hosts when SSL/TLS is used
14723 by the client. This test was designed to be used with TCP request content
14724 inspection. If content switching is needed, it is recommended to first wait
14725 for a complete client hello (type 1), like in the example below. See also
14726 "ssl_fc_sni".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020014727
Willy Tarreau74ca5042013-06-11 23:12:07 +020014728 ACL derivatives :
14729 req_ssl_sni : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020014730
Willy Tarreau74ca5042013-06-11 23:12:07 +020014731 Examples :
14732 # Wait for a client hello for at most 5 seconds
14733 tcp-request inspect-delay 5s
14734 tcp-request content accept if { req_ssl_hello_type 1 }
14735 use_backend bk_allow if { req_ssl_sni -f allowed_sites }
14736 default_backend bk_sorry_page
Willy Tarreau04aa6a92012-04-06 18:57:55 +020014737
Pradeep Jindalbb2acf52015-09-29 10:12:57 +053014738req.ssl_st_ext : integer
14739 Returns 0 if the client didn't send a SessionTicket TLS Extension (RFC5077)
14740 Returns 1 if the client sent SessionTicket TLS Extension
14741 Returns 2 if the client also sent non-zero length TLS SessionTicket
14742 Note that this only applies to raw contents found in the request buffer and
14743 not to contents deciphered via an SSL data layer, so this will not work with
14744 "bind" lines having the "ssl" option. This can for example be used to detect
14745 whether the client sent a SessionTicket or not and stick it accordingly, if
14746 no SessionTicket then stick on SessionID or don't stick as there's no server
14747 side state is there when SessionTickets are in use.
14748
Willy Tarreau74ca5042013-06-11 23:12:07 +020014749req.ssl_ver : integer
14750req_ssl_ver : integer (deprecated)
14751 Returns an integer value containing the version of the SSL/TLS protocol of a
14752 stream present in the request buffer. Both SSLv2 hello messages and SSLv3
14753 messages are supported. TLSv1 is announced as SSL version 3.1. The value is
14754 composed of the major version multiplied by 65536, added to the minor
14755 version. Note that this only applies to raw contents found in the request
14756 buffer and not to contents deciphered via an SSL data layer, so this will not
14757 work with "bind" lines having the "ssl" option. The ACL version of the test
14758 matches against a decimal notation in the form MAJOR.MINOR (eg: 3.1). This
14759 fetch is mostly used in ACL.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014760
Willy Tarreau74ca5042013-06-11 23:12:07 +020014761 ACL derivatives :
14762 req_ssl_ver : decimal match
Willy Tarreaud63335a2010-02-26 12:56:52 +010014763
Willy Tarreau47e8eba2013-09-11 23:28:46 +020014764res.len : integer
14765 Returns an integer value corresponding to the number of bytes present in the
14766 response buffer. This is mostly used in ACL. It is important to understand
14767 that this test does not return false as long as the buffer is changing. This
14768 means that a check with equality to zero will almost always immediately match
14769 at the beginning of the session, while a test for more data will wait for
14770 that data to come in and return false only when haproxy is certain that no
14771 more data will come in. This test was designed to be used with TCP response
14772 content inspection.
14773
Willy Tarreau74ca5042013-06-11 23:12:07 +020014774res.payload(<offset>,<length>) : binary
14775 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020014776 in the response buffer. As a special case, if the <length> argument is zero,
14777 the the whole buffer from <offset> to the end is extracted. This can be used
14778 with ACLs in order to check for the presence of some content in a buffer at
14779 any location.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014780
Willy Tarreau74ca5042013-06-11 23:12:07 +020014781res.payload_lv(<offset1>,<length>[,<offset2>]) : binary
14782 This extracts a binary block whose size is specified at <offset1> for <length>
14783 bytes, and which starts at <offset2> if specified or just after the length in
14784 the response buffer. The <offset2> parameter also supports relative offsets
14785 if prepended with a '+' or '-' sign.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014786
Willy Tarreau74ca5042013-06-11 23:12:07 +020014787 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014788
Willy Tarreau971f7b62015-09-29 14:06:59 +020014789res.ssl_hello_type : integer
14790rep_ssl_hello_type : integer (deprecated)
14791 Returns an integer value containing the type of the SSL hello message found
14792 in the response buffer if the buffer contains data that parses as a complete
14793 SSL (v3 or superior) hello message. Note that this only applies to raw
14794 contents found in the response buffer and not to contents deciphered via an
14795 SSL data layer, so this will not work with "server" lines having the "ssl"
14796 option. This is mostly used in ACL to detect presence of an SSL hello message
14797 that is supposed to contain an SSL session ID usable for stickiness.
14798
Willy Tarreau74ca5042013-06-11 23:12:07 +020014799wait_end : boolean
14800 This fetch either returns true when the inspection period is over, or does
14801 not fetch. It is only used in ACLs, in conjunction with content analysis to
14802 avoid returning a wrong verdict early. It may also be used to delay some
14803 actions, such as a delayed reject for some special addresses. Since it either
14804 stops the rules evaluation or immediately returns true, it is recommended to
14805 use this acl as the last one in a rule. Please note that the default ACL
14806 "WAIT_END" is always usable without prior declaration. This test was designed
14807 to be used with TCP request content inspection.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014808
Willy Tarreau74ca5042013-06-11 23:12:07 +020014809 Examples :
14810 # delay every incoming request by 2 seconds
14811 tcp-request inspect-delay 2s
14812 tcp-request content accept if WAIT_END
Willy Tarreaud63335a2010-02-26 12:56:52 +010014813
Willy Tarreau74ca5042013-06-11 23:12:07 +020014814 # don't immediately tell bad guys they are rejected
14815 tcp-request inspect-delay 10s
14816 acl goodguys src 10.0.0.0/24
14817 acl badguys src 10.0.1.0/24
14818 tcp-request content accept if goodguys
14819 tcp-request content reject if badguys WAIT_END
14820 tcp-request content reject
14821
14822
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200148237.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +020014824--------------------------------------
14825
14826It is possible to fetch samples from HTTP contents, requests and responses.
14827This application layer is also called layer 7. It is only possible to fetch the
14828data in this section when a full HTTP request or response has been parsed from
14829its respective request or response buffer. This is always the case with all
14830HTTP specific rules and for sections running with "mode http". When using TCP
14831content inspection, it may be necessary to support an inspection delay in order
14832to let the request or response come in first. These fetches may require a bit
14833more CPU resources than the layer 4 ones, but not much since the request and
14834response are indexed.
14835
14836base : string
14837 This returns the concatenation of the first Host header and the path part of
14838 the request, which starts at the first slash and ends before the question
14839 mark. It can be useful in virtual hosted environments to detect URL abuses as
14840 well as to improve shared caches efficiency. Using this with a limited size
14841 stick table also allows one to collect statistics about most commonly
14842 requested objects by host/path. With ACLs it can allow simple content
14843 switching rules involving the host and the path at the same time, such as
14844 "www.example.com/favicon.ico". See also "path" and "uri".
14845
14846 ACL derivatives :
14847 base : exact string match
14848 base_beg : prefix match
14849 base_dir : subdir match
14850 base_dom : domain match
14851 base_end : suffix match
14852 base_len : length match
14853 base_reg : regex match
14854 base_sub : substring match
14855
14856base32 : integer
14857 This returns a 32-bit hash of the value returned by the "base" fetch method
14858 above. This is useful to track per-URL activity on high traffic sites without
14859 having to store all URLs. Instead a shorter hash is stored, saving a lot of
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020014860 memory. The output type is an unsigned integer. The hash function used is
14861 SDBM with full avalanche on the output. Technically, base32 is exactly equal
14862 to "base,sdbm(1)".
Willy Tarreau74ca5042013-06-11 23:12:07 +020014863
14864base32+src : binary
14865 This returns the concatenation of the base32 fetch above and the src fetch
14866 below. The resulting type is of type binary, with a size of 8 or 20 bytes
14867 depending on the source address family. This can be used to track per-IP,
14868 per-URL counters.
14869
William Lallemand65ad6e12014-01-31 15:08:02 +010014870capture.req.hdr(<idx>) : string
14871 This extracts the content of the header captured by the "capture request
14872 header", idx is the position of the capture keyword in the configuration.
14873 The first entry is an index of 0. See also: "capture request header".
14874
14875capture.req.method : string
14876 This extracts the METHOD of an HTTP request. It can be used in both request
14877 and response. Unlike "method", it can be used in both request and response
14878 because it's allocated.
14879
14880capture.req.uri : string
14881 This extracts the request's URI, which starts at the first slash and ends
14882 before the first space in the request (without the host part). Unlike "path"
14883 and "url", it can be used in both request and response because it's
14884 allocated.
14885
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020014886capture.req.ver : string
14887 This extracts the request's HTTP version and returns either "HTTP/1.0" or
14888 "HTTP/1.1". Unlike "req.ver", it can be used in both request, response, and
14889 logs because it relies on a persistent flag.
14890
William Lallemand65ad6e12014-01-31 15:08:02 +010014891capture.res.hdr(<idx>) : string
14892 This extracts the content of the header captured by the "capture response
14893 header", idx is the position of the capture keyword in the configuration.
14894 The first entry is an index of 0.
14895 See also: "capture response header"
14896
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020014897capture.res.ver : string
14898 This extracts the response's HTTP version and returns either "HTTP/1.0" or
14899 "HTTP/1.1". Unlike "res.ver", it can be used in logs because it relies on a
14900 persistent flag.
14901
Willy Tarreaua5910cc2015-05-02 00:46:08 +020014902req.body : binary
14903 This returns the HTTP request's available body as a block of data. It
14904 requires that the request body has been buffered made available using
14905 "option http-buffer-request". In case of chunked-encoded body, currently only
14906 the first chunk is analyzed.
14907
Thierry FOURNIER9826c772015-05-20 15:50:54 +020014908req.body_param([<name>) : string
14909 This fetch assumes that the body of the POST request is url-encoded. The user
14910 can check if the "content-type" contains the value
14911 "application/x-www-form-urlencoded". This extracts the first occurrence of the
14912 parameter <name> in the body, which ends before '&'. The parameter name is
14913 case-sensitive. If no name is given, any parameter will match, and the first
14914 one will be returned. The result is a string corresponding to the value of the
14915 parameter <name> as presented in the request body (no URL decoding is
14916 performed). Note that the ACL version of this fetch iterates over multiple
14917 parameters and will iteratively report all parameters values if no name is
14918 given.
14919
Willy Tarreaua5910cc2015-05-02 00:46:08 +020014920req.body_len : integer
14921 This returns the length of the HTTP request's available body in bytes. It may
14922 be lower than the advertised length if the body is larger than the buffer. It
14923 requires that the request body has been buffered made available using
14924 "option http-buffer-request".
14925
14926req.body_size : integer
14927 This returns the advertised length of the HTTP request's body in bytes. It
14928 will represent the advertised Content-Length header, or the size of the first
14929 chunk in case of chunked encoding. In order to parse the chunks, it requires
14930 that the request body has been buffered made available using
14931 "option http-buffer-request".
14932
Willy Tarreau74ca5042013-06-11 23:12:07 +020014933req.cook([<name>]) : string
14934cook([<name>]) : string (deprecated)
14935 This extracts the last occurrence of the cookie name <name> on a "Cookie"
14936 header line from the request, and returns its value as string. If no name is
14937 specified, the first cookie value is returned. When used with ACLs, all
14938 matching cookies are evaluated. Spaces around the name and the value are
14939 ignored as requested by the Cookie header specification (RFC6265). The cookie
14940 name is case-sensitive. Empty cookies are valid, so an empty cookie may very
14941 well return an empty value if it is present. Use the "found" match to detect
14942 presence. Use the res.cook() variant for response cookies sent by the server.
14943
14944 ACL derivatives :
14945 cook([<name>]) : exact string match
14946 cook_beg([<name>]) : prefix match
14947 cook_dir([<name>]) : subdir match
14948 cook_dom([<name>]) : domain match
14949 cook_end([<name>]) : suffix match
14950 cook_len([<name>]) : length match
14951 cook_reg([<name>]) : regex match
14952 cook_sub([<name>]) : substring match
Willy Tarreaud63335a2010-02-26 12:56:52 +010014953
Willy Tarreau74ca5042013-06-11 23:12:07 +020014954req.cook_cnt([<name>]) : integer
14955cook_cnt([<name>]) : integer (deprecated)
14956 Returns an integer value representing the number of occurrences of the cookie
14957 <name> in the request, or all cookies if <name> is not specified.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014958
Willy Tarreau74ca5042013-06-11 23:12:07 +020014959req.cook_val([<name>]) : integer
14960cook_val([<name>]) : integer (deprecated)
14961 This extracts the last occurrence of the cookie name <name> on a "Cookie"
14962 header line from the request, and converts its value to an integer which is
14963 returned. If no name is specified, the first cookie value is returned. When
14964 used in ACLs, all matching names are iterated over until a value matches.
Willy Tarreau0e698542011-09-16 08:32:32 +020014965
Willy Tarreau74ca5042013-06-11 23:12:07 +020014966cookie([<name>]) : string (deprecated)
14967 This extracts the last occurrence of the cookie name <name> on a "Cookie"
14968 header line from the request, or a "Set-Cookie" header from the response, and
14969 returns its value as a string. A typical use is to get multiple clients
14970 sharing a same profile use the same server. This can be similar to what
Willy Tarreau294d0f02015-08-10 19:40:12 +020014971 "appsession" did with the "request-learn" statement, but with support for
Willy Tarreau74ca5042013-06-11 23:12:07 +020014972 multi-peer synchronization and state keeping across restarts. If no name is
14973 specified, the first cookie value is returned. This fetch should not be used
14974 anymore and should be replaced by req.cook() or res.cook() instead as it
14975 ambiguously uses the direction based on the context where it is used.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014976
Willy Tarreau74ca5042013-06-11 23:12:07 +020014977hdr([<name>[,<occ>]]) : string
14978 This is equivalent to req.hdr() when used on requests, and to res.hdr() when
14979 used on responses. Please refer to these respective fetches for more details.
14980 In case of doubt about the fetch direction, please use the explicit ones.
14981 Note that contrary to the hdr() sample fetch method, the hdr_* ACL keywords
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014982 unambiguously apply to the request headers.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014983
Willy Tarreau74ca5042013-06-11 23:12:07 +020014984req.fhdr(<name>[,<occ>]) : string
14985 This extracts the last occurrence of header <name> in an HTTP request. When
14986 used from an ACL, all occurrences are iterated over until a match is found.
14987 Optionally, a specific occurrence might be specified as a position number.
14988 Positive values indicate a position from the first occurrence, with 1 being
14989 the first one. Negative values indicate positions relative to the last one,
14990 with -1 being the last one. It differs from req.hdr() in that any commas
14991 present in the value are returned and are not used as delimiters. This is
14992 sometimes useful with headers such as User-Agent.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014993
Willy Tarreau74ca5042013-06-11 23:12:07 +020014994req.fhdr_cnt([<name>]) : integer
14995 Returns an integer value representing the number of occurrences of request
14996 header field name <name>, or the total number of header fields if <name> is
14997 not specified. Contrary to its req.hdr_cnt() cousin, this function returns
14998 the number of full line headers and does not stop on commas.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014999
Willy Tarreau74ca5042013-06-11 23:12:07 +020015000req.hdr([<name>[,<occ>]]) : string
15001 This extracts the last occurrence of header <name> in an HTTP request. When
15002 used from an ACL, all occurrences are iterated over until a match is found.
15003 Optionally, a specific occurrence might be specified as a position number.
15004 Positive values indicate a position from the first occurrence, with 1 being
15005 the first one. Negative values indicate positions relative to the last one,
15006 with -1 being the last one. A typical use is with the X-Forwarded-For header
15007 once converted to IP, associated with an IP stick-table. The function
15008 considers any comma as a delimiter for distinct values. If full-line headers
Lukas Tribus23953682017-04-28 13:24:30 +000015009 are desired instead, use req.fhdr(). Please carefully check RFC7231 to know
Willy Tarreau74ca5042013-06-11 23:12:07 +020015010 how certain headers are supposed to be parsed. Also, some of them are case
15011 insensitive (eg: Connection).
Willy Tarreaud63335a2010-02-26 12:56:52 +010015012
Willy Tarreau74ca5042013-06-11 23:12:07 +020015013 ACL derivatives :
15014 hdr([<name>[,<occ>]]) : exact string match
15015 hdr_beg([<name>[,<occ>]]) : prefix match
15016 hdr_dir([<name>[,<occ>]]) : subdir match
15017 hdr_dom([<name>[,<occ>]]) : domain match
15018 hdr_end([<name>[,<occ>]]) : suffix match
15019 hdr_len([<name>[,<occ>]]) : length match
15020 hdr_reg([<name>[,<occ>]]) : regex match
15021 hdr_sub([<name>[,<occ>]]) : substring match
15022
15023req.hdr_cnt([<name>]) : integer
15024hdr_cnt([<header>]) : integer (deprecated)
15025 Returns an integer value representing the number of occurrences of request
15026 header field name <name>, or the total number of header field values if
15027 <name> is not specified. It is important to remember that one header line may
15028 count as several headers if it has several values. The function considers any
15029 comma as a delimiter for distinct values. If full-line headers are desired
15030 instead, req.fhdr_cnt() should be used instead. With ACLs, it can be used to
15031 detect presence, absence or abuse of a specific header, as well as to block
15032 request smuggling attacks by rejecting requests which contain more than one
15033 of certain headers. See "req.hdr" for more information on header matching.
15034
15035req.hdr_ip([<name>[,<occ>]]) : ip
15036hdr_ip([<name>[,<occ>]]) : ip (deprecated)
15037 This extracts the last occurrence of header <name> in an HTTP request,
15038 converts it to an IPv4 or IPv6 address and returns this address. When used
15039 with ACLs, all occurrences are checked, and if <name> is omitted, every value
15040 of every header is checked. Optionally, a specific occurrence might be
15041 specified as a position number. Positive values indicate a position from the
15042 first occurrence, with 1 being the first one. Negative values indicate
15043 positions relative to the last one, with -1 being the last one. A typical use
15044 is with the X-Forwarded-For and X-Client-IP headers.
15045
15046req.hdr_val([<name>[,<occ>]]) : integer
15047hdr_val([<name>[,<occ>]]) : integer (deprecated)
15048 This extracts the last occurrence of header <name> in an HTTP request, and
15049 converts it to an integer value. When used with ACLs, all occurrences are
15050 checked, and if <name> is omitted, every value of every header is checked.
15051 Optionally, a specific occurrence might be specified as a position number.
15052 Positive values indicate a position from the first occurrence, with 1 being
15053 the first one. Negative values indicate positions relative to the last one,
15054 with -1 being the last one. A typical use is with the X-Forwarded-For header.
15055
15056http_auth(<userlist>) : boolean
15057 Returns a boolean indicating whether the authentication data received from
15058 the client match a username & password stored in the specified userlist. This
15059 fetch function is not really useful outside of ACLs. Currently only http
15060 basic auth is supported.
15061
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010015062http_auth_group(<userlist>) : string
15063 Returns a string corresponding to the user name found in the authentication
15064 data received from the client if both the user name and password are valid
15065 according to the specified userlist. The main purpose is to use it in ACLs
15066 where it is then checked whether the user belongs to any group within a list.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015067 This fetch function is not really useful outside of ACLs. Currently only http
15068 basic auth is supported.
15069
15070 ACL derivatives :
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010015071 http_auth_group(<userlist>) : group ...
15072 Returns true when the user extracted from the request and whose password is
15073 valid according to the specified userlist belongs to at least one of the
15074 groups.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015075
15076http_first_req : boolean
Willy Tarreau7f18e522010-10-22 20:04:13 +020015077 Returns true when the request being processed is the first one of the
15078 connection. This can be used to add or remove headers that may be missing
Willy Tarreau74ca5042013-06-11 23:12:07 +020015079 from some requests when a request is not the first one, or to help grouping
15080 requests in the logs.
Willy Tarreau7f18e522010-10-22 20:04:13 +020015081
Willy Tarreau74ca5042013-06-11 23:12:07 +020015082method : integer + string
15083 Returns an integer value corresponding to the method in the HTTP request. For
15084 example, "GET" equals 1 (check sources to establish the matching). Value 9
15085 means "other method" and may be converted to a string extracted from the
15086 stream. This should not be used directly as a sample, this is only meant to
15087 be used from ACLs, which transparently convert methods from patterns to these
15088 integer + string values. Some predefined ACL already check for most common
15089 methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015090
Willy Tarreau74ca5042013-06-11 23:12:07 +020015091 ACL derivatives :
15092 method : case insensitive method match
Willy Tarreau6a06a402007-07-15 20:15:28 +020015093
Willy Tarreau74ca5042013-06-11 23:12:07 +020015094 Example :
15095 # only accept GET and HEAD requests
15096 acl valid_method method GET HEAD
15097 http-request deny if ! valid_method
Willy Tarreau6a06a402007-07-15 20:15:28 +020015098
Willy Tarreau74ca5042013-06-11 23:12:07 +020015099path : string
15100 This extracts the request's URL path, which starts at the first slash and
15101 ends before the question mark (without the host part). A typical use is with
15102 prefetch-capable caches, and with portals which need to aggregate multiple
15103 information from databases and keep them in caches. Note that with outgoing
15104 caches, it would be wiser to use "url" instead. With ACLs, it's typically
15105 used to match exact file names (eg: "/login.php"), or directory parts using
15106 the derivative forms. See also the "url" and "base" fetch methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015107
Willy Tarreau74ca5042013-06-11 23:12:07 +020015108 ACL derivatives :
15109 path : exact string match
15110 path_beg : prefix match
15111 path_dir : subdir match
15112 path_dom : domain match
15113 path_end : suffix match
15114 path_len : length match
15115 path_reg : regex match
15116 path_sub : substring match
Willy Tarreau6a06a402007-07-15 20:15:28 +020015117
Willy Tarreau49ad95c2015-01-19 15:06:26 +010015118query : string
15119 This extracts the request's query string, which starts after the first
15120 question mark. If no question mark is present, this fetch returns nothing. If
15121 a question mark is present but nothing follows, it returns an empty string.
15122 This means it's possible to easily know whether a query string is present
Tim Düsterhus4896c442016-11-29 02:15:19 +010015123 using the "found" matching method. This fetch is the complement of "path"
Willy Tarreau49ad95c2015-01-19 15:06:26 +010015124 which stops before the question mark.
15125
Willy Tarreaueb27ec72015-02-20 13:55:29 +010015126req.hdr_names([<delim>]) : string
15127 This builds a string made from the concatenation of all header names as they
15128 appear in the request when the rule is evaluated. The default delimiter is
15129 the comma (',') but it may be overridden as an optional argument <delim>. In
15130 this case, only the first character of <delim> is considered.
15131
Willy Tarreau74ca5042013-06-11 23:12:07 +020015132req.ver : string
15133req_ver : string (deprecated)
15134 Returns the version string from the HTTP request, for example "1.1". This can
15135 be useful for logs, but is mostly there for ACL. Some predefined ACL already
15136 check for versions 1.0 and 1.1.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015137
Willy Tarreau74ca5042013-06-11 23:12:07 +020015138 ACL derivatives :
15139 req_ver : exact string match
Willy Tarreau0e698542011-09-16 08:32:32 +020015140
Willy Tarreau74ca5042013-06-11 23:12:07 +020015141res.comp : boolean
15142 Returns the boolean "true" value if the response has been compressed by
15143 HAProxy, otherwise returns boolean "false". This may be used to add
15144 information in the logs.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015145
Willy Tarreau74ca5042013-06-11 23:12:07 +020015146res.comp_algo : string
15147 Returns a string containing the name of the algorithm used if the response
15148 was compressed by HAProxy, for example : "deflate". This may be used to add
15149 some information in the logs.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015150
Willy Tarreau74ca5042013-06-11 23:12:07 +020015151res.cook([<name>]) : string
15152scook([<name>]) : string (deprecated)
15153 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
15154 header line from the response, and returns its value as string. If no name is
15155 specified, the first cookie value is returned.
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020015156
Willy Tarreau74ca5042013-06-11 23:12:07 +020015157 ACL derivatives :
15158 scook([<name>] : exact string match
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020015159
Willy Tarreau74ca5042013-06-11 23:12:07 +020015160res.cook_cnt([<name>]) : integer
15161scook_cnt([<name>]) : integer (deprecated)
15162 Returns an integer value representing the number of occurrences of the cookie
15163 <name> in the response, or all cookies if <name> is not specified. This is
15164 mostly useful when combined with ACLs to detect suspicious responses.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015165
Willy Tarreau74ca5042013-06-11 23:12:07 +020015166res.cook_val([<name>]) : integer
15167scook_val([<name>]) : integer (deprecated)
15168 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
15169 header line from the response, and converts its value to an integer which is
15170 returned. If no name is specified, the first cookie value is returned.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015171
Willy Tarreau74ca5042013-06-11 23:12:07 +020015172res.fhdr([<name>[,<occ>]]) : string
15173 This extracts the last occurrence of header <name> in an HTTP response, or of
15174 the last header if no <name> is specified. Optionally, a specific occurrence
15175 might be specified as a position number. Positive values indicate a position
15176 from the first occurrence, with 1 being the first one. Negative values
15177 indicate positions relative to the last one, with -1 being the last one. It
15178 differs from res.hdr() in that any commas present in the value are returned
15179 and are not used as delimiters. If this is not desired, the res.hdr() fetch
15180 should be used instead. This is sometimes useful with headers such as Date or
15181 Expires.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015182
Willy Tarreau74ca5042013-06-11 23:12:07 +020015183res.fhdr_cnt([<name>]) : integer
15184 Returns an integer value representing the number of occurrences of response
15185 header field name <name>, or the total number of header fields if <name> is
15186 not specified. Contrary to its res.hdr_cnt() cousin, this function returns
15187 the number of full line headers and does not stop on commas. If this is not
15188 desired, the res.hdr_cnt() fetch should be used instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015189
Willy Tarreau74ca5042013-06-11 23:12:07 +020015190res.hdr([<name>[,<occ>]]) : string
15191shdr([<name>[,<occ>]]) : string (deprecated)
15192 This extracts the last occurrence of header <name> in an HTTP response, or of
15193 the last header if no <name> is specified. Optionally, a specific occurrence
15194 might be specified as a position number. Positive values indicate a position
15195 from the first occurrence, with 1 being the first one. Negative values
15196 indicate positions relative to the last one, with -1 being the last one. This
15197 can be useful to learn some data into a stick-table. The function considers
15198 any comma as a delimiter for distinct values. If this is not desired, the
15199 res.fhdr() fetch should be used instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015200
Willy Tarreau74ca5042013-06-11 23:12:07 +020015201 ACL derivatives :
15202 shdr([<name>[,<occ>]]) : exact string match
15203 shdr_beg([<name>[,<occ>]]) : prefix match
15204 shdr_dir([<name>[,<occ>]]) : subdir match
15205 shdr_dom([<name>[,<occ>]]) : domain match
15206 shdr_end([<name>[,<occ>]]) : suffix match
15207 shdr_len([<name>[,<occ>]]) : length match
15208 shdr_reg([<name>[,<occ>]]) : regex match
15209 shdr_sub([<name>[,<occ>]]) : substring match
15210
15211res.hdr_cnt([<name>]) : integer
15212shdr_cnt([<name>]) : integer (deprecated)
15213 Returns an integer value representing the number of occurrences of response
15214 header field name <name>, or the total number of header fields if <name> is
15215 not specified. The function considers any comma as a delimiter for distinct
15216 values. If this is not desired, the res.fhdr_cnt() fetch should be used
15217 instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015218
Willy Tarreau74ca5042013-06-11 23:12:07 +020015219res.hdr_ip([<name>[,<occ>]]) : ip
15220shdr_ip([<name>[,<occ>]]) : ip (deprecated)
15221 This extracts the last occurrence of header <name> in an HTTP response,
15222 convert it to an IPv4 or IPv6 address and returns this address. Optionally, a
15223 specific occurrence might be specified as a position number. Positive values
15224 indicate a position from the first occurrence, with 1 being the first one.
15225 Negative values indicate positions relative to the last one, with -1 being
15226 the last one. This can be useful to learn some data into a stick table.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015227
Willy Tarreaueb27ec72015-02-20 13:55:29 +010015228res.hdr_names([<delim>]) : string
15229 This builds a string made from the concatenation of all header names as they
15230 appear in the response when the rule is evaluated. The default delimiter is
15231 the comma (',') but it may be overridden as an optional argument <delim>. In
15232 this case, only the first character of <delim> is considered.
15233
Willy Tarreau74ca5042013-06-11 23:12:07 +020015234res.hdr_val([<name>[,<occ>]]) : integer
15235shdr_val([<name>[,<occ>]]) : integer (deprecated)
15236 This extracts the last occurrence of header <name> in an HTTP response, and
15237 converts it to an integer value. Optionally, a specific occurrence might be
15238 specified as a position number. Positive values indicate a position from the
15239 first occurrence, with 1 being the first one. Negative values indicate
15240 positions relative to the last one, with -1 being the last one. This can be
15241 useful to learn some data into a stick table.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010015242
Willy Tarreau74ca5042013-06-11 23:12:07 +020015243res.ver : string
15244resp_ver : string (deprecated)
15245 Returns the version string from the HTTP response, for example "1.1". This
15246 can be useful for logs, but is mostly there for ACL.
Willy Tarreau0e698542011-09-16 08:32:32 +020015247
Willy Tarreau74ca5042013-06-11 23:12:07 +020015248 ACL derivatives :
15249 resp_ver : exact string match
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010015250
Willy Tarreau74ca5042013-06-11 23:12:07 +020015251set-cookie([<name>]) : string (deprecated)
15252 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
15253 header line from the response and uses the corresponding value to match. This
Willy Tarreau294d0f02015-08-10 19:40:12 +020015254 can be comparable to what "appsession" did with default options, but with
Willy Tarreau74ca5042013-06-11 23:12:07 +020015255 support for multi-peer synchronization and state keeping across restarts.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010015256
Willy Tarreau74ca5042013-06-11 23:12:07 +020015257 This fetch function is deprecated and has been superseded by the "res.cook"
15258 fetch. This keyword will disappear soon.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010015259
Willy Tarreau74ca5042013-06-11 23:12:07 +020015260status : integer
15261 Returns an integer containing the HTTP status code in the HTTP response, for
15262 example, 302. It is mostly used within ACLs and integer ranges, for example,
15263 to remove any Location header if the response is not a 3xx.
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015264
Thierry Fournier0e00dca2016-04-07 15:47:40 +020015265unique-id : string
15266 Returns the unique-id attached to the request. The directive
15267 "unique-id-format" must be set. If it is not set, the unique-id sample fetch
15268 fails. Note that the unique-id is usually used with HTTP requests, however this
15269 sample fetch can be used with other protocols. Obviously, if it is used with
15270 other protocols than HTTP, the unique-id-format directive must not contain
15271 HTTP parts. See: unique-id-format and unique-id-header
15272
Willy Tarreau74ca5042013-06-11 23:12:07 +020015273url : string
15274 This extracts the request's URL as presented in the request. A typical use is
15275 with prefetch-capable caches, and with portals which need to aggregate
15276 multiple information from databases and keep them in caches. With ACLs, using
15277 "path" is preferred over using "url", because clients may send a full URL as
15278 is normally done with proxies. The only real use is to match "*" which does
15279 not match in "path", and for which there is already a predefined ACL. See
15280 also "path" and "base".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015281
Willy Tarreau74ca5042013-06-11 23:12:07 +020015282 ACL derivatives :
15283 url : exact string match
15284 url_beg : prefix match
15285 url_dir : subdir match
15286 url_dom : domain match
15287 url_end : suffix match
15288 url_len : length match
15289 url_reg : regex match
15290 url_sub : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015291
Willy Tarreau74ca5042013-06-11 23:12:07 +020015292url_ip : ip
15293 This extracts the IP address from the request's URL when the host part is
15294 presented as an IP address. Its use is very limited. For instance, a
15295 monitoring system might use this field as an alternative for the source IP in
15296 order to test what path a given source address would follow, or to force an
15297 entry in a table for a given source address. With ACLs it can be used to
15298 restrict access to certain systems through a proxy, for example when combined
15299 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015300
Willy Tarreau74ca5042013-06-11 23:12:07 +020015301url_port : integer
15302 This extracts the port part from the request's URL. Note that if the port is
15303 not specified in the request, port 80 is assumed. With ACLs it can be used to
15304 restrict access to certain systems through a proxy, for example when combined
15305 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015306
Willy Tarreau1ede1da2015-05-07 16:06:18 +020015307urlp([<name>[,<delim>]]) : string
15308url_param([<name>[,<delim>]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020015309 This extracts the first occurrence of the parameter <name> in the query
15310 string, which begins after either '?' or <delim>, and which ends before '&',
Willy Tarreau1ede1da2015-05-07 16:06:18 +020015311 ';' or <delim>. The parameter name is case-sensitive. If no name is given,
15312 any parameter will match, and the first one will be returned. The result is
15313 a string corresponding to the value of the parameter <name> as presented in
15314 the request (no URL decoding is performed). This can be used for session
Willy Tarreau74ca5042013-06-11 23:12:07 +020015315 stickiness based on a client ID, to extract an application cookie passed as a
15316 URL parameter, or in ACLs to apply some checks. Note that the ACL version of
Willy Tarreau1ede1da2015-05-07 16:06:18 +020015317 this fetch iterates over multiple parameters and will iteratively report all
15318 parameters values if no name is given
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015319
Willy Tarreau74ca5042013-06-11 23:12:07 +020015320 ACL derivatives :
15321 urlp(<name>[,<delim>]) : exact string match
15322 urlp_beg(<name>[,<delim>]) : prefix match
15323 urlp_dir(<name>[,<delim>]) : subdir match
15324 urlp_dom(<name>[,<delim>]) : domain match
15325 urlp_end(<name>[,<delim>]) : suffix match
15326 urlp_len(<name>[,<delim>]) : length match
15327 urlp_reg(<name>[,<delim>]) : regex match
15328 urlp_sub(<name>[,<delim>]) : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015329
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015330
Willy Tarreau74ca5042013-06-11 23:12:07 +020015331 Example :
15332 # match http://example.com/foo?PHPSESSIONID=some_id
15333 stick on urlp(PHPSESSIONID)
15334 # match http://example.com/foo;JSESSIONID=some_id
15335 stick on urlp(JSESSIONID,;)
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020015336
Jarno Huuskonen676f6222017-03-30 09:19:45 +030015337urlp_val([<name>[,<delim>]]) : integer
Willy Tarreau74ca5042013-06-11 23:12:07 +020015338 See "urlp" above. This one extracts the URL parameter <name> in the request
15339 and converts it to an integer value. This can be used for session stickiness
15340 based on a user ID for example, or with ACLs to match a page number or price.
Willy Tarreaua9fddca2012-07-31 07:51:48 +020015341
Dragan Dosen0070cd52016-06-16 12:19:49 +020015342url32 : integer
15343 This returns a 32-bit hash of the value obtained by concatenating the first
15344 Host header and the whole URL including parameters (not only the path part of
15345 the request, as in the "base32" fetch above). This is useful to track per-URL
15346 activity. A shorter hash is stored, saving a lot of memory. The output type
15347 is an unsigned integer.
15348
15349url32+src : binary
15350 This returns the concatenation of the "url32" fetch and the "src" fetch. The
15351 resulting type is of type binary, with a size of 8 or 20 bytes depending on
15352 the source address family. This can be used to track per-IP, per-URL counters.
15353
Willy Tarreau198a7442008-01-17 12:05:32 +010015354
Willy Tarreau74ca5042013-06-11 23:12:07 +0200153557.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015356---------------------
Willy Tarreauced27012008-01-17 20:35:34 +010015357
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015358Some predefined ACLs are hard-coded so that they do not have to be declared in
15359every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +020015360order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +010015361
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015362ACL name Equivalent to Usage
15363---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015364FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +020015365HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015366HTTP_1.0 req_ver 1.0 match HTTP version 1.0
15367HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +010015368HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
15369HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
15370HTTP_URL_SLASH url_beg / match URL beginning with "/"
15371HTTP_URL_STAR url * match URL equal to "*"
15372LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015373METH_CONNECT method CONNECT match HTTP CONNECT method
Daniel Schneller9ff96c72016-04-11 17:45:29 +020015374METH_DELETE method DELETE match HTTP DELETE method
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015375METH_GET method GET HEAD match HTTP GET or HEAD method
15376METH_HEAD method HEAD match HTTP HEAD method
15377METH_OPTIONS method OPTIONS match HTTP OPTIONS method
15378METH_POST method POST match HTTP POST method
Daniel Schneller9ff96c72016-04-11 17:45:29 +020015379METH_PUT method PUT match HTTP PUT method
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015380METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +020015381RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015382REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +010015383TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015384WAIT_END wait_end wait for end of content analysis
15385---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +010015386
Willy Tarreaub937b7e2010-01-12 15:27:54 +010015387
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200153888. Logging
15389----------
Willy Tarreau844e3c52008-01-11 16:28:18 +010015390
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015391One of HAProxy's strong points certainly lies is its precise logs. It probably
15392provides the finest level of information available for such a product, which is
15393very important for troubleshooting complex environments. Standard information
15394provided in logs include client ports, TCP/HTTP state timers, precise session
15395state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010015396to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015397headers.
15398
15399In order to improve administrators reactivity, it offers a great transparency
15400about encountered problems, both internal and external, and it is possible to
15401send logs to different sources at the same time with different level filters :
15402
15403 - global process-level logs (system errors, start/stop, etc..)
15404 - per-instance system and internal errors (lack of resource, bugs, ...)
15405 - per-instance external troubles (servers up/down, max connections)
15406 - per-instance activity (client connections), either at the establishment or
15407 at the termination.
Jim Freeman9e8714b2015-05-26 09:16:34 -060015408 - per-request control of log-level, eg:
15409 http-request set-log-level silent if sensitive_request
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015410
15411The ability to distribute different levels of logs to different log servers
15412allow several production teams to interact and to fix their problems as soon
15413as possible. For example, the system team might monitor system-wide errors,
15414while the application team might be monitoring the up/down for their servers in
15415real time, and the security team might analyze the activity logs with one hour
15416delay.
15417
15418
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200154198.1. Log levels
15420---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015421
Simon Hormandf791f52011-05-29 15:01:10 +090015422TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015423source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +090015424HTTP request, HTTP return code, number of bytes transmitted, conditions
15425in which the session ended, and even exchanged cookies values. For example
15426track a particular user's problems. All messages may be sent to up to two
15427syslog servers. Check the "log" keyword in section 4.2 for more information
15428about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015429
15430
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200154318.2. Log formats
15432----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015433
William Lallemand48940402012-01-30 16:47:22 +010015434HAProxy supports 5 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +090015435and will be detailed in the following sections. A few of them may vary
15436slightly with the configuration, due to indicators specific to certain
15437options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015438
15439 - the default format, which is very basic and very rarely used. It only
15440 provides very basic information about the incoming connection at the moment
15441 it is accepted : source IP:port, destination IP:port, and frontend-name.
15442 This mode will eventually disappear so it will not be described to great
15443 extents.
15444
15445 - the TCP format, which is more advanced. This format is enabled when "option
15446 tcplog" is set on the frontend. HAProxy will then usually wait for the
15447 connection to terminate before logging. This format provides much richer
15448 information, such as timers, connection counts, queue size, etc... This
15449 format is recommended for pure TCP proxies.
15450
15451 - the HTTP format, which is the most advanced for HTTP proxying. This format
15452 is enabled when "option httplog" is set on the frontend. It provides the
15453 same information as the TCP format with some HTTP-specific fields such as
15454 the request, the status code, and captures of headers and cookies. This
15455 format is recommended for HTTP proxies.
15456
Emeric Brun3a058f32009-06-30 18:26:00 +020015457 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
15458 fields arranged in the same order as the CLF format. In this mode, all
15459 timers, captures, flags, etc... appear one per field after the end of the
15460 common fields, in the same order they appear in the standard HTTP format.
15461
William Lallemand48940402012-01-30 16:47:22 +010015462 - the custom log format, allows you to make your own log line.
15463
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015464Next sections will go deeper into details for each of these formats. Format
15465specification will be performed on a "field" basis. Unless stated otherwise, a
15466field is a portion of text delimited by any number of spaces. Since syslog
15467servers are susceptible of inserting fields at the beginning of a line, it is
15468always assumed that the first field is the one containing the process name and
15469identifier.
15470
15471Note : Since log lines may be quite long, the log examples in sections below
15472 might be broken into multiple lines. The example log lines will be
15473 prefixed with 3 closing angle brackets ('>>>') and each time a log is
15474 broken into multiple lines, each non-final line will end with a
15475 backslash ('\') and the next line will start indented by two characters.
15476
15477
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200154788.2.1. Default log format
15479-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015480
15481This format is used when no specific option is set. The log is emitted as soon
15482as the connection is accepted. One should note that this currently is the only
15483format which logs the request's destination IP and ports.
15484
15485 Example :
15486 listen www
15487 mode http
15488 log global
15489 server srv1 127.0.0.1:8000
15490
15491 >>> Feb 6 12:12:09 localhost \
15492 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
15493 (www/HTTP)
15494
15495 Field Format Extract from the example above
15496 1 process_name '[' pid ']:' haproxy[14385]:
15497 2 'Connect from' Connect from
15498 3 source_ip ':' source_port 10.0.1.2:33312
15499 4 'to' to
15500 5 destination_ip ':' destination_port 10.0.3.31:8012
15501 6 '(' frontend_name '/' mode ')' (www/HTTP)
15502
15503Detailed fields description :
15504 - "source_ip" is the IP address of the client which initiated the connection.
15505 - "source_port" is the TCP port of the client which initiated the connection.
15506 - "destination_ip" is the IP address the client connected to.
15507 - "destination_port" is the TCP port the client connected to.
15508 - "frontend_name" is the name of the frontend (or listener) which received
15509 and processed the connection.
15510 - "mode is the mode the frontend is operating (TCP or HTTP).
15511
Willy Tarreauceb24bc2010-11-09 12:46:41 +010015512In case of a UNIX socket, the source and destination addresses are marked as
15513"unix:" and the ports reflect the internal ID of the socket which accepted the
15514connection (the same ID as reported in the stats).
15515
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015516It is advised not to use this deprecated format for newer installations as it
15517will eventually disappear.
15518
15519
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200155208.2.2. TCP log format
15521---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015522
15523The TCP format is used when "option tcplog" is specified in the frontend, and
15524is the recommended format for pure TCP proxies. It provides a lot of precious
15525information for troubleshooting. Since this format includes timers and byte
15526counts, the log is normally emitted at the end of the session. It can be
15527emitted earlier if "option logasap" is specified, which makes sense in most
15528environments with long sessions such as remote terminals. Sessions which match
15529the "monitor" rules are never logged. It is also possible not to emit logs for
15530sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020015531specifying "option dontlognull" in the frontend. Successful connections will
15532not be logged if "option dontlog-normal" is specified in the frontend. A few
15533fields may slightly vary depending on some configuration options, those are
15534marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015535
15536 Example :
15537 frontend fnt
15538 mode tcp
15539 option tcplog
15540 log global
15541 default_backend bck
15542
15543 backend bck
15544 server srv1 127.0.0.1:8000
15545
15546 >>> Feb 6 12:12:56 localhost \
15547 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
15548 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
15549
15550 Field Format Extract from the example above
15551 1 process_name '[' pid ']:' haproxy[14387]:
15552 2 client_ip ':' client_port 10.0.1.2:33313
15553 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
15554 4 frontend_name fnt
15555 5 backend_name '/' server_name bck/srv1
15556 6 Tw '/' Tc '/' Tt* 0/0/5007
15557 7 bytes_read* 212
15558 8 termination_state --
15559 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
15560 10 srv_queue '/' backend_queue 0/0
15561
15562Detailed fields description :
15563 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010015564 connection to haproxy. If the connection was accepted on a UNIX socket
15565 instead, the IP address would be replaced with the word "unix". Note that
15566 when the connection is accepted on a socket configured with "accept-proxy"
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010015567 and the PROXY protocol is correctly used, or with a "accept-netscaler-cip"
15568 and the NetScaler Client IP insetion protocol is correctly used, then the
15569 logs will reflect the forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015570
15571 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010015572 If the connection was accepted on a UNIX socket instead, the port would be
15573 replaced with the ID of the accepting socket, which is also reported in the
15574 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015575
15576 - "accept_date" is the exact date when the connection was received by haproxy
15577 (which might be very slightly different from the date observed on the
15578 network if there was some queuing in the system's backlog). This is usually
15579 the same date which may appear in any upstream firewall's log.
15580
15581 - "frontend_name" is the name of the frontend (or listener) which received
15582 and processed the connection.
15583
15584 - "backend_name" is the name of the backend (or listener) which was selected
15585 to manage the connection to the server. This will be the same as the
15586 frontend if no switching rule has been applied, which is common for TCP
15587 applications.
15588
15589 - "server_name" is the name of the last server to which the connection was
15590 sent, which might differ from the first one if there were connection errors
15591 and a redispatch occurred. Note that this server belongs to the backend
15592 which processed the request. If the connection was aborted before reaching
15593 a server, "<NOSRV>" is indicated instead of a server name.
15594
15595 - "Tw" is the total time in milliseconds spent waiting in the various queues.
15596 It can be "-1" if the connection was aborted before reaching the queue.
15597 See "Timers" below for more details.
15598
15599 - "Tc" is the total time in milliseconds spent waiting for the connection to
15600 establish to the final server, including retries. It can be "-1" if the
15601 connection was aborted before a connection could be established. See
15602 "Timers" below for more details.
15603
15604 - "Tt" is the total time in milliseconds elapsed between the accept and the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030015605 last close. It covers all possible processing. There is one exception, if
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015606 "option logasap" was specified, then the time counting stops at the moment
15607 the log is emitted. In this case, a '+' sign is prepended before the value,
15608 indicating that the final one will be larger. See "Timers" below for more
15609 details.
15610
15611 - "bytes_read" is the total number of bytes transmitted from the server to
15612 the client when the log is emitted. If "option logasap" is specified, the
15613 this value will be prefixed with a '+' sign indicating that the final one
15614 may be larger. Please note that this value is a 64-bit counter, so log
15615 analysis tools must be able to handle it without overflowing.
15616
15617 - "termination_state" is the condition the session was in when the session
15618 ended. This indicates the session state, which side caused the end of
15619 session to happen, and for what reason (timeout, error, ...). The normal
15620 flags should be "--", indicating the session was closed by either end with
15621 no data remaining in buffers. See below "Session state at disconnection"
15622 for more details.
15623
15624 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040015625 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015626 limits have been reached. For instance, if actconn is close to 512 when
15627 multiple connection errors occur, chances are high that the system limits
15628 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015629 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015630
15631 - "feconn" is the total number of concurrent connections on the frontend when
15632 the session was logged. It is useful to estimate the amount of resource
15633 required to sustain high loads, and to detect when the frontend's "maxconn"
15634 has been reached. Most often when this value increases by huge jumps, it is
15635 because there is congestion on the backend servers, but sometimes it can be
15636 caused by a denial of service attack.
15637
15638 - "beconn" is the total number of concurrent connections handled by the
15639 backend when the session was logged. It includes the total number of
15640 concurrent connections active on servers as well as the number of
15641 connections pending in queues. It is useful to estimate the amount of
15642 additional servers needed to support high loads for a given application.
15643 Most often when this value increases by huge jumps, it is because there is
15644 congestion on the backend servers, but sometimes it can be caused by a
15645 denial of service attack.
15646
15647 - "srv_conn" is the total number of concurrent connections still active on
15648 the server when the session was logged. It can never exceed the server's
15649 configured "maxconn" parameter. If this value is very often close or equal
15650 to the server's "maxconn", it means that traffic regulation is involved a
15651 lot, meaning that either the server's maxconn value is too low, or that
15652 there aren't enough servers to process the load with an optimal response
15653 time. When only one of the server's "srv_conn" is high, it usually means
15654 that this server has some trouble causing the connections to take longer to
15655 be processed than on other servers.
15656
15657 - "retries" is the number of connection retries experienced by this session
15658 when trying to connect to the server. It must normally be zero, unless a
15659 server is being stopped at the same moment the connection was attempted.
15660 Frequent retries generally indicate either a network problem between
15661 haproxy and the server, or a misconfigured system backlog on the server
15662 preventing new connections from being queued. This field may optionally be
15663 prefixed with a '+' sign, indicating that the session has experienced a
15664 redispatch after the maximal retry count has been reached on the initial
15665 server. In this case, the server name appearing in the log is the one the
15666 connection was redispatched to, and not the first one, though both may
15667 sometimes be the same in case of hashing for instance. So as a general rule
15668 of thumb, when a '+' is present in front of the retry count, this count
15669 should not be attributed to the logged server.
15670
15671 - "srv_queue" is the total number of requests which were processed before
15672 this one in the server queue. It is zero when the request has not gone
15673 through the server queue. It makes it possible to estimate the approximate
15674 server's response time by dividing the time spent in queue by the number of
15675 requests in the queue. It is worth noting that if a session experiences a
15676 redispatch and passes through two server queues, their positions will be
15677 cumulated. A request should not pass through both the server queue and the
15678 backend queue unless a redispatch occurs.
15679
15680 - "backend_queue" is the total number of requests which were processed before
15681 this one in the backend's global queue. It is zero when the request has not
15682 gone through the global queue. It makes it possible to estimate the average
15683 queue length, which easily translates into a number of missing servers when
15684 divided by a server's "maxconn" parameter. It is worth noting that if a
15685 session experiences a redispatch, it may pass twice in the backend's queue,
15686 and then both positions will be cumulated. A request should not pass
15687 through both the server queue and the backend queue unless a redispatch
15688 occurs.
15689
15690
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200156918.2.3. HTTP log format
15692----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015693
15694The HTTP format is the most complete and the best suited for HTTP proxies. It
15695is enabled by when "option httplog" is specified in the frontend. It provides
15696the same level of information as the TCP format with additional features which
15697are specific to the HTTP protocol. Just like the TCP format, the log is usually
15698emitted at the end of the session, unless "option logasap" is specified, which
15699generally only makes sense for download sites. A session which matches the
15700"monitor" rules will never logged. It is also possible not to log sessions for
15701which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020015702frontend. Successful connections will not be logged if "option dontlog-normal"
15703is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015704
15705Most fields are shared with the TCP log, some being different. A few fields may
15706slightly vary depending on some configuration options. Those ones are marked
15707with a star ('*') after the field name below.
15708
15709 Example :
15710 frontend http-in
15711 mode http
15712 option httplog
15713 log global
15714 default_backend bck
15715
15716 backend static
15717 server srv1 127.0.0.1:8000
15718
15719 >>> Feb 6 12:14:14 localhost \
15720 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
15721 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 +010015722 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015723
15724 Field Format Extract from the example above
15725 1 process_name '[' pid ']:' haproxy[14389]:
15726 2 client_ip ':' client_port 10.0.1.2:33317
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020015727 3 '[' request_date ']' [06/Feb/2009:12:14:14.655]
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015728 4 frontend_name http-in
15729 5 backend_name '/' server_name static/srv1
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020015730 6 TR '/' Tw '/' Tc '/' Tr '/' Ta* 10/0/30/69/109
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015731 7 status_code 200
15732 8 bytes_read* 2750
15733 9 captured_request_cookie -
15734 10 captured_response_cookie -
15735 11 termination_state ----
15736 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
15737 13 srv_queue '/' backend_queue 0/0
15738 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
15739 15 '{' captured_response_headers* '}' {}
15740 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +010015741
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015742Detailed fields description :
15743 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010015744 connection to haproxy. If the connection was accepted on a UNIX socket
15745 instead, the IP address would be replaced with the word "unix". Note that
15746 when the connection is accepted on a socket configured with "accept-proxy"
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010015747 and the PROXY protocol is correctly used, or with a "accept-netscaler-cip"
15748 and the NetScaler Client IP insetion protocol is correctly used, then the
15749 logs will reflect the forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015750
15751 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010015752 If the connection was accepted on a UNIX socket instead, the port would be
15753 replaced with the ID of the accepting socket, which is also reported in the
15754 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015755
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020015756 - "request_date" is the exact date when the first byte of the HTTP request
15757 was received by haproxy (log field %tr).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015758
15759 - "frontend_name" is the name of the frontend (or listener) which received
15760 and processed the connection.
15761
15762 - "backend_name" is the name of the backend (or listener) which was selected
15763 to manage the connection to the server. This will be the same as the
15764 frontend if no switching rule has been applied.
15765
15766 - "server_name" is the name of the last server to which the connection was
15767 sent, which might differ from the first one if there were connection errors
15768 and a redispatch occurred. Note that this server belongs to the backend
15769 which processed the request. If the request was aborted before reaching a
15770 server, "<NOSRV>" is indicated instead of a server name. If the request was
15771 intercepted by the stats subsystem, "<STATS>" is indicated instead.
15772
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020015773 - "TR" is the total time in milliseconds spent waiting for a full HTTP
15774 request from the client (not counting body) after the first byte was
15775 received. It can be "-1" if the connection was aborted before a complete
15776 request could be received or the a bad request was received. It should
15777 always be very small because a request generally fits in one single packet.
15778 Large times here generally indicate network issues between the client and
15779 haproxy or requests being typed by hand. See "Timers" below for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015780
15781 - "Tw" is the total time in milliseconds spent waiting in the various queues.
15782 It can be "-1" if the connection was aborted before reaching the queue.
15783 See "Timers" below for more details.
15784
15785 - "Tc" is the total time in milliseconds spent waiting for the connection to
15786 establish to the final server, including retries. It can be "-1" if the
15787 request was aborted before a connection could be established. See "Timers"
15788 below for more details.
15789
15790 - "Tr" is the total time in milliseconds spent waiting for the server to send
15791 a full HTTP response, not counting data. It can be "-1" if the request was
15792 aborted before a complete response could be received. It generally matches
15793 the server's processing time for the request, though it may be altered by
15794 the amount of data sent by the client to the server. Large times here on
15795 "GET" requests generally indicate an overloaded server. See "Timers" below
15796 for more details.
15797
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020015798 - "Ta" is the time the request remained active in haproxy, which is the total
15799 time in milliseconds elapsed between the first byte of the request was
15800 received and the last byte of response was sent. It covers all possible
15801 processing except the handshake (see Th) and idle time (see Ti). There is
15802 one exception, if "option logasap" was specified, then the time counting
15803 stops at the moment the log is emitted. In this case, a '+' sign is
15804 prepended before the value, indicating that the final one will be larger.
15805 See "Timers" below for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015806
15807 - "status_code" is the HTTP status code returned to the client. This status
15808 is generally set by the server, but it might also be set by haproxy when
15809 the server cannot be reached or when its response is blocked by haproxy.
15810
15811 - "bytes_read" is the total number of bytes transmitted to the client when
15812 the log is emitted. This does include HTTP headers. If "option logasap" is
15813 specified, the this value will be prefixed with a '+' sign indicating that
15814 the final one may be larger. Please note that this value is a 64-bit
15815 counter, so log analysis tools must be able to handle it without
15816 overflowing.
15817
15818 - "captured_request_cookie" is an optional "name=value" entry indicating that
15819 the client had this cookie in the request. The cookie name and its maximum
15820 length are defined by the "capture cookie" statement in the frontend
15821 configuration. The field is a single dash ('-') when the option is not
15822 set. Only one cookie may be captured, it is generally used to track session
15823 ID exchanges between a client and a server to detect session crossing
15824 between clients due to application bugs. For more details, please consult
15825 the section "Capturing HTTP headers and cookies" below.
15826
15827 - "captured_response_cookie" is an optional "name=value" entry indicating
15828 that the server has returned a cookie with its response. The cookie name
15829 and its maximum length are defined by the "capture cookie" statement in the
15830 frontend configuration. The field is a single dash ('-') when the option is
15831 not set. Only one cookie may be captured, it is generally used to track
15832 session ID exchanges between a client and a server to detect session
15833 crossing between clients due to application bugs. For more details, please
15834 consult the section "Capturing HTTP headers and cookies" below.
15835
15836 - "termination_state" is the condition the session was in when the session
15837 ended. This indicates the session state, which side caused the end of
15838 session to happen, for what reason (timeout, error, ...), just like in TCP
15839 logs, and information about persistence operations on cookies in the last
15840 two characters. The normal flags should begin with "--", indicating the
15841 session was closed by either end with no data remaining in buffers. See
15842 below "Session state at disconnection" for more details.
15843
15844 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040015845 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015846 limits have been reached. For instance, if actconn is close to 512 or 1024
15847 when multiple connection errors occur, chances are high that the system
15848 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015849 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010015850 system.
15851
15852 - "feconn" is the total number of concurrent connections on the frontend when
15853 the session was logged. It is useful to estimate the amount of resource
15854 required to sustain high loads, and to detect when the frontend's "maxconn"
15855 has been reached. Most often when this value increases by huge jumps, it is
15856 because there is congestion on the backend servers, but sometimes it can be
15857 caused by a denial of service attack.
15858
15859 - "beconn" is the total number of concurrent connections handled by the
15860 backend when the session was logged. It includes the total number of
15861 concurrent connections active on servers as well as the number of
15862 connections pending in queues. It is useful to estimate the amount of
15863 additional servers needed to support high loads for a given application.
15864 Most often when this value increases by huge jumps, it is because there is
15865 congestion on the backend servers, but sometimes it can be caused by a
15866 denial of service attack.
15867
15868 - "srv_conn" is the total number of concurrent connections still active on
15869 the server when the session was logged. It can never exceed the server's
15870 configured "maxconn" parameter. If this value is very often close or equal
15871 to the server's "maxconn", it means that traffic regulation is involved a
15872 lot, meaning that either the server's maxconn value is too low, or that
15873 there aren't enough servers to process the load with an optimal response
15874 time. When only one of the server's "srv_conn" is high, it usually means
15875 that this server has some trouble causing the requests to take longer to be
15876 processed than on other servers.
15877
15878 - "retries" is the number of connection retries experienced by this session
15879 when trying to connect to the server. It must normally be zero, unless a
15880 server is being stopped at the same moment the connection was attempted.
15881 Frequent retries generally indicate either a network problem between
15882 haproxy and the server, or a misconfigured system backlog on the server
15883 preventing new connections from being queued. This field may optionally be
15884 prefixed with a '+' sign, indicating that the session has experienced a
15885 redispatch after the maximal retry count has been reached on the initial
15886 server. In this case, the server name appearing in the log is the one the
15887 connection was redispatched to, and not the first one, though both may
15888 sometimes be the same in case of hashing for instance. So as a general rule
15889 of thumb, when a '+' is present in front of the retry count, this count
15890 should not be attributed to the logged server.
15891
15892 - "srv_queue" is the total number of requests which were processed before
15893 this one in the server queue. It is zero when the request has not gone
15894 through the server queue. It makes it possible to estimate the approximate
15895 server's response time by dividing the time spent in queue by the number of
15896 requests in the queue. It is worth noting that if a session experiences a
15897 redispatch and passes through two server queues, their positions will be
15898 cumulated. A request should not pass through both the server queue and the
15899 backend queue unless a redispatch occurs.
15900
15901 - "backend_queue" is the total number of requests which were processed before
15902 this one in the backend's global queue. It is zero when the request has not
15903 gone through the global queue. It makes it possible to estimate the average
15904 queue length, which easily translates into a number of missing servers when
15905 divided by a server's "maxconn" parameter. It is worth noting that if a
15906 session experiences a redispatch, it may pass twice in the backend's queue,
15907 and then both positions will be cumulated. A request should not pass
15908 through both the server queue and the backend queue unless a redispatch
15909 occurs.
15910
15911 - "captured_request_headers" is a list of headers captured in the request due
15912 to the presence of the "capture request header" statement in the frontend.
15913 Multiple headers can be captured, they will be delimited by a vertical bar
15914 ('|'). When no capture is enabled, the braces do not appear, causing a
15915 shift of remaining fields. It is important to note that this field may
15916 contain spaces, and that using it requires a smarter log parser than when
15917 it's not used. Please consult the section "Capturing HTTP headers and
15918 cookies" below for more details.
15919
15920 - "captured_response_headers" is a list of headers captured in the response
15921 due to the presence of the "capture response header" statement in the
15922 frontend. Multiple headers can be captured, they will be delimited by a
15923 vertical bar ('|'). When no capture is enabled, the braces do not appear,
15924 causing a shift of remaining fields. It is important to note that this
15925 field may contain spaces, and that using it requires a smarter log parser
15926 than when it's not used. Please consult the section "Capturing HTTP headers
15927 and cookies" below for more details.
15928
15929 - "http_request" is the complete HTTP request line, including the method,
15930 request and HTTP version string. Non-printable characters are encoded (see
15931 below the section "Non-printable characters"). This is always the last
15932 field, and it is always delimited by quotes and is the only one which can
15933 contain quotes. If new fields are added to the log format, they will be
15934 added before this field. This field might be truncated if the request is
15935 huge and does not fit in the standard syslog buffer (1024 characters). This
15936 is the reason why this field must always remain the last one.
15937
15938
Cyril Bontédc4d9032012-04-08 21:57:39 +0200159398.2.4. Custom log format
15940------------------------
William Lallemand48940402012-01-30 16:47:22 +010015941
Willy Tarreau2beef582012-12-20 17:22:52 +010015942The directive log-format allows you to customize the logs in http mode and tcp
William Lallemandbddd4fd2012-02-27 11:23:10 +010015943mode. It takes a string as argument.
William Lallemand48940402012-01-30 16:47:22 +010015944
15945HAproxy understands some log format variables. % precedes log format variables.
15946Variables can take arguments using braces ('{}'), and multiple arguments are
15947separated by commas within the braces. Flags may be added or removed by
15948prefixing them with a '+' or '-' sign.
15949
15950Special variable "%o" may be used to propagate its flags to all other
15951variables on the same format string. This is particularly handy with quoted
Dragan Dosen835b9212016-02-12 13:23:03 +010015952("Q") and escaped ("E") string formats.
William Lallemand48940402012-01-30 16:47:22 +010015953
Willy Tarreauc8368452012-12-21 00:09:23 +010015954If a variable is named between square brackets ('[' .. ']') then it is used
Willy Tarreaube722a22014-06-13 16:31:59 +020015955as a sample expression rule (see section 7.3). This it useful to add some
Willy Tarreauc8368452012-12-21 00:09:23 +010015956less common information such as the client's SSL certificate's DN, or to log
15957the key that would be used to store an entry into a stick table.
15958
William Lallemand48940402012-01-30 16:47:22 +010015959Note: spaces must be escaped. A space character is considered as a separator.
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030015960In order to emit a verbatim '%', it must be preceded by another '%' resulting
Willy Tarreau06d97f92013-12-02 17:45:48 +010015961in '%%'. HAProxy will automatically merge consecutive separators.
William Lallemand48940402012-01-30 16:47:22 +010015962
Dragan Dosen835b9212016-02-12 13:23:03 +010015963Note: when using the RFC5424 syslog message format, the characters '"',
15964'\' and ']' inside PARAM-VALUE should be escaped with '\' as prefix (see
15965https://tools.ietf.org/html/rfc5424#section-6.3.3 for more details). In
15966such cases, the use of the flag "E" should be considered.
15967
William Lallemand48940402012-01-30 16:47:22 +010015968Flags are :
15969 * Q: quote a string
Jamie Gloudonaaa21002012-08-25 00:18:33 -040015970 * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid)
Dragan Dosen835b9212016-02-12 13:23:03 +010015971 * E: escape characters '"', '\' and ']' in a string with '\' as prefix
15972 (intended purpose is for the RFC5424 structured-data log formats)
William Lallemand48940402012-01-30 16:47:22 +010015973
15974 Example:
15975
15976 log-format %T\ %t\ Some\ Text
15977 log-format %{+Q}o\ %t\ %s\ %{-Q}r
15978
Dragan Dosen835b9212016-02-12 13:23:03 +010015979 log-format-sd %{+Q,+E}o\ [exampleSDID@1234\ header=%[capture.req.hdr(0)]]
15980
William Lallemand48940402012-01-30 16:47:22 +010015981At the moment, the default HTTP format is defined this way :
15982
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020015983 log-format "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC \
15984 %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs %{+Q}r"
William Lallemand48940402012-01-30 16:47:22 +010015985
William Lallemandbddd4fd2012-02-27 11:23:10 +010015986the default CLF format is defined this way :
William Lallemand48940402012-01-30 16:47:22 +010015987
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020015988 log-format "%{+Q}o %{-Q}ci - - [%trg] %r %ST %B \"\" \"\" %cp \
15989 %ms %ft %b %s %TR %Tw %Tc %Tr %Ta %tsc %ac %fc \
15990 %bc %sc %rc %sq %bq %CC %CS %hrl %hsl"
William Lallemand48940402012-01-30 16:47:22 +010015991
William Lallemandbddd4fd2012-02-27 11:23:10 +010015992and the default TCP format is defined this way :
15993
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020015994 log-format "%ci:%cp [%t] %ft %b/%s %Tw/%Tc/%Tt %B %ts \
15995 %ac/%fc/%bc/%sc/%rc %sq/%bq"
William Lallemandbddd4fd2012-02-27 11:23:10 +010015996
William Lallemand48940402012-01-30 16:47:22 +010015997Please refer to the table below for currently defined variables :
15998
William Lallemandbddd4fd2012-02-27 11:23:10 +010015999 +---+------+-----------------------------------------------+-------------+
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020016000 | R | var | field name (8.2.2 and 8.2.3 for description) | type |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016001 +---+------+-----------------------------------------------+-------------+
16002 | | %o | special variable, apply flags on all next var | |
16003 +---+------+-----------------------------------------------+-------------+
Willy Tarreau2beef582012-12-20 17:22:52 +010016004 | | %B | bytes_read (from server to client) | numeric |
16005 | H | %CC | captured_request_cookie | string |
16006 | H | %CS | captured_response_cookie | string |
William Lallemand5f232402012-04-05 18:02:55 +020016007 | | %H | hostname | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000016008 | H | %HM | HTTP method (ex: POST) | string |
16009 | H | %HP | HTTP request URI without query string (path) | string |
Andrew Hayworthe63ac872015-07-31 16:14:16 +000016010 | H | %HQ | HTTP request URI query string (ex: ?bar=baz) | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000016011 | H | %HU | HTTP request URI (ex: /foo?bar=baz) | string |
16012 | H | %HV | HTTP version (ex: HTTP/1.0) | string |
William Lallemanda73203e2012-03-12 12:48:57 +010016013 | | %ID | unique-id | string |
Willy Tarreau4bf99632014-06-13 12:21:40 +020016014 | | %ST | status_code | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020016015 | | %T | gmt_date_time | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016016 | | %Ta | Active time of the request (from TR to end) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016017 | | %Tc | Tc | numeric |
Willy Tarreau27b639d2016-05-17 17:55:27 +020016018 | | %Td | Td = Tt - (Tq + Tw + Tc + Tr) | numeric |
Yuxans Yao4e25b012012-10-19 10:36:09 +080016019 | | %Tl | local_date_time | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016020 | | %Th | connection handshake time (SSL, PROXY proto) | numeric |
16021 | H | %Ti | idle time before the HTTP request | numeric |
16022 | H | %Tq | Th + Ti + TR | numeric |
16023 | H | %TR | time to receive the full request from 1st byte| numeric |
16024 | H | %Tr | Tr (response time) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020016025 | | %Ts | timestamp | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016026 | | %Tt | Tt | numeric |
16027 | | %Tw | Tw | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010016028 | | %U | bytes_uploaded (from client to server) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016029 | | %ac | actconn | numeric |
16030 | | %b | backend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010016031 | | %bc | beconn (backend concurrent connections) | numeric |
16032 | | %bi | backend_source_ip (connecting address) | IP |
16033 | | %bp | backend_source_port (connecting address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016034 | | %bq | backend_queue | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010016035 | | %ci | client_ip (accepted address) | IP |
16036 | | %cp | client_port (accepted address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016037 | | %f | frontend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010016038 | | %fc | feconn (frontend concurrent connections) | numeric |
16039 | | %fi | frontend_ip (accepting address) | IP |
16040 | | %fp | frontend_port (accepting address) | numeric |
Willy Tarreau773d65f2012-10-12 14:56:11 +020016041 | | %ft | frontend_name_transport ('~' suffix for SSL) | string |
Willy Tarreau7346acb2014-08-28 15:03:15 +020016042 | | %lc | frontend_log_counter | numeric |
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020016043 | | %hr | captured_request_headers default style | string |
16044 | | %hrl | captured_request_headers CLF style | string list |
16045 | | %hs | captured_response_headers default style | string |
16046 | | %hsl | captured_response_headers CLF style | string list |
Willy Tarreau812c88e2015-08-09 10:56:35 +020016047 | | %ms | accept date milliseconds (left-padded with 0) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020016048 | | %pid | PID | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020016049 | H | %r | http_request | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016050 | | %rc | retries | numeric |
Willy Tarreau1f0da242014-01-25 11:01:50 +010016051 | | %rt | request_counter (HTTP req or TCP session) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016052 | | %s | server_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010016053 | | %sc | srv_conn (server concurrent connections) | numeric |
16054 | | %si | server_IP (target address) | IP |
16055 | | %sp | server_port (target address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016056 | | %sq | srv_queue | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020016057 | S | %sslc| ssl_ciphers (ex: AES-SHA) | string |
16058 | S | %sslv| ssl_version (ex: TLSv1) | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010016059 | | %t | date_time (with millisecond resolution) | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016060 | H | %tr | date_time of HTTP request | date |
16061 | H | %trg | gmt_date_time of start of HTTP request | date |
16062 | H | %trl | locla_date_time of start of HTTP request | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016063 | | %ts | termination_state | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020016064 | H | %tsc | termination_state with cookie status | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010016065 +---+------+-----------------------------------------------+-------------+
William Lallemand48940402012-01-30 16:47:22 +010016066
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020016067 R = Restrictions : H = mode http only ; S = SSL only
William Lallemand48940402012-01-30 16:47:22 +010016068
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010016069
160708.2.5. Error log format
16071-----------------------
16072
16073When an incoming connection fails due to an SSL handshake or an invalid PROXY
16074protocol header, haproxy will log the event using a shorter, fixed line format.
16075By default, logs are emitted at the LOG_INFO level, unless the option
16076"log-separate-errors" is set in the backend, in which case the LOG_ERR level
16077will be used. Connections on which no data are exchanged (eg: probes) are not
16078logged if the "dontlognull" option is set.
16079
16080The format looks like this :
16081
16082 >>> Dec 3 18:27:14 localhost \
16083 haproxy[6103]: 127.0.0.1:56059 [03/Dec/2012:17:35:10.380] frt/f1: \
16084 Connection error during SSL handshake
16085
16086 Field Format Extract from the example above
16087 1 process_name '[' pid ']:' haproxy[6103]:
16088 2 client_ip ':' client_port 127.0.0.1:56059
16089 3 '[' accept_date ']' [03/Dec/2012:17:35:10.380]
16090 4 frontend_name "/" bind_name ":" frt/f1:
16091 5 message Connection error during SSL handshake
16092
16093These fields just provide minimal information to help debugging connection
16094failures.
16095
16096
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200160978.3. Advanced logging options
16098-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016099
16100Some advanced logging options are often looked for but are not easy to find out
16101just by looking at the various options. Here is an entry point for the few
16102options which can enable better logging. Please refer to the keywords reference
16103for more information about their usage.
16104
16105
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200161068.3.1. Disabling logging of external tests
16107------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016108
16109It is quite common to have some monitoring tools perform health checks on
16110haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
16111commercial load-balancer, and sometimes it will simply be a more complete
16112monitoring system such as Nagios. When the tests are very frequent, users often
16113ask how to disable logging for those checks. There are three possibilities :
16114
16115 - if connections come from everywhere and are just TCP probes, it is often
16116 desired to simply disable logging of connections without data exchange, by
16117 setting "option dontlognull" in the frontend. It also disables logging of
16118 port scans, which may or may not be desired.
16119
16120 - if the connection come from a known source network, use "monitor-net" to
16121 declare this network as monitoring only. Any host in this network will then
16122 only be able to perform health checks, and their requests will not be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016123 logged. This is generally appropriate to designate a list of equipment
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016124 such as other load-balancers.
16125
16126 - if the tests are performed on a known URI, use "monitor-uri" to declare
16127 this URI as dedicated to monitoring. Any host sending this request will
16128 only get the result of a health-check, and the request will not be logged.
16129
16130
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200161318.3.2. Logging before waiting for the session to terminate
16132----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016133
16134The problem with logging at end of connection is that you have no clue about
16135what is happening during very long sessions, such as remote terminal sessions
16136or large file downloads. This problem can be worked around by specifying
16137"option logasap" in the frontend. Haproxy will then log as soon as possible,
16138just before data transfer begins. This means that in case of TCP, it will still
16139log the connection status to the server, and in case of HTTP, it will log just
16140after processing the server headers. In this case, the number of bytes reported
16141is the number of header bytes sent to the client. In order to avoid confusion
16142with normal logs, the total time field and the number of bytes are prefixed
16143with a '+' sign which means that real numbers are certainly larger.
16144
16145
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200161468.3.3. Raising log level upon errors
16147------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020016148
16149Sometimes it is more convenient to separate normal traffic from errors logs,
16150for instance in order to ease error monitoring from log files. When the option
16151"log-separate-errors" is used, connections which experience errors, timeouts,
16152retries, redispatches or HTTP status codes 5xx will see their syslog level
16153raised from "info" to "err". This will help a syslog daemon store the log in
16154a separate file. It is very important to keep the errors in the normal traffic
16155file too, so that log ordering is not altered. You should also be careful if
16156you already have configured your syslog daemon to store all logs higher than
16157"notice" in an "admin" file, because the "err" level is higher than "notice".
16158
16159
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200161608.3.4. Disabling logging of successful connections
16161--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020016162
16163Although this may sound strange at first, some large sites have to deal with
16164multiple thousands of logs per second and are experiencing difficulties keeping
16165them intact for a long time or detecting errors within them. If the option
16166"dontlog-normal" is set on the frontend, all normal connections will not be
16167logged. In this regard, a normal connection is defined as one without any
16168error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
16169and a response with a status 5xx is not considered normal and will be logged
16170too. Of course, doing is is really discouraged as it will remove most of the
16171useful information from the logs. Do this only if you have no other
16172alternative.
16173
16174
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200161758.4. Timing events
16176------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016177
16178Timers provide a great help in troubleshooting network problems. All values are
16179reported in milliseconds (ms). These timers should be used in conjunction with
16180the session termination flags. In TCP mode with "option tcplog" set on the
16181frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016182mode, 5 control points are reported under the form "TR/Tw/Tc/Tr/Ta". In
16183addition, three other measures are provided, "Th", "Ti", and "Tq".
16184
Guillaume de Lafondf27cddc2016-12-23 17:32:43 +010016185Timings events in HTTP mode:
16186
16187 first request 2nd request
16188 |<-------------------------------->|<-------------- ...
16189 t tr t tr ...
16190 ---|----|----|----|----|----|----|----|----|--
16191 : Th Ti TR Tw Tc Tr Td : Ti ...
16192 :<---- Tq ---->: :
16193 :<-------------- Tt -------------->:
16194 :<--------- Ta --------->:
16195
16196Timings events in TCP mode:
16197
16198 TCP session
16199 |<----------------->|
16200 t t
16201 ---|----|----|----|----|---
16202 | Th Tw Tc Td |
16203 |<------ Tt ------->|
16204
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016205 - Th: total time to accept tcp connection and execute handshakes for low level
16206 protocols. Currently, these protocoles are proxy-protocol and SSL. This may
16207 only happen once during the whole connection's lifetime. A large time here
16208 may indicate that the client only pre-established the connection without
16209 speaking, that it is experiencing network issues preventing it from
16210 completing a handshake in a reasonable time (eg: MTU issues), or that an
16211 SSL handshake was very expensive to compute.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016212
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016213 - Ti: is the idle time before the HTTP request (HTTP mode only). This timer
16214 counts between the end of the handshakes and the first byte of the HTTP
16215 request. When dealing with a second request in keep-alive mode, it starts
16216 to count after the end of the transmission the previous response. Some
16217 browsers pre-establish connections to a server in order to reduce the
16218 latency of a future request, and keep them pending until they need it. This
16219 delay will be reported as the idle time. A value of -1 indicates that
16220 nothing was received on the connection.
16221
16222 - TR: total time to get the client request (HTTP mode only). It's the time
16223 elapsed between the first bytes received and the moment the proxy received
16224 the empty line marking the end of the HTTP headers. The value "-1"
16225 indicates that the end of headers has never been seen. This happens when
16226 the client closes prematurely or times out. This time is usually very short
16227 since most requests fit in a single packet. A large time may indicate a
16228 request typed by hand during a test.
16229
16230 - Tq: total time to get the client request from the accept date or since the
16231 emission of the last byte of the previous response (HTTP mode only). It's
16232 exactly equalt to Th + Ti + TR unless any of them is -1, in which case it
16233 returns -1 as well. This timer used to be very useful before the arrival of
16234 HTTP keep-alive and browsers' pre-connect feature. It's recommended to drop
16235 it in favor of TR nowadays, as the idle time adds a lot of noise to the
16236 reports.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016237
16238 - Tw: total time spent in the queues waiting for a connection slot. It
16239 accounts for backend queue as well as the server queues, and depends on the
16240 queue size, and the time needed for the server to complete previous
16241 requests. The value "-1" means that the request was killed before reaching
16242 the queue, which is generally what happens with invalid or denied requests.
16243
16244 - Tc: total time to establish the TCP connection to the server. It's the time
16245 elapsed between the moment the proxy sent the connection request, and the
16246 moment it was acknowledged by the server, or between the TCP SYN packet and
16247 the matching SYN/ACK packet in return. The value "-1" means that the
16248 connection never established.
16249
16250 - Tr: server response time (HTTP mode only). It's the time elapsed between
16251 the moment the TCP connection was established to the server and the moment
16252 the server sent its complete response headers. It purely shows its request
16253 processing time, without the network overhead due to the data transmission.
16254 It is worth noting that when the client has data to send to the server, for
16255 instance during a POST request, the time already runs, and this can distort
16256 apparent response time. For this reason, it's generally wise not to trust
16257 too much this field for POST requests initiated from clients behind an
16258 untrusted network. A value of "-1" here means that the last the response
16259 header (empty line) was never seen, most likely because the server timeout
16260 stroke before the server managed to process the request.
16261
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016262 - Ta: total active time for the HTTP request, between the moment the proxy
16263 received the first byte of the request header and the emission of the last
16264 byte of the response body. The exception is when the "logasap" option is
16265 specified. In this case, it only equals (TR+Tw+Tc+Tr), and is prefixed with
16266 a '+' sign. From this field, we can deduce "Td", the data transmission time,
16267 by subtracting other timers when valid :
16268
16269 Td = Ta - (TR + Tw + Tc + Tr)
16270
16271 Timers with "-1" values have to be excluded from this equation. Note that
16272 "Ta" can never be negative.
16273
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016274 - Tt: total session duration time, between the moment the proxy accepted it
16275 and the moment both ends were closed. The exception is when the "logasap"
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016276 option is specified. In this case, it only equals (Th+Ti+TR+Tw+Tc+Tr), and
16277 is prefixed with a '+' sign. From this field, we can deduce "Td", the data
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016278 transmission time, by subtracting other timers when valid :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016279
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016280 Td = Tt - (Th + Ti + TR + Tw + Tc + Tr)
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016281
16282 Timers with "-1" values have to be excluded from this equation. In TCP
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016283 mode, "Ti", "Tq" and "Tr" have to be excluded too. Note that "Tt" can never
16284 be negative and that for HTTP, Tt is simply equal to (Th+Ti+Ta).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016285
16286These timers provide precious indications on trouble causes. Since the TCP
16287protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
16288that timers close to multiples of 3s are nearly always related to lost packets
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016289due to network problems (wires, negotiation, congestion). Moreover, if "Ta" or
16290"Tt" is close to a timeout value specified in the configuration, it often means
16291that a session has been aborted on timeout.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016292
16293Most common cases :
16294
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016295 - If "Th" or "Ti" are close to 3000, a packet has probably been lost between
16296 the client and the proxy. This is very rare on local networks but might
16297 happen when clients are on far remote networks and send large requests. It
16298 may happen that values larger than usual appear here without any network
16299 cause. Sometimes, during an attack or just after a resource starvation has
16300 ended, haproxy may accept thousands of connections in a few milliseconds.
16301 The time spent accepting these connections will inevitably slightly delay
16302 processing of other connections, and it can happen that request times in the
16303 order of a few tens of milliseconds are measured after a few thousands of
16304 new connections have been accepted at once. Using one of the keep-alive
16305 modes may display larger idle times since "Ti" measures the time spent
Patrick Mezard105faca2010-06-12 17:02:46 +020016306 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016307
16308 - If "Tc" is close to 3000, a packet has probably been lost between the
16309 server and the proxy during the server connection phase. This value should
16310 always be very low, such as 1 ms on local networks and less than a few tens
16311 of ms on remote networks.
16312
Willy Tarreau55165fe2009-05-10 12:02:55 +020016313 - If "Tr" is nearly always lower than 3000 except some rare values which seem
16314 to be the average majored by 3000, there are probably some packets lost
16315 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016316
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016317 - If "Ta" is large even for small byte counts, it generally is because
16318 neither the client nor the server decides to close the connection while
16319 haproxy is running in tunnel mode and both have agreed on a keep-alive
16320 connection mode. In order to solve this issue, it will be needed to specify
16321 one of the HTTP options to manipulate keep-alive or close options on either
16322 the frontend or the backend. Having the smallest possible 'Ta' or 'Tt' is
16323 important when connection regulation is used with the "maxconn" option on
16324 the servers, since no new connection will be sent to the server until
16325 another one is released.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016326
16327Other noticeable HTTP log cases ('xx' means any value to be ignored) :
16328
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016329 TR/Tw/Tc/Tr/+Ta The "option logasap" is present on the frontend and the log
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016330 was emitted before the data phase. All the timers are valid
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016331 except "Ta" which is shorter than reality.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016332
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016333 -1/xx/xx/xx/Ta The client was not able to send a complete request in time
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016334 or it aborted too early. Check the session termination flags
16335 then "timeout http-request" and "timeout client" settings.
16336
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016337 TR/-1/xx/xx/Ta It was not possible to process the request, maybe because
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016338 servers were out of order, because the request was invalid
16339 or forbidden by ACL rules. Check the session termination
16340 flags.
16341
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016342 TR/Tw/-1/xx/Ta The connection could not establish on the server. Either it
16343 actively refused it or it timed out after Ta-(TR+Tw) ms.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016344 Check the session termination flags, then check the
16345 "timeout connect" setting. Note that the tarpit action might
16346 return similar-looking patterns, with "Tw" equal to the time
16347 the client connection was maintained open.
16348
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016349 TR/Tw/Tc/-1/Ta The server has accepted the connection but did not return
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016350 a complete response in time, or it closed its connection
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020016351 unexpectedly after Ta-(TR+Tw+Tc) ms. Check the session
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016352 termination flags, then check the "timeout server" setting.
16353
16354
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200163558.5. Session state at disconnection
16356-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016357
16358TCP and HTTP logs provide a session termination indicator in the
16359"termination_state" field, just before the number of active connections. It is
163602-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
16361each of which has a special meaning :
16362
16363 - On the first character, a code reporting the first event which caused the
16364 session to terminate :
16365
16366 C : the TCP session was unexpectedly aborted by the client.
16367
16368 S : the TCP session was unexpectedly aborted by the server, or the
16369 server explicitly refused it.
16370
16371 P : the session was prematurely aborted by the proxy, because of a
16372 connection limit enforcement, because a DENY filter was matched,
16373 because of a security check which detected and blocked a dangerous
16374 error in server response which might have caused information leak
Willy Tarreau570f2212013-06-10 16:42:09 +020016375 (eg: cacheable cookie).
16376
16377 L : the session was locally processed by haproxy and was not passed to
16378 a server. This is what happens for stats and redirects.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016379
16380 R : a resource on the proxy has been exhausted (memory, sockets, source
16381 ports, ...). Usually, this appears during the connection phase, and
16382 system logs should contain a copy of the precise error. If this
16383 happens, it must be considered as a very serious anomaly which
16384 should be fixed as soon as possible by any means.
16385
16386 I : an internal error was identified by the proxy during a self-check.
16387 This should NEVER happen, and you are encouraged to report any log
16388 containing this, because this would almost certainly be a bug. It
16389 would be wise to preventively restart the process after such an
16390 event too, in case it would be caused by memory corruption.
16391
Simon Horman752dc4a2011-06-21 14:34:59 +090016392 D : the session was killed by haproxy because the server was detected
16393 as down and was configured to kill all connections when going down.
16394
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070016395 U : the session was killed by haproxy on this backup server because an
16396 active server was detected as up and was configured to kill all
16397 backup connections when going up.
16398
Willy Tarreaua2a64e92011-09-07 23:01:56 +020016399 K : the session was actively killed by an admin operating on haproxy.
16400
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016401 c : the client-side timeout expired while waiting for the client to
16402 send or receive data.
16403
16404 s : the server-side timeout expired while waiting for the server to
16405 send or receive data.
16406
16407 - : normal session completion, both the client and the server closed
16408 with nothing left in the buffers.
16409
16410 - on the second character, the TCP or HTTP session state when it was closed :
16411
Willy Tarreauf7b30a92010-12-06 22:59:17 +010016412 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016413 (HTTP mode only). Nothing was sent to any server.
16414
16415 Q : the proxy was waiting in the QUEUE for a connection slot. This can
16416 only happen when servers have a 'maxconn' parameter set. It can
16417 also happen in the global queue after a redispatch consecutive to
16418 a failed attempt to connect to a dying server. If no redispatch is
16419 reported, then no connection attempt was made to any server.
16420
16421 C : the proxy was waiting for the CONNECTION to establish on the
16422 server. The server might at most have noticed a connection attempt.
16423
16424 H : the proxy was waiting for complete, valid response HEADERS from the
16425 server (HTTP only).
16426
16427 D : the session was in the DATA phase.
16428
16429 L : the proxy was still transmitting LAST data to the client while the
16430 server had already finished. This one is very rare as it can only
16431 happen when the client dies while receiving the last packets.
16432
16433 T : the request was tarpitted. It has been held open with the client
16434 during the whole "timeout tarpit" duration or until the client
16435 closed, both of which will be reported in the "Tw" timer.
16436
16437 - : normal session completion after end of data transfer.
16438
16439 - the third character tells whether the persistence cookie was provided by
16440 the client (only in HTTP mode) :
16441
16442 N : the client provided NO cookie. This is usually the case for new
16443 visitors, so counting the number of occurrences of this flag in the
16444 logs generally indicate a valid trend for the site frequentation.
16445
16446 I : the client provided an INVALID cookie matching no known server.
16447 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +020016448 cookies between HTTP/HTTPS sites, persistence conditionally
16449 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016450
16451 D : the client provided a cookie designating a server which was DOWN,
16452 so either "option persist" was used and the client was sent to
16453 this server, or it was not set and the client was redispatched to
16454 another server.
16455
Willy Tarreau996a92c2010-10-13 19:30:47 +020016456 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016457 server.
16458
Willy Tarreau996a92c2010-10-13 19:30:47 +020016459 E : the client provided a valid cookie, but with a last date which was
16460 older than what is allowed by the "maxidle" cookie parameter, so
16461 the cookie is consider EXPIRED and is ignored. The request will be
16462 redispatched just as if there was no cookie.
16463
16464 O : the client provided a valid cookie, but with a first date which was
16465 older than what is allowed by the "maxlife" cookie parameter, so
16466 the cookie is consider too OLD and is ignored. The request will be
16467 redispatched just as if there was no cookie.
16468
Willy Tarreauc89ccb62012-04-05 21:18:22 +020016469 U : a cookie was present but was not used to select the server because
16470 some other server selection mechanism was used instead (typically a
16471 "use-server" rule).
16472
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016473 - : does not apply (no cookie set in configuration).
16474
16475 - the last character reports what operations were performed on the persistence
16476 cookie returned by the server (only in HTTP mode) :
16477
16478 N : NO cookie was provided by the server, and none was inserted either.
16479
16480 I : no cookie was provided by the server, and the proxy INSERTED one.
16481 Note that in "cookie insert" mode, if the server provides a cookie,
16482 it will still be overwritten and reported as "I" here.
16483
Willy Tarreau996a92c2010-10-13 19:30:47 +020016484 U : the proxy UPDATED the last date in the cookie that was presented by
16485 the client. This can only happen in insert mode with "maxidle". It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016486 happens every time there is activity at a different date than the
Willy Tarreau996a92c2010-10-13 19:30:47 +020016487 date indicated in the cookie. If any other change happens, such as
16488 a redispatch, then the cookie will be marked as inserted instead.
16489
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016490 P : a cookie was PROVIDED by the server and transmitted as-is.
16491
16492 R : the cookie provided by the server was REWRITTEN by the proxy, which
16493 happens in "cookie rewrite" or "cookie prefix" modes.
16494
16495 D : the cookie provided by the server was DELETED by the proxy.
16496
16497 - : does not apply (no cookie set in configuration).
16498
Willy Tarreau996a92c2010-10-13 19:30:47 +020016499The combination of the two first flags gives a lot of information about what
16500was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016501helpful to detect server saturation, network troubles, local system resource
16502starvation, attacks, etc...
16503
16504The most common termination flags combinations are indicated below. They are
16505alphabetically sorted, with the lowercase set just after the upper case for
16506easier finding and understanding.
16507
16508 Flags Reason
16509
16510 -- Normal termination.
16511
16512 CC The client aborted before the connection could be established to the
16513 server. This can happen when haproxy tries to connect to a recently
16514 dead (or unchecked) server, and the client aborts while haproxy is
16515 waiting for the server to respond or for "timeout connect" to expire.
16516
16517 CD The client unexpectedly aborted during data transfer. This can be
16518 caused by a browser crash, by an intermediate equipment between the
16519 client and haproxy which decided to actively break the connection,
16520 by network routing issues between the client and haproxy, or by a
16521 keep-alive session between the server and the client terminated first
16522 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +010016523
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016524 cD The client did not send nor acknowledge any data for as long as the
16525 "timeout client" delay. This is often caused by network failures on
Cyril Bontédc4d9032012-04-08 21:57:39 +020016526 the client side, or the client simply leaving the net uncleanly.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016527
16528 CH The client aborted while waiting for the server to start responding.
16529 It might be the server taking too long to respond or the client
16530 clicking the 'Stop' button too fast.
16531
16532 cH The "timeout client" stroke while waiting for client data during a
16533 POST request. This is sometimes caused by too large TCP MSS values
16534 for PPPoE networks which cannot transport full-sized packets. It can
16535 also happen when client timeout is smaller than server timeout and
16536 the server takes too long to respond.
16537
16538 CQ The client aborted while its session was queued, waiting for a server
16539 with enough empty slots to accept it. It might be that either all the
16540 servers were saturated or that the assigned server was taking too
16541 long a time to respond.
16542
16543 CR The client aborted before sending a full HTTP request. Most likely
16544 the request was typed by hand using a telnet client, and aborted
16545 too early. The HTTP status code is likely a 400 here. Sometimes this
16546 might also be caused by an IDS killing the connection between haproxy
Willy Tarreau0f228a02015-05-01 15:37:53 +020016547 and the client. "option http-ignore-probes" can be used to ignore
16548 connections without any data transfer.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016549
16550 cR The "timeout http-request" stroke before the client sent a full HTTP
16551 request. This is sometimes caused by too large TCP MSS values on the
16552 client side for PPPoE networks which cannot transport full-sized
16553 packets, or by clients sending requests by hand and not typing fast
16554 enough, or forgetting to enter the empty line at the end of the
Willy Tarreau2705a612014-05-23 17:38:34 +020016555 request. The HTTP status code is likely a 408 here. Note: recently,
Willy Tarreau0f228a02015-05-01 15:37:53 +020016556 some browsers started to implement a "pre-connect" feature consisting
16557 in speculatively connecting to some recently visited web sites just
16558 in case the user would like to visit them. This results in many
16559 connections being established to web sites, which end up in 408
16560 Request Timeout if the timeout strikes first, or 400 Bad Request when
16561 the browser decides to close them first. These ones pollute the log
16562 and feed the error counters. Some versions of some browsers have even
16563 been reported to display the error code. It is possible to work
16564 around the undesirable effects of this behaviour by adding "option
16565 http-ignore-probes" in the frontend, resulting in connections with
16566 zero data transfer to be totally ignored. This will definitely hide
16567 the errors of people experiencing connectivity issues though.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016568
16569 CT The client aborted while its session was tarpitted. It is important to
16570 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +020016571 wrong tarpit rules have been written. If a lot of them happen, it
16572 might make sense to lower the "timeout tarpit" value to something
16573 closer to the average reported "Tw" timer, in order not to consume
16574 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016575
Willy Tarreau570f2212013-06-10 16:42:09 +020016576 LR The request was intercepted and locally handled by haproxy. Generally
16577 it means that this was a redirect or a stats request.
16578
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010016579 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016580 the TCP connection (the proxy received a TCP RST or an ICMP message
16581 in return). Under some circumstances, it can also be the network
16582 stack telling the proxy that the server is unreachable (eg: no route,
16583 or no ARP response on local network). When this happens in HTTP mode,
16584 the status code is likely a 502 or 503 here.
16585
16586 sC The "timeout connect" stroke before a connection to the server could
16587 complete. When this happens in HTTP mode, the status code is likely a
16588 503 or 504 here.
16589
16590 SD The connection to the server died with an error during the data
16591 transfer. This usually means that haproxy has received an RST from
16592 the server or an ICMP message from an intermediate equipment while
16593 exchanging data with the server. This can be caused by a server crash
16594 or by a network issue on an intermediate equipment.
16595
16596 sD The server did not send nor acknowledge any data for as long as the
16597 "timeout server" setting during the data phase. This is often caused
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010016598 by too short timeouts on L4 equipments before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016599 load-balancers, ...), as well as keep-alive sessions maintained
16600 between the client and the server expiring first on haproxy.
16601
16602 SH The server aborted before sending its full HTTP response headers, or
16603 it crashed while processing the request. Since a server aborting at
16604 this moment is very rare, it would be wise to inspect its logs to
16605 control whether it crashed and why. The logged request may indicate a
16606 small set of faulty requests, demonstrating bugs in the application.
16607 Sometimes this might also be caused by an IDS killing the connection
16608 between haproxy and the server.
16609
16610 sH The "timeout server" stroke before the server could return its
16611 response headers. This is the most common anomaly, indicating too
16612 long transactions, probably caused by server or database saturation.
16613 The immediate workaround consists in increasing the "timeout server"
16614 setting, but it is important to keep in mind that the user experience
16615 will suffer from these long response times. The only long term
16616 solution is to fix the application.
16617
16618 sQ The session spent too much time in queue and has been expired. See
16619 the "timeout queue" and "timeout connect" settings to find out how to
16620 fix this if it happens too often. If it often happens massively in
16621 short periods, it may indicate general problems on the affected
16622 servers due to I/O or database congestion, or saturation caused by
16623 external attacks.
16624
16625 PC The proxy refused to establish a connection to the server because the
16626 process' socket limit has been reached while attempting to connect.
Cyril Bontédc4d9032012-04-08 21:57:39 +020016627 The global "maxconn" parameter may be increased in the configuration
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016628 so that it does not happen anymore. This status is very rare and
16629 might happen when the global "ulimit-n" parameter is forced by hand.
16630
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010016631 PD The proxy blocked an incorrectly formatted chunked encoded message in
16632 a request or a response, after the server has emitted its headers. In
16633 most cases, this will indicate an invalid message from the server to
Willy Tarreauf3a3e132013-08-31 08:16:26 +020016634 the client. Haproxy supports chunk sizes of up to 2GB - 1 (2147483647
16635 bytes). Any larger size will be considered as an error.
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010016636
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016637 PH The proxy blocked the server's response, because it was invalid,
16638 incomplete, dangerous (cache control), or matched a security filter.
16639 In any case, an HTTP 502 error is sent to the client. One possible
16640 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010016641 containing unauthorized characters. It is also possible but quite
16642 rare, that the proxy blocked a chunked-encoding request from the
16643 client due to an invalid syntax, before the server responded. In this
16644 case, an HTTP 400 error is sent to the client and reported in the
16645 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016646
16647 PR The proxy blocked the client's HTTP request, either because of an
16648 invalid HTTP syntax, in which case it returned an HTTP 400 error to
16649 the client, or because a deny filter matched, in which case it
16650 returned an HTTP 403 error.
16651
16652 PT The proxy blocked the client's request and has tarpitted its
16653 connection before returning it a 500 server error. Nothing was sent
16654 to the server. The connection was maintained open for as long as
16655 reported by the "Tw" timer field.
16656
16657 RC A local resource has been exhausted (memory, sockets, source ports)
16658 preventing the connection to the server from establishing. The error
16659 logs will tell precisely what was missing. This is very rare and can
16660 only be solved by proper system tuning.
16661
Willy Tarreau996a92c2010-10-13 19:30:47 +020016662The combination of the two last flags gives a lot of information about how
16663persistence was handled by the client, the server and by haproxy. This is very
16664important to troubleshoot disconnections, when users complain they have to
16665re-authenticate. The commonly encountered flags are :
16666
16667 -- Persistence cookie is not enabled.
16668
16669 NN No cookie was provided by the client, none was inserted in the
16670 response. For instance, this can be in insert mode with "postonly"
16671 set on a GET request.
16672
16673 II A cookie designating an invalid server was provided by the client,
16674 a valid one was inserted in the response. This typically happens when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040016675 a "server" entry is removed from the configuration, since its cookie
Willy Tarreau996a92c2010-10-13 19:30:47 +020016676 value can be presented by a client when no other server knows it.
16677
16678 NI No cookie was provided by the client, one was inserted in the
16679 response. This typically happens for first requests from every user
16680 in "insert" mode, which makes it an easy way to count real users.
16681
16682 VN A cookie was provided by the client, none was inserted in the
16683 response. This happens for most responses for which the client has
16684 already got a cookie.
16685
16686 VU A cookie was provided by the client, with a last visit date which is
16687 not completely up-to-date, so an updated cookie was provided in
16688 response. This can also happen if there was no date at all, or if
16689 there was a date but the "maxidle" parameter was not set, so that the
16690 cookie can be switched to unlimited time.
16691
16692 EI A cookie was provided by the client, with a last visit date which is
16693 too old for the "maxidle" parameter, so the cookie was ignored and a
16694 new cookie was inserted in the response.
16695
16696 OI A cookie was provided by the client, with a first visit date which is
16697 too old for the "maxlife" parameter, so the cookie was ignored and a
16698 new cookie was inserted in the response.
16699
16700 DI The server designated by the cookie was down, a new server was
16701 selected and a new cookie was emitted in the response.
16702
16703 VI The server designated by the cookie was not marked dead but could not
16704 be reached. A redispatch happened and selected another one, which was
16705 then advertised in the response.
16706
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016707
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200167088.6. Non-printable characters
16709-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016710
16711In order not to cause trouble to log analysis tools or terminals during log
16712consulting, non-printable characters are not sent as-is into log files, but are
16713converted to the two-digits hexadecimal representation of their ASCII code,
16714prefixed by the character '#'. The only characters that can be logged without
16715being escaped are comprised between 32 and 126 (inclusive). Obviously, the
16716escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
16717is the same for the character '"' which becomes "#22", as well as '{', '|' and
16718'}' when logging headers.
16719
16720Note that the space character (' ') is not encoded in headers, which can cause
16721issues for tools relying on space count to locate fields. A typical header
16722containing spaces is "User-Agent".
16723
16724Last, it has been observed that some syslog daemons such as syslog-ng escape
16725the quote ('"') with a backslash ('\'). The reverse operation can safely be
16726performed since no quote may appear anywhere else in the logs.
16727
16728
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200167298.7. Capturing HTTP cookies
16730---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016731
16732Cookie capture simplifies the tracking a complete user session. This can be
16733achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016734section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016735cookie will simultaneously be checked in the request ("Cookie:" header) and in
16736the response ("Set-Cookie:" header). The respective values will be reported in
16737the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016738locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016739not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
16740user switches to a new session for example, because the server will reassign it
16741a new cookie. It is also possible to detect if a server unexpectedly sets a
16742wrong cookie to a client, leading to session crossing.
16743
16744 Examples :
16745 # capture the first cookie whose name starts with "ASPSESSION"
16746 capture cookie ASPSESSION len 32
16747
16748 # capture the first cookie whose name is exactly "vgnvisitor"
16749 capture cookie vgnvisitor= len 32
16750
16751
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200167528.8. Capturing HTTP headers
16753---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016754
16755Header captures are useful to track unique request identifiers set by an upper
16756proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
16757the response, one can search for information about the response length, how the
16758server asked the cache to behave, or an object location during a redirection.
16759
16760Header captures are performed using the "capture request header" and "capture
16761response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016762section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016763
16764It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010016765time. Non-existent headers are logged as empty strings, and if one header
16766appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016767are grouped within braces '{' and '}' in the same order as they were declared,
16768and delimited with a vertical bar '|' without any space. Response headers
16769follow the same representation, but are displayed after a space following the
16770request headers block. These blocks are displayed just before the HTTP request
16771in the logs.
16772
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020016773As a special case, it is possible to specify an HTTP header capture in a TCP
16774frontend. The purpose is to enable logging of headers which will be parsed in
16775an HTTP backend if the request is then switched to this HTTP backend.
16776
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016777 Example :
16778 # This instance chains to the outgoing proxy
16779 listen proxy-out
16780 mode http
16781 option httplog
16782 option logasap
16783 log global
16784 server cache1 192.168.1.1:3128
16785
16786 # log the name of the virtual server
16787 capture request header Host len 20
16788
16789 # log the amount of data uploaded during a POST
16790 capture request header Content-Length len 10
16791
16792 # log the beginning of the referrer
16793 capture request header Referer len 20
16794
16795 # server name (useful for outgoing proxies only)
16796 capture response header Server len 20
16797
16798 # logging the content-length is useful with "option logasap"
16799 capture response header Content-Length len 10
16800
16801 # log the expected cache behaviour on the response
16802 capture response header Cache-Control len 8
16803
16804 # the Via header will report the next proxy's name
16805 capture response header Via len 20
16806
16807 # log the URL location during a redirection
16808 capture response header Location len 20
16809
16810 >>> Aug 9 20:26:09 localhost \
16811 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
16812 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
16813 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
16814 "GET http://fr.adserver.yahoo.com/"
16815
16816 >>> Aug 9 20:30:46 localhost \
16817 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
16818 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
16819 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010016820 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016821
16822 >>> Aug 9 20:30:46 localhost \
16823 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
16824 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
16825 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
16826 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010016827 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016828
16829
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200168308.9. Examples of logs
16831---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016832
16833These are real-world examples of logs accompanied with an explanation. Some of
16834them have been made up by hand. The syslog part has been removed for better
16835reading. Their sole purpose is to explain how to decipher them.
16836
16837 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
16838 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
16839 "HEAD / HTTP/1.0"
16840
16841 => long request (6.5s) entered by hand through 'telnet'. The server replied
16842 in 147 ms, and the session ended normally ('----')
16843
16844 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
16845 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
16846 0/9 "HEAD / HTTP/1.0"
16847
16848 => Idem, but the request was queued in the global queue behind 9 other
16849 requests, and waited there for 1230 ms.
16850
16851 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
16852 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
16853 "GET /image.iso HTTP/1.0"
16854
16855 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010016856 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016857 14 ms, 243 bytes of headers were sent to the client, and total time from
16858 accept to first data byte is 30 ms.
16859
16860 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
16861 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
16862 "GET /cgi-bin/bug.cgi? HTTP/1.0"
16863
16864 => the proxy blocked a server response either because of an "rspdeny" or
16865 "rspideny" filter, or because the response was improperly formatted and
Willy Tarreau3c92c5f2011-08-28 09:45:47 +020016866 not HTTP-compliant, or because it blocked sensitive information which
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016867 risked being cached. In this case, the response is replaced with a "502
16868 bad gateway". The flags ("PH--") tell us that it was haproxy who decided
16869 to return the 502 and not the server.
16870
16871 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +010016872 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 +010016873
16874 => the client never completed its request and aborted itself ("C---") after
16875 8.5s, while the proxy was waiting for the request headers ("-R--").
16876 Nothing was sent to any server.
16877
16878 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
16879 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
16880
16881 => The client never completed its request, which was aborted by the
16882 time-out ("c---") after 50s, while the proxy was waiting for the request
16883 headers ("-R--"). Nothing was sent to any server, but the proxy could
16884 send a 408 return code to the client.
16885
16886 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
16887 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
16888
16889 => This log was produced with "option tcplog". The client timed out after
16890 5 seconds ("c----").
16891
16892 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
16893 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +010016894 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016895
16896 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016897 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +010016898 (config says 'retries 3'), and no redispatch (otherwise we would have
16899 seen "/+3"). Status code 503 was returned to the client. There were 115
16900 connections on this server, 202 connections on this proxy, and 205 on
16901 the global process. It is possible that the server refused the
16902 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +010016903
Willy Tarreau52b2d222011-09-07 23:48:48 +020016904
Christopher Fauletc3fe5332016-04-07 15:30:10 +0200169059. Supported filters
16906--------------------
16907
16908Here are listed officially supported filters with the list of parameters they
16909accept. Depending on compile options, some of these filters might be
16910unavailable. The list of available filters is reported in haproxy -vv.
16911
16912See also : "filter"
16913
169149.1. Trace
16915----------
16916
Christopher Faulet31bfe1f2016-12-09 17:42:38 +010016917filter trace [name <name>] [random-parsing] [random-forwarding] [hexdump]
Christopher Fauletc3fe5332016-04-07 15:30:10 +020016918
16919 Arguments:
16920 <name> is an arbitrary name that will be reported in
16921 messages. If no name is provided, "TRACE" is used.
16922
16923 <random-parsing> enables the random parsing of data exchanged between
16924 the client and the server. By default, this filter
16925 parses all available data. With this parameter, it
16926 only parses a random amount of the available data.
16927
16928 <random-forwarding> enables the random forwading of parsed data. By
16929 default, this filter forwards all previously parsed
16930 data. With this parameter, it only forwards a random
16931 amount of the parsed data.
16932
Christopher Faulet31bfe1f2016-12-09 17:42:38 +010016933 <hexump> dumps all forwarded data to the server and the client.
16934
Christopher Fauletc3fe5332016-04-07 15:30:10 +020016935This filter can be used as a base to develop new filters. It defines all
16936callbacks and print a message on the standard error stream (stderr) with useful
16937information for all of them. It may be useful to debug the activity of other
16938filters or, quite simply, HAProxy's activity.
16939
16940Using <random-parsing> and/or <random-forwarding> parameters is a good way to
16941tests the behavior of a filter that parses data exchanged between a client and
16942a server by adding some latencies in the processing.
16943
16944
169459.2. HTTP compression
16946---------------------
16947
16948filter compression
16949
16950The HTTP compression has been moved in a filter in HAProxy 1.7. "compression"
16951keyword must still be used to enable and configure the HTTP compression. And
16952when no other filter is used, it is enough. But it is mandatory to explicitly
16953use a filter line to enable the HTTP compression when two or more filters are
16954used for the same listener/frontend/backend. This is important to know the
16955filters evaluation order.
16956
16957See also : "compression"
16958
16959
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200169609.3. Stream Processing Offload Engine (SPOE)
16961--------------------------------------------
16962
16963filter spoe [engine <name>] config <file>
16964
16965 Arguments :
16966
16967 <name> is the engine name that will be used to find the right scope in
16968 the configuration file. If not provided, all the file will be
16969 parsed.
16970
16971 <file> is the path of the engine configuration file. This file can
16972 contain configuration of several engines. In this case, each
16973 part must be placed in its own scope.
16974
16975The Stream Processing Offload Engine (SPOE) is a filter communicating with
16976external components. It allows the offload of some specifics processing on the
16977streams in tierce applications. These external components and information
16978exchanged with them are configured in dedicated files, for the main part. It
16979also requires dedicated backends, defined in HAProxy configuration.
16980
16981SPOE communicates with external components using an in-house binary protocol,
16982the Stream Processing Offload Protocol (SPOP).
16983
Tim Düsterhus4896c442016-11-29 02:15:19 +010016984For all information about the SPOE configuration and the SPOP specification, see
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020016985"doc/SPOE.txt".
16986
16987Important note:
16988 The SPOE filter is highly experimental for now and was not heavily
16989 tested. It is really not production ready. So use it carefully.
16990
William Lallemand86d0df02017-11-24 21:36:45 +01001699110. Cache
16992---------
16993
16994HAProxy provides a cache, which was designed to perform cache on small objects
16995(favicon, css...). This is a minimalist low-maintenance cache which runs in
16996RAM.
16997
16998The cache is based on a memory which is shared between processes and threads,
Cyril Bonté7b888f12017-11-26 22:24:31 +010016999this memory is split in blocks of 1k.
William Lallemand86d0df02017-11-24 21:36:45 +010017000
17001If an object is not used anymore, it can be deleted to store a new object
17002independently of its expiration date. The oldest objects are deleted first
17003when we try to allocate a new one.
17004
Cyril Bonté7b888f12017-11-26 22:24:31 +010017005The cache uses a hash of the host header and the URI as the key.
William Lallemand86d0df02017-11-24 21:36:45 +010017006
17007It's possible to view the status of a cache using the Unix socket command
17008"show cache" consult section 9.3 "Unix Socket commands" of Management Guide
17009for more details.
17010
17011When an object is delivered from the cache, the server name in the log is
17012replaced by "<CACHE>".
17013
Cyril Bonté7b888f12017-11-26 22:24:31 +01001701410.1. Limitation
17015----------------
William Lallemand86d0df02017-11-24 21:36:45 +010017016
17017The cache won't store and won't deliver objects in these cases:
17018
17019- If the response is not a 200
17020- If the response contains a Vary header
17021- If the response does not contain a Content-Length header or if the
17022 Content-Length + the headers size is greater than a buffer size - the
17023 reserve.
17024- If the response is not cacheable
17025
17026- If the request is not a GET
17027- If the HTTP version of the request is smaller than 1.1
17028
17029Caution!: Due to the current limitation of the filters, it is not recommended
17030to use the cache with other filters. Using them can cause undefined behavior
Cyril Bonté7b888f12017-11-26 22:24:31 +010017031if they modify the response (compression for example).
William Lallemand86d0df02017-11-24 21:36:45 +010017032
Cyril Bonté7b888f12017-11-26 22:24:31 +01001703310.2. Setup
17034-----------
William Lallemand86d0df02017-11-24 21:36:45 +010017035
17036To setup a cache, you must define a cache section and use it in a proxy with
17037the corresponding http-request and response actions.
17038
Cyril Bonté7b888f12017-11-26 22:24:31 +01001703910.2.1. Cache section
17040---------------------
William Lallemand86d0df02017-11-24 21:36:45 +010017041
17042cache <name>
17043 Declare a cache section, allocate a shared cache memory named <name>, the
17044 size of cache is mandatory.
17045
17046total-max-size <megabytes>
17047 Define the size in RAM of the cache in megabytes. this size is splitted in
17048 blocks of 1kb which are used by the cache entries.
17049
17050max-age <seconds>
17051 Define the maximum expiration duration. The expiration is set has the lowest
17052 value between the s-maxage or max-age (in this order) directive in the
17053 Cache-Control response header and this value. The default value is 60
17054 seconds, which means that you can't cache an object more than 60 seconds by
17055 default.
17056
Cyril Bonté7b888f12017-11-26 22:24:31 +01001705710.2.2. Proxy section
17058---------------------
William Lallemand86d0df02017-11-24 21:36:45 +010017059
17060http-request cache-use <name>
17061 Try to deliver a cached object from the cache <name>. This directive is also
17062 mandatory to store the cache as it calculates the cache hash. If you want to
17063 use a condition for both storage and delivering that's a good idea to put it
17064 after this one.
17065
17066http-response cache-store <name>
17067 Store an http-response within the cache. The storage of the response headers
17068 is done at this step, which means you can use others http-response actions
17069 to modify headers before or after the storage of the response. This action
17070 is responsible for the setup of the cache storage filter.
17071
17072
17073Example:
17074
17075 backend bck1
17076 mode http
17077
17078 http-request cache-use foobar
17079 http-response cache-store foobar
17080 server srv1 127.0.0.1:80
17081
17082 cache foobar
17083 total-max-size 4
17084 max-age 240
17085
Willy Tarreau0ba27502007-12-24 16:55:16 +010017086/*
17087 * Local variables:
17088 * fill-column: 79
17089 * End:
17090 */