blob: 83f337d001879d13f122e2f66eaad9d60db61902 [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 Tarreau15480d72014-06-19 21:10:58 +02005 version 1.6
Willy Tarreau6a06a402007-07-15 20:15:28 +02006 willy tarreau
Willy Tarreau50bdda62015-07-22 17:32:56 +02007 2015/07/22
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
Willy Tarreauc57f0e22009-05-10 13:12:33 +020053
544. Proxies
554.1. Proxy keywords matrix
564.2. Alphabetically sorted keywords reference
57
Willy Tarreau086fbf52012-09-24 20:34:51 +0200585. Bind and Server options
595.1. Bind options
605.2. Server and default-server options
Baptiste Assmann1fa66662015-04-14 00:28:47 +0200615.3. Server DNS resolution
625.3.1. Global overview
635.3.2. The resolvers section
Willy Tarreauc57f0e22009-05-10 13:12:33 +020064
656. HTTP header manipulation
66
Willy Tarreau74ca5042013-06-11 23:12:07 +0200677. Using ACLs and fetching samples
687.1. ACL basics
697.1.1. Matching booleans
707.1.2. Matching integers
717.1.3. Matching strings
727.1.4. Matching regular expressions (regexes)
737.1.5. Matching arbitrary data blocks
747.1.6. Matching IPv4 and IPv6 addresses
757.2. Using ACLs to form conditions
767.3. Fetching samples
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200777.3.1. Converters
787.3.2. Fetching samples from internal states
797.3.3. Fetching samples at Layer 4
807.3.4. Fetching samples at Layer 5
817.3.5. Fetching samples from buffer contents (Layer 6)
827.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +0200837.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020084
858. Logging
868.1. Log levels
878.2. Log formats
888.2.1. Default log format
898.2.2. TCP log format
908.2.3. HTTP log format
William Lallemand48940402012-01-30 16:47:22 +0100918.2.4. Custom log format
Willy Tarreau5f51e1a2012-12-03 18:40:10 +0100928.2.5. Error log format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200938.3. Advanced logging options
948.3.1. Disabling logging of external tests
958.3.2. Logging before waiting for the session to terminate
968.3.3. Raising log level upon errors
978.3.4. Disabling logging of successful connections
988.4. Timing events
998.5. Session state at disconnection
1008.6. Non-printable characters
1018.7. Capturing HTTP cookies
1028.8. Capturing HTTP headers
1038.9. Examples of logs
104
1059. Statistics and monitoring
1069.1. CSV format
1079.2. Unix Socket commands
108
109
1101. Quick reminder about HTTP
111----------------------------
112
113When haproxy is running in HTTP mode, both the request and the response are
114fully analyzed and indexed, thus it becomes possible to build matching criteria
115on almost anything found in the contents.
116
117However, it is important to understand how HTTP requests and responses are
118formed, and how HAProxy decomposes them. It will then become easier to write
119correct rules and to debug existing configurations.
120
121
1221.1. The HTTP transaction model
123-------------------------------
124
125The HTTP protocol is transaction-driven. This means that each request will lead
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100126to one and only one response. Traditionally, a TCP connection is established
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200127from the client to the server, a request is sent by the client on the
128connection, the server responds and the connection is closed. A new request
129will involve a new connection :
130
131 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
132
133In this mode, called the "HTTP close" mode, there are as many connection
134establishments as there are HTTP transactions. Since the connection is closed
135by the server after the response, the client does not need to know the content
136length.
137
138Due to the transactional nature of the protocol, it was possible to improve it
139to avoid closing a connection between two subsequent transactions. In this mode
140however, it is mandatory that the server indicates the content length for each
141response so that the client does not wait indefinitely. For this, a special
142header is used: "Content-length". This mode is called the "keep-alive" mode :
143
144 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
145
146Its advantages are a reduced latency between transactions, and less processing
147power required on the server side. It is generally better than the close mode,
148but not always because the clients often limit their concurrent connections to
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200149a smaller value.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200150
151A last improvement in the communications is the pipelining mode. It still uses
152keep-alive, but the client does not wait for the first response to send the
153second request. This is useful for fetching large number of images composing a
154page :
155
156 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
157
158This can obviously have a tremendous benefit on performance because the network
159latency is eliminated between subsequent requests. Many HTTP agents do not
160correctly support pipelining since there is no way to associate a response with
161the corresponding request in HTTP. For this reason, it is mandatory for the
Cyril Bonté78caf842010-03-10 22:41:43 +0100162server to reply in the exact same order as the requests were received.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200163
Willy Tarreau70dffda2014-01-30 03:07:23 +0100164By default HAProxy operates in keep-alive mode with regards to persistent
165connections: for each connection it processes each request and response, and
166leaves the connection idle on both sides between the end of a response and the
167start of a new request.
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200168
Willy Tarreau70dffda2014-01-30 03:07:23 +0100169HAProxy supports 5 connection modes :
170 - keep alive : all requests and responses are processed (default)
171 - tunnel : only the first request and response are processed,
172 everything else is forwarded with no analysis.
173 - passive close : tunnel with "Connection: close" added in both directions.
174 - server close : the server-facing connection is closed after the response.
175 - forced close : the connection is actively closed after end of response.
176
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200177
1781.2. HTTP request
179-----------------
180
181First, let's consider this HTTP request :
182
183 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100184 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200185 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
186 2 Host: www.mydomain.com
187 3 User-agent: my small browser
188 4 Accept: image/jpeg, image/gif
189 5 Accept: image/png
190
191
1921.2.1. The Request line
193-----------------------
194
195Line 1 is the "request line". It is always composed of 3 fields :
196
197 - a METHOD : GET
198 - a URI : /serv/login.php?lang=en&profile=2
199 - a version tag : HTTP/1.1
200
201All of them are delimited by what the standard calls LWS (linear white spaces),
202which are commonly spaces, but can also be tabs or line feeds/carriage returns
203followed by spaces/tabs. The method itself cannot contain any colon (':') and
204is limited to alphabetic letters. All those various combinations make it
205desirable that HAProxy performs the splitting itself rather than leaving it to
206the user to write a complex or inaccurate regular expression.
207
208The URI itself can have several forms :
209
210 - A "relative URI" :
211
212 /serv/login.php?lang=en&profile=2
213
214 It is a complete URL without the host part. This is generally what is
215 received by servers, reverse proxies and transparent proxies.
216
217 - An "absolute URI", also called a "URL" :
218
219 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
220
221 It is composed of a "scheme" (the protocol name followed by '://'), a host
222 name or address, optionally a colon (':') followed by a port number, then
223 a relative URI beginning at the first slash ('/') after the address part.
224 This is generally what proxies receive, but a server supporting HTTP/1.1
225 must accept this form too.
226
227 - a star ('*') : this form is only accepted in association with the OPTIONS
228 method and is not relayable. It is used to inquiry a next hop's
229 capabilities.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100230
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200231 - an address:port combination : 192.168.0.12:80
232 This is used with the CONNECT method, which is used to establish TCP
233 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
234 other protocols too.
235
236In a relative URI, two sub-parts are identified. The part before the question
237mark is called the "path". It is typically the relative path to static objects
238on the server. The part after the question mark is called the "query string".
239It is mostly used with GET requests sent to dynamic scripts and is very
240specific to the language, framework or application in use.
241
242
2431.2.2. The request headers
244--------------------------
245
246The headers start at the second line. They are composed of a name at the
247beginning of the line, immediately followed by a colon (':'). Traditionally,
248an LWS is added after the colon but that's not required. Then come the values.
249Multiple identical headers may be folded into one single line, delimiting the
250values with commas, provided that their order is respected. This is commonly
251encountered in the "Cookie:" field. A header may span over multiple lines if
252the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
253define a total of 3 values for the "Accept:" header.
254
255Contrary to a common mis-conception, header names are not case-sensitive, and
256their values are not either if they refer to other header names (such as the
257"Connection:" header).
258
259The end of the headers is indicated by the first empty line. People often say
260that it's a double line feed, which is not exact, even if a double line feed
261is one valid form of empty line.
262
263Fortunately, HAProxy takes care of all these complex combinations when indexing
264headers, checking values and counting them, so there is no reason to worry
265about the way they could be written, but it is important not to accuse an
266application of being buggy if it does unusual, valid things.
267
268Important note:
269 As suggested by RFC2616, HAProxy normalizes headers by replacing line breaks
270 in the middle of headers by LWS in order to join multi-line headers. This
271 is necessary for proper analysis and helps less capable HTTP parsers to work
272 correctly and not to be fooled by such complex constructs.
273
274
2751.3. HTTP response
276------------------
277
278An HTTP response looks very much like an HTTP request. Both are called HTTP
279messages. Let's consider this HTTP response :
280
281 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100282 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200283 1 HTTP/1.1 200 OK
284 2 Content-length: 350
285 3 Content-Type: text/html
286
Willy Tarreau816b9792009-09-15 21:25:21 +0200287As a special case, HTTP supports so called "Informational responses" as status
288codes 1xx. These messages are special in that they don't convey any part of the
289response, they're just used as sort of a signaling message to ask a client to
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100290continue to post its request for instance. In the case of a status 100 response
291the requested information will be carried by the next non-100 response message
292following the informational one. This implies that multiple responses may be
293sent to a single request, and that this only works when keep-alive is enabled
294(1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to
295correctly forward and skip them, and only process the next non-100 response. As
296such, these messages are neither logged nor transformed, unless explicitly
297state otherwise. Status 101 messages indicate that the protocol is changing
298over the same connection and that haproxy must switch to tunnel mode, just as
299if a CONNECT had occurred. Then the Upgrade header would contain additional
300information about the type of protocol the connection is switching to.
Willy Tarreau816b9792009-09-15 21:25:21 +0200301
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200302
3031.3.1. The Response line
304------------------------
305
306Line 1 is the "response line". It is always composed of 3 fields :
307
308 - a version tag : HTTP/1.1
309 - a status code : 200
310 - a reason : OK
311
312The status code is always 3-digit. The first digit indicates a general status :
Willy Tarreau816b9792009-09-15 21:25:21 +0200313 - 1xx = informational message to be skipped (eg: 100, 101)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200314 - 2xx = OK, content is following (eg: 200, 206)
315 - 3xx = OK, no content following (eg: 302, 304)
316 - 4xx = error caused by the client (eg: 401, 403, 404)
317 - 5xx = error caused by the server (eg: 500, 502, 503)
318
319Please refer to RFC2616 for the detailed meaning of all such codes. The
Willy Tarreaud72758d2010-01-12 10:42:19 +0100320"reason" field is just a hint, but is not parsed by clients. Anything can be
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200321found there, but it's a common practice to respect the well-established
322messages. It can be composed of one or multiple words, such as "OK", "Found",
323or "Authentication Required".
324
325Haproxy may emit the following status codes by itself :
326
327 Code When / reason
328 200 access to stats page, and when replying to monitoring requests
329 301 when performing a redirection, depending on the configured code
330 302 when performing a redirection, depending on the configured code
331 303 when performing a redirection, depending on the configured code
Willy Tarreaub67fdc42013-03-29 19:28:11 +0100332 307 when performing a redirection, depending on the configured code
333 308 when performing a redirection, depending on the configured code
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200334 400 for an invalid or too large request
335 401 when an authentication is required to perform the action (when
336 accessing the stats page)
337 403 when a request is forbidden by a "block" ACL or "reqdeny" filter
338 408 when the request timeout strikes before the request is complete
339 500 when haproxy encounters an unrecoverable internal error, such as a
340 memory allocation failure, which should never happen
341 502 when the server returns an empty, invalid or incomplete response, or
342 when an "rspdeny" filter blocks the response.
343 503 when no server was available to handle the request, or in response to
344 monitoring requests which match the "monitor fail" condition
345 504 when the response timeout strikes before the server responds
346
347The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3484.2).
349
350
3511.3.2. The response headers
352---------------------------
353
354Response headers work exactly like request headers, and as such, HAProxy uses
355the same parsing function for both. Please refer to paragraph 1.2.2 for more
356details.
357
358
3592. Configuring HAProxy
360----------------------
361
3622.1. Configuration file format
363------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200364
365HAProxy's configuration process involves 3 major sources of parameters :
366
367 - the arguments from the command-line, which always take precedence
368 - the "global" section, which sets process-wide parameters
369 - the proxies sections which can take form of "defaults", "listen",
370 "frontend" and "backend".
371
Willy Tarreau0ba27502007-12-24 16:55:16 +0100372The configuration file syntax consists in lines beginning with a keyword
373referenced in this manual, optionally followed by one or several parameters
William Lallemandf9873ba2015-05-05 17:37:14 +0200374delimited by spaces.
Willy Tarreau0ba27502007-12-24 16:55:16 +0100375
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200376
William Lallemandf9873ba2015-05-05 17:37:14 +02003772.2. Quoting and escaping
378-------------------------
379
380HAProxy's configuration introduces a quoting and escaping system similar to
381many programming languages. The configuration file supports 3 types: escaping
382with a backslash, weak quoting with double quotes, and strong quoting with
383single quotes.
384
385If spaces have to be entered in strings, then they must be escaped by preceding
386them by a backslash ('\') or by quoting them. Backslashes also have to be
387escaped by doubling or strong quoting them.
388
389Escaping is achieved by preceding a special character by a backslash ('\'):
390
391 \ to mark a space and differentiate it from a delimiter
392 \# to mark a hash and differentiate it from a comment
393 \\ to use a backslash
394 \' to use a single quote and differentiate it from strong quoting
395 \" to use a double quote and differentiate it from weak quoting
396
397Weak quoting is achieved by using double quotes (""). Weak quoting prevents
398the interpretation of:
399
400 space as a parameter separator
401 ' single quote as a strong quoting delimiter
402 # hash as a comment start
403
William Lallemandb2f07452015-05-12 14:27:13 +0200404Weak quoting permits the interpretation of variables, if you want to use a non
405-interpreted dollar within a double quoted string, you should escape it with a
406backslash ("\$"), it does not work outside weak quoting.
407
408Interpretation of escaping and special characters are not prevented by weak
William Lallemandf9873ba2015-05-05 17:37:14 +0200409quoting.
410
411Strong quoting is achieved by using single quotes (''). Inside single quotes,
412nothing is interpreted, it's the efficient way to quote regexes.
413
414Quoted and escaped strings are replaced in memory by their interpreted
415equivalent, it allows you to perform concatenation.
416
417 Example:
418 # those are equivalents:
419 log-format %{+Q}o\ %t\ %s\ %{-Q}r
420 log-format "%{+Q}o %t %s %{-Q}r"
421 log-format '%{+Q}o %t %s %{-Q}r'
422 log-format "%{+Q}o %t"' %s %{-Q}r'
423 log-format "%{+Q}o %t"' %s'\ %{-Q}r
424
425 # those are equivalents:
426 reqrep "^([^\ :]*)\ /static/(.*)" \1\ /\2
427 reqrep "^([^ :]*)\ /static/(.*)" '\1 /\2'
428 reqrep "^([^ :]*)\ /static/(.*)" "\1 /\2"
429 reqrep "^([^ :]*)\ /static/(.*)" "\1\ /\2"
430
431
William Lallemandb2f07452015-05-12 14:27:13 +02004322.3. Environment variables
433--------------------------
434
435HAProxy's configuration supports environment variables. Those variables are
436interpreted only within double quotes. Variables are expanded during the
437configuration parsing. Variable names must be preceded by a dollar ("$") and
438optionally enclosed with braces ("{}") similarly to what is done in Bourne
439shell. Variable names can contain alphanumerical characters or the character
440underscore ("_") but should not start with a digit.
441
442 Example:
443
444 bind "fd@${FD_APP1}"
445
446 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
447
448 user "$HAPROXY_USER"
449
450
4512.4. Time format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200452----------------
453
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100454Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100455values are generally expressed in milliseconds (unless explicitly stated
456otherwise) but may be expressed in any other unit by suffixing the unit to the
457numeric value. It is important to consider this because it will not be repeated
458for every keyword. Supported units are :
459
460 - us : microseconds. 1 microsecond = 1/1000000 second
461 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
462 - s : seconds. 1s = 1000ms
463 - m : minutes. 1m = 60s = 60000ms
464 - h : hours. 1h = 60m = 3600s = 3600000ms
465 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
466
467
William Lallemandf9873ba2015-05-05 17:37:14 +02004682.4. Examples
Patrick Mezard35da19c2010-06-12 17:02:47 +0200469-------------
470
471 # Simple configuration for an HTTP proxy listening on port 80 on all
472 # interfaces and forwarding requests to a single backend "servers" with a
473 # single server "server1" listening on 127.0.0.1:8000
474 global
475 daemon
476 maxconn 256
477
478 defaults
479 mode http
480 timeout connect 5000ms
481 timeout client 50000ms
482 timeout server 50000ms
483
484 frontend http-in
485 bind *:80
486 default_backend servers
487
488 backend servers
489 server server1 127.0.0.1:8000 maxconn 32
490
491
492 # The same configuration defined with a single listen block. Shorter but
493 # less expressive, especially in HTTP mode.
494 global
495 daemon
496 maxconn 256
497
498 defaults
499 mode http
500 timeout connect 5000ms
501 timeout client 50000ms
502 timeout server 50000ms
503
504 listen http-in
505 bind *:80
506 server server1 127.0.0.1:8000 maxconn 32
507
508
509Assuming haproxy is in $PATH, test these configurations in a shell with:
510
Willy Tarreauccb289d2010-12-11 20:19:38 +0100511 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200512
513
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005143. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200515--------------------
516
517Parameters in the "global" section are process-wide and often OS-specific. They
518are generally set once for all and do not need being changed once correct. Some
519of them have command-line equivalents.
520
521The following keywords are supported in the "global" section :
522
523 * Process management and security
Emeric Brunc8e8d122012-10-02 18:42:10 +0200524 - ca-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200525 - chroot
Emeric Brunc8e8d122012-10-02 18:42:10 +0200526 - crt-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200527 - daemon
Simon Horman98637e52014-06-20 12:30:16 +0900528 - external-check
Willy Tarreau6a06a402007-07-15 20:15:28 +0200529 - gid
530 - group
531 - log
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100532 - log-send-hostname
Willy Tarreau6a06a402007-07-15 20:15:28 +0200533 - nbproc
534 - pidfile
535 - uid
536 - ulimit-n
537 - user
Willy Tarreaufbee7132007-10-18 13:53:22 +0200538 - stats
Emeric Brun850efd52014-01-29 12:24:34 +0100539 - ssl-server-verify
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200540 - node
541 - description
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100542 - unix-bind
Thomas Holmesdb04f192015-05-18 13:21:39 +0100543 - 51degrees-data-file
544 - 51degrees-property-name-list
Dragan Dosen93b38d92015-06-29 16:43:25 +0200545 - 51degrees-property-separator
Dragan Dosenae6d39a2015-06-29 16:43:27 +0200546 - 51degrees-cache-size
Willy Tarreaud72758d2010-01-12 10:42:19 +0100547
Willy Tarreau6a06a402007-07-15 20:15:28 +0200548 * Performance tuning
Willy Tarreau1746eec2014-04-25 10:46:47 +0200549 - max-spread-checks
Willy Tarreau6a06a402007-07-15 20:15:28 +0200550 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +0200551 - maxconnrate
William Lallemandd85f9172012-11-09 17:05:39 +0100552 - maxcomprate
William Lallemand072a2bf2012-11-20 17:01:01 +0100553 - maxcompcpuusage
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100554 - maxpipes
Willy Tarreau93e7c002013-10-07 18:51:07 +0200555 - maxsessrate
Willy Tarreau403edff2012-09-06 11:58:37 +0200556 - maxsslconn
Willy Tarreaue43d5322013-10-07 20:01:52 +0200557 - maxsslrate
Willy Tarreau6a06a402007-07-15 20:15:28 +0200558 - noepoll
559 - nokqueue
560 - nopoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100561 - nosplice
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300562 - nogetaddrinfo
Willy Tarreaufe255b72007-10-14 23:09:26 +0200563 - spread-checks
Willy Tarreau27a674e2009-08-17 07:23:33 +0200564 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200565 - tune.chksize
William Lallemandf3747832012-11-09 12:33:10 +0100566 - tune.comp.maxlevel
Willy Tarreau193b8c62012-11-22 00:17:38 +0100567 - tune.http.cookielen
Willy Tarreauac1932d2011-10-24 19:14:41 +0200568 - tune.http.maxhdr
Willy Tarreau7e312732014-02-12 16:35:14 +0100569 - tune.idletimer
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100570 - tune.lua.forced-yield
Willy Tarreau32f61e22015-03-18 17:54:59 +0100571 - tune.lua.maxmem
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100572 - tune.lua.session-timeout
573 - tune.lua.task-timeout
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100574 - tune.maxaccept
575 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200576 - tune.maxrewrite
Willy Tarreauf3045d22015-04-29 16:24:50 +0200577 - tune.pattern.cache-size
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200578 - tune.pipesize
Willy Tarreaue803de22010-01-21 17:43:04 +0100579 - tune.rcvbuf.client
580 - tune.rcvbuf.server
581 - tune.sndbuf.client
582 - tune.sndbuf.server
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100583 - tune.ssl.cachesize
Willy Tarreaubfd59462013-02-21 07:46:09 +0100584 - tune.ssl.lifetime
Emeric Brun8dc60392014-05-09 13:52:00 +0200585 - tune.ssl.force-private-cache
Willy Tarreaubfd59462013-02-21 07:46:09 +0100586 - tune.ssl.maxrecord
Remi Gacognef46cd6e2014-06-12 14:58:40 +0200587 - tune.ssl.default-dh-param
Christopher Faulet31af49d2015-06-09 17:29:50 +0200588 - tune.ssl.ssl-ctx-cache-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +0200589 - tune.vars.global-max-size
590 - tune.vars.reqres-max-size
591 - tune.vars.sess-max-size
592 - tune.vars.txn-max-size
William Lallemanda509e4c2012-11-07 16:54:34 +0100593 - tune.zlib.memlevel
594 - tune.zlib.windowsize
Willy Tarreaud72758d2010-01-12 10:42:19 +0100595
Willy Tarreau6a06a402007-07-15 20:15:28 +0200596 * Debugging
597 - debug
598 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200599
600
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006013.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200602------------------------------------
603
Emeric Brunc8e8d122012-10-02 18:42:10 +0200604ca-base <dir>
605 Assigns a default directory to fetch SSL CA certificates and CRLs from when a
Emeric Brunfd33a262012-10-11 16:28:27 +0200606 relative path is used with "ca-file" or "crl-file" directives. Absolute
607 locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200608
Willy Tarreau6a06a402007-07-15 20:15:28 +0200609chroot <jail dir>
610 Changes current directory to <jail dir> and performs a chroot() there before
611 dropping privileges. This increases the security level in case an unknown
612 vulnerability would be exploited, since it would make it very hard for the
613 attacker to exploit the system. This only works when the process is started
614 with superuser privileges. It is important to ensure that <jail_dir> is both
615 empty and unwritable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100616
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100617cpu-map <"all"|"odd"|"even"|process_num> <cpu-set>...
618 On Linux 2.6 and above, it is possible to bind a process to a specific CPU
619 set. This means that the process will never run on other CPUs. The "cpu-map"
620 directive specifies CPU sets for process sets. The first argument is the
Willy Tarreaua9db57e2013-01-18 11:29:29 +0100621 process number to bind. This process must have a number between 1 and 32 or
622 64, depending on the machine's word size, and any process IDs above nbproc
623 are ignored. It is possible to specify all processes at once using "all",
624 only odd numbers using "odd" or even numbers using "even", just like with the
625 "bind-process" directive. The second and forthcoming arguments are CPU sets.
626 Each CPU set is either a unique number between 0 and 31 or 63 or a range with
627 two such numbers delimited by a dash ('-'). Multiple CPU numbers or ranges
628 may be specified, and the processes will be allowed to bind to all of them.
629 Obviously, multiple "cpu-map" directives may be specified. Each "cpu-map"
630 directive will replace the previous ones when they overlap.
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100631
Emeric Brunc8e8d122012-10-02 18:42:10 +0200632crt-base <dir>
633 Assigns a default directory to fetch SSL certificates from when a relative
634 path is used with "crtfile" directives. Absolute locations specified after
635 "crtfile" prevail and ignore "crt-base".
636
Willy Tarreau6a06a402007-07-15 20:15:28 +0200637daemon
638 Makes the process fork into background. This is the recommended mode of
639 operation. It is equivalent to the command line "-D" argument. It can be
640 disabled by the command line "-db" argument.
641
David Carlier8167f302015-06-01 13:50:06 +0200642deviceatlas-json-file <path>
643 Sets the path of the DeviceAtlas JSON data file to be loaded by the API.
644 The path must be a valid JSON data file and accessible by Haproxy process.
645
646deviceatlas-log-level <value>
647 Sets the level of informations returned by the API. This directive is
648 optional and set to 0 by default if not set.
649
650deviceatlas-separator <char>
651 Sets the character separator for the API properties results. This directive
652 is optional and set to | by default if not set.
653
Simon Horman98637e52014-06-20 12:30:16 +0900654external-check
655 Allows the use of an external agent to perform health checks.
656 This is disabled by default as a security precaution.
657 See "option external-check".
658
Willy Tarreau6a06a402007-07-15 20:15:28 +0200659gid <number>
660 Changes the process' group ID to <number>. It is recommended that the group
661 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
662 be started with a user belonging to this group, or with superuser privileges.
Michael Schererab012dd2013-01-12 18:35:19 +0100663 Note that if haproxy is started from a user having supplementary groups, it
664 will only be able to drop these groups if started with superuser privileges.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200665 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100666
Willy Tarreau6a06a402007-07-15 20:15:28 +0200667group <group name>
668 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
669 See also "gid" and "user".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100670
Willy Tarreau18324f52014-06-27 18:10:07 +0200671log <address> [len <length>] <facility> [max level [min level]]
Willy Tarreau6a06a402007-07-15 20:15:28 +0200672 Adds a global syslog server. Up to two global servers can be defined. They
673 will receive logs for startups and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100674 configured with "log global".
675
676 <address> can be one of:
677
Willy Tarreau2769aa02007-12-27 18:26:09 +0100678 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100679 no port is specified, 514 is used by default (the standard syslog
680 port).
681
David du Colombier24bb5f52011-03-17 10:40:23 +0100682 - An IPv6 address followed by a colon and optionally a UDP port. If
683 no port is specified, 514 is used by default (the standard syslog
684 port).
685
Robert Tsai81ae1952007-12-05 10:47:29 +0100686 - A filesystem path to a UNIX domain socket, keeping in mind
687 considerations for chroot (be sure the path is accessible inside
688 the chroot) and uid/gid (be sure the path is appropriately
689 writeable).
690
William Lallemandb2f07452015-05-12 14:27:13 +0200691 You may want to reference some environment variables in the address
692 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +0100693
Willy Tarreau18324f52014-06-27 18:10:07 +0200694 <length> is an optional maximum line length. Log lines larger than this value
695 will be truncated before being sent. The reason is that syslog
696 servers act differently on log line length. All servers support the
697 default value of 1024, but some servers simply drop larger lines
698 while others do log them. If a server supports long lines, it may
699 make sense to set this value here in order to avoid truncating long
700 lines. Similarly, if a server drops long lines, it is preferable to
701 truncate them before sending them. Accepted values are 80 to 65535
702 inclusive. The default value of 1024 is generally fine for all
703 standard usages. Some specific cases of long captures or
704 JSON-formated logs may require larger values.
705
Robert Tsai81ae1952007-12-05 10:47:29 +0100706 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200707
708 kern user mail daemon auth syslog lpr news
709 uucp cron auth2 ftp ntp audit alert cron2
710 local0 local1 local2 local3 local4 local5 local6 local7
711
712 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200713 all messages are sent. If a maximum level is specified, only messages with a
714 severity at least as important as this level will be sent. An optional minimum
715 level can be specified. If it is set, logs emitted with a more severe level
716 than this one will be capped to this level. This is used to avoid sending
717 "emerg" messages on all terminals on some default syslog configurations.
718 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200719
Cyril Bontédc4d9032012-04-08 21:57:39 +0200720 emerg alert crit err warning notice info debug
Willy Tarreau6a06a402007-07-15 20:15:28 +0200721
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100722log-send-hostname [<string>]
723 Sets the hostname field in the syslog header. If optional "string" parameter
724 is set the header is set to the string contents, otherwise uses the hostname
725 of the system. Generally used if one is not relaying logs through an
726 intermediate syslog server or for simply customizing the hostname printed in
727 the logs.
728
Kevinm48936af2010-12-22 16:08:21 +0000729log-tag <string>
730 Sets the tag field in the syslog header to this string. It defaults to the
731 program name as launched from the command line, which usually is "haproxy".
732 Sometimes it can be useful to differentiate between multiple processes
Willy Tarreau094af4e2015-01-07 15:03:42 +0100733 running on the same host. See also the per-proxy "log-tag" directive.
Kevinm48936af2010-12-22 16:08:21 +0000734
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100735lua-load <file>
736 This global directive loads and executes a Lua file. This directive can be
737 used multiple times.
738
Willy Tarreau6a06a402007-07-15 20:15:28 +0200739nbproc <number>
740 Creates <number> processes when going daemon. This requires the "daemon"
741 mode. By default, only one process is created, which is the recommended mode
742 of operation. For systems limited to small sets of file descriptors per
743 process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES
744 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon".
745
746pidfile <pidfile>
747 Writes pids of all daemons into file <pidfile>. This option is equivalent to
748 the "-p" command line argument. The file must be accessible to the user
749 starting the process. See also "daemon".
750
Willy Tarreaua9db57e2013-01-18 11:29:29 +0100751stats bind-process [ all | odd | even | <number 1-64>[-<number 1-64>] ] ...
Willy Tarreau35b7b162012-10-22 23:17:18 +0200752 Limits the stats socket to a certain set of processes numbers. By default the
753 stats socket is bound to all processes, causing a warning to be emitted when
754 nbproc is greater than 1 because there is no way to select the target process
755 when connecting. However, by using this setting, it becomes possible to pin
756 the stats socket to a specific set of processes, typically the first one. The
757 warning will automatically be disabled when this setting is used, whatever
Willy Tarreaua9db57e2013-01-18 11:29:29 +0100758 the number of processes used. The maximum process ID depends on the machine's
Willy Tarreauae302532014-05-07 19:22:24 +0200759 word size (32 or 64). A better option consists in using the "process" setting
760 of the "stats socket" line to force the process on each line.
Willy Tarreau35b7b162012-10-22 23:17:18 +0200761
Willy Tarreau610f04b2014-02-13 11:36:41 +0100762ssl-default-bind-ciphers <ciphers>
763 This setting is only available when support for OpenSSL was built in. It sets
764 the default string describing the list of cipher algorithms ("cipher suite")
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300765 that are negotiated during the SSL/TLS handshake for all "bind" lines which
Willy Tarreau610f04b2014-02-13 11:36:41 +0100766 do not explicitly define theirs. The format of the string is defined in
767 "man 1 ciphers" from OpenSSL man pages, and can be for instance a string such
768 as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes). Please check the
769 "bind" keyword for more information.
770
Emeric Brun2c86cbf2014-10-30 15:56:50 +0100771ssl-default-bind-options [<option>]...
772 This setting is only available when support for OpenSSL was built in. It sets
773 default ssl-options to force on all "bind" lines. Please check the "bind"
774 keyword to see available options.
775
776 Example:
777 global
778 ssl-default-bind-options no-sslv3 no-tls-tickets
779
Willy Tarreau610f04b2014-02-13 11:36:41 +0100780ssl-default-server-ciphers <ciphers>
781 This setting is only available when support for OpenSSL was built in. It
782 sets the default string describing the list of cipher algorithms that are
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300783 negotiated during the SSL/TLS handshake with the server, for all "server"
Willy Tarreau610f04b2014-02-13 11:36:41 +0100784 lines which do not explicitly define theirs. The format of the string is
785 defined in "man 1 ciphers". Please check the "server" keyword for more
786 information.
787
Emeric Brun2c86cbf2014-10-30 15:56:50 +0100788ssl-default-server-options [<option>]...
789 This setting is only available when support for OpenSSL was built in. It sets
790 default ssl-options to force on all "server" lines. Please check the "server"
791 keyword to see available options.
792
Remi Gacogne47783ef2015-05-29 15:53:22 +0200793ssl-dh-param-file <file>
794 This setting is only available when support for OpenSSL was built in. It sets
795 the default DH parameters that are used during the SSL/TLS handshake when
796 ephemeral Diffie-Hellman (DHE) key exchange is used, for all "bind" lines
797 which do not explicitely define theirs. It will be overridden by custom DH
798 parameters found in a bind certificate file if any. If custom DH parameters
799 are not specified either by using ssl-dh-param-file or by setting them directly
800 in the certificate file, pre-generated DH parameters of the size specified
801 by tune.ssl.default-dh-param will be used. Custom parameters are known to be
802 more secure and therefore their use is recommended.
803 Custom DH parameters may be generated by using the OpenSSL command
804 "openssl dhparam <size>", where size should be at least 2048, as 1024-bit DH
805 parameters should not be considered secure anymore.
806
Emeric Brun850efd52014-01-29 12:24:34 +0100807ssl-server-verify [none|required]
808 The default behavior for SSL verify on servers side. If specified to 'none',
809 servers certificates are not verified. The default is 'required' except if
810 forced using cmdline option '-dV'.
811
Willy Tarreauabb175f2012-09-24 12:43:26 +0200812stats socket [<address:port>|<path>] [param*]
813 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
814 Connections to this socket will return various statistics outputs and even
815 allow some commands to be issued to change some runtime settings. Please
816 consult section 9.2 "Unix Socket commands" for more details.
Willy Tarreau6162db22009-10-10 17:13:00 +0200817
Willy Tarreauabb175f2012-09-24 12:43:26 +0200818 All parameters supported by "bind" lines are supported, for instance to
819 restrict access to some users or their access rights. Please consult
820 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200821
822stats timeout <timeout, in milliseconds>
823 The default timeout on the stats socket is set to 10 seconds. It is possible
824 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +0100825 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200826
827stats maxconn <connections>
828 By default, the stats socket is limited to 10 concurrent connections. It is
829 possible to change this value with "stats maxconn".
830
Willy Tarreau6a06a402007-07-15 20:15:28 +0200831uid <number>
832 Changes the process' user ID to <number>. It is recommended that the user ID
833 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
834 be started with superuser privileges in order to be able to switch to another
835 one. See also "gid" and "user".
836
837ulimit-n <number>
838 Sets the maximum number of per-process file-descriptors to <number>. By
839 default, it is automatically computed, so it is recommended not to use this
840 option.
841
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100842unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
843 [ group <group> ] [ gid <gid> ]
844
845 Fixes common settings to UNIX listening sockets declared in "bind" statements.
846 This is mainly used to simplify declaration of those UNIX sockets and reduce
847 the risk of errors, since those settings are most commonly required but are
848 also process-specific. The <prefix> setting can be used to force all socket
849 path to be relative to that directory. This might be needed to access another
850 component's chroot. Note that those paths are resolved before haproxy chroots
851 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
852 all have the same meaning as their homonyms used by the "bind" statement. If
853 both are specified, the "bind" statement has priority, meaning that the
854 "unix-bind" settings may be seen as process-wide default settings.
855
Willy Tarreau6a06a402007-07-15 20:15:28 +0200856user <user name>
857 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
858 See also "uid" and "group".
859
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200860node <name>
861 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
862
863 This statement is useful in HA configurations where two or more processes or
864 servers share the same IP address. By setting a different node-name on all
865 nodes, it becomes easy to immediately spot what server is handling the
866 traffic.
867
868description <text>
869 Add a text that describes the instance.
870
871 Please note that it is required to escape certain characters (# for example)
872 and this text is inserted into a html page so you should avoid using
873 "<" and ">" characters.
874
Thomas Holmesdb04f192015-05-18 13:21:39 +010087551degrees-data-file <file path>
876 The path of the 51Degrees data file to provide device detection services. The
877 file should be unzipped and accessible by HAProxy with relevavnt permissions.
878
Dragan Dosenae6d39a2015-06-29 16:43:27 +0200879 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +0100880 compiled with USE_51DEGREES.
881
88251degrees-property-name-list [<string>]
883 A list of 51Degrees property names to be load from the dataset. A full list
884 of names is available on the 51Degrees website:
885 https://51degrees.com/resources/property-dictionary
886
Dragan Dosenae6d39a2015-06-29 16:43:27 +0200887 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +0100888 compiled with USE_51DEGREES.
889
Dragan Dosen93b38d92015-06-29 16:43:25 +020089051degrees-property-separator <char>
Thomas Holmesdb04f192015-05-18 13:21:39 +0100891 A char that will be appended to every property value in a response header
892 containing 51Degrees results. If not set that will be set as ','.
893
Dragan Dosenae6d39a2015-06-29 16:43:27 +0200894 Please note that this option is only available when haproxy has been
895 compiled with USE_51DEGREES.
896
89751degrees-cache-size <number>
898 Sets the size of the 51Degrees converter cache to <number> entries. This
899 is an LRU cache which reminds previous device detections and their results.
900 By default, this cache is disabled.
901
902 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +0100903 compiled with USE_51DEGREES.
904
Willy Tarreau6a06a402007-07-15 20:15:28 +0200905
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009063.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +0200907-----------------------
908
Willy Tarreau1746eec2014-04-25 10:46:47 +0200909max-spread-checks <delay in milliseconds>
910 By default, haproxy tries to spread the start of health checks across the
911 smallest health check interval of all the servers in a farm. The principle is
912 to avoid hammering services running on the same server. But when using large
913 check intervals (10 seconds or more), the last servers in the farm take some
914 time before starting to be tested, which can be a problem. This parameter is
915 used to enforce an upper bound on delay between the first and the last check,
916 even if the servers' check intervals are larger. When servers run with
917 shorter intervals, their intervals will be respected though.
918
Willy Tarreau6a06a402007-07-15 20:15:28 +0200919maxconn <number>
920 Sets the maximum per-process number of concurrent connections to <number>. It
921 is equivalent to the command-line argument "-n". Proxies will stop accepting
922 connections when this limit is reached. The "ulimit-n" parameter is
Willy Tarreau8274e102014-06-19 15:31:25 +0200923 automatically adjusted according to this value. See also "ulimit-n". Note:
924 the "select" poller cannot reliably use more than 1024 file descriptors on
925 some platforms. If your platform only supports select and reports "select
926 FAILED" on startup, you need to reduce maxconn until it works (slightly
Willy Tarreaud0256482015-01-15 21:45:22 +0100927 below 500 in general). If this value is not set, it will default to the value
928 set in DEFAULT_MAXCONN at build time (reported in haproxy -vv) if no memory
929 limit is enforced, or will be computed based on the memory limit, the buffer
930 size, memory allocated to compression, SSL cache size, and use or not of SSL
931 and the associated maxsslconn (which can also be automatic).
Willy Tarreau6a06a402007-07-15 20:15:28 +0200932
Willy Tarreau81c25d02011-09-07 15:17:21 +0200933maxconnrate <number>
934 Sets the maximum per-process number of connections per second to <number>.
935 Proxies will stop accepting connections when this limit is reached. It can be
936 used to limit the global capacity regardless of each frontend capacity. It is
937 important to note that this can only be used as a service protection measure,
938 as there will not necessarily be a fair share between frontends when the
939 limit is reached, so it's a good idea to also limit each frontend to some
940 value close to its expected share. Also, lowering tune.maxaccept can improve
941 fairness.
942
William Lallemandd85f9172012-11-09 17:05:39 +0100943maxcomprate <number>
944 Sets the maximum per-process input compression rate to <number> kilobytes
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300945 per second. For each session, if the maximum is reached, the compression
William Lallemandd85f9172012-11-09 17:05:39 +0100946 level will be decreased during the session. If the maximum is reached at the
947 beginning of a session, the session will not compress at all. If the maximum
948 is not reached, the compression level will be increased up to
949 tune.comp.maxlevel. A value of zero means there is no limit, this is the
950 default value.
951
William Lallemand072a2bf2012-11-20 17:01:01 +0100952maxcompcpuusage <number>
953 Sets the maximum CPU usage HAProxy can reach before stopping the compression
954 for new requests or decreasing the compression level of current requests.
955 It works like 'maxcomprate' but measures CPU usage instead of incoming data
956 bandwidth. The value is expressed in percent of the CPU used by haproxy. In
957 case of multiple processes (nbproc > 1), each process manages its individual
958 usage. A value of 100 disable the limit. The default value is 100. Setting
959 a lower value will prevent the compression work from slowing the whole
960 process down and from introducing high latencies.
961
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100962maxpipes <number>
963 Sets the maximum per-process number of pipes to <number>. Currently, pipes
964 are only used by kernel-based tcp splicing. Since a pipe contains two file
965 descriptors, the "ulimit-n" value will be increased accordingly. The default
966 value is maxconn/4, which seems to be more than enough for most heavy usages.
967 The splice code dynamically allocates and releases pipes, and can fall back
968 to standard copy, so setting this value too low may only impact performance.
969
Willy Tarreau93e7c002013-10-07 18:51:07 +0200970maxsessrate <number>
971 Sets the maximum per-process number of sessions per second to <number>.
972 Proxies will stop accepting connections when this limit is reached. It can be
973 used to limit the global capacity regardless of each frontend capacity. It is
974 important to note that this can only be used as a service protection measure,
975 as there will not necessarily be a fair share between frontends when the
976 limit is reached, so it's a good idea to also limit each frontend to some
977 value close to its expected share. Also, lowering tune.maxaccept can improve
978 fairness.
979
Willy Tarreau403edff2012-09-06 11:58:37 +0200980maxsslconn <number>
981 Sets the maximum per-process number of concurrent SSL connections to
982 <number>. By default there is no SSL-specific limit, which means that the
983 global maxconn setting will apply to all connections. Setting this limit
984 avoids having openssl use too much memory and crash when malloc returns NULL
985 (since it unfortunately does not reliably check for such conditions). Note
986 that the limit applies both to incoming and outgoing connections, so one
987 connection which is deciphered then ciphered accounts for 2 SSL connections.
Willy Tarreaud0256482015-01-15 21:45:22 +0100988 If this value is not set, but a memory limit is enforced, this value will be
989 automatically computed based on the memory limit, maxconn, the buffer size,
990 memory allocated to compression, SSL cache size, and use of SSL in either
991 frontends, backends or both. If neither maxconn nor maxsslconn are specified
992 when there is a memory limit, haproxy will automatically adjust these values
993 so that 100% of the connections can be made over SSL with no risk, and will
994 consider the sides where it is enabled (frontend, backend, both).
Willy Tarreau403edff2012-09-06 11:58:37 +0200995
Willy Tarreaue43d5322013-10-07 20:01:52 +0200996maxsslrate <number>
997 Sets the maximum per-process number of SSL sessions per second to <number>.
998 SSL listeners will stop accepting connections when this limit is reached. It
999 can be used to limit the global SSL CPU usage regardless of each frontend
1000 capacity. It is important to note that this can only be used as a service
1001 protection measure, as there will not necessarily be a fair share between
1002 frontends when the limit is reached, so it's a good idea to also limit each
1003 frontend to some value close to its expected share. It is also important to
1004 note that the sessions are accounted before they enter the SSL stack and not
1005 after, which also protects the stack against bad handshakes. Also, lowering
1006 tune.maxaccept can improve fairness.
1007
William Lallemand9d5f5482012-11-07 16:12:57 +01001008maxzlibmem <number>
1009 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
1010 When the maximum amount is reached, future sessions will not compress as long
1011 as RAM is unavailable. When sets to 0, there is no limit.
William Lallemande3a7d992012-11-20 11:25:20 +01001012 The default value is 0. The value is available in bytes on the UNIX socket
1013 with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is
1014 "ZlibMemUsage" in bytes.
1015
Willy Tarreau6a06a402007-07-15 20:15:28 +02001016noepoll
1017 Disables the use of the "epoll" event polling system on Linux. It is
1018 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +01001019 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001020
1021nokqueue
1022 Disables the use of the "kqueue" event polling system on BSD. It is
1023 equivalent to the command-line argument "-dk". The next polling system
1024 used will generally be "poll". See also "nopoll".
1025
1026nopoll
1027 Disables the use of the "poll" event polling system. It is equivalent to the
1028 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001029 It should never be needed to disable "poll" since it's available on all
Willy Tarreaue9f49e72012-11-11 17:42:00 +01001030 platforms supported by HAProxy. See also "nokqueue" and "noepoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001031
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001032nosplice
1033 Disables the use of kernel tcp splicing between sockets on Linux. It is
1034 equivalent to the command line argument "-dS". Data will then be copied
1035 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001036 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001037 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
1038 be used. This option makes it easier to globally disable kernel splicing in
1039 case of doubt. See also "option splice-auto", "option splice-request" and
1040 "option splice-response".
1041
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001042nogetaddrinfo
1043 Disables the use of getaddrinfo(3) for name resolving. It is equivalent to
1044 the command line argument "-dG". Deprecated gethostbyname(3) will be used.
1045
Willy Tarreaufe255b72007-10-14 23:09:26 +02001046spread-checks <0..50, in percent>
Simon Hormand60d6912013-11-25 10:46:36 +09001047 Sometimes it is desirable to avoid sending agent and health checks to
1048 servers at exact intervals, for instance when many logical servers are
1049 located on the same physical server. With the help of this parameter, it
1050 becomes possible to add some randomness in the check interval between 0
1051 and +/- 50%. A value between 2 and 5 seems to show good results. The
1052 default value remains at 0.
Willy Tarreaufe255b72007-10-14 23:09:26 +02001053
Willy Tarreau33cb0652014-12-23 22:52:37 +01001054tune.buffers.limit <number>
1055 Sets a hard limit on the number of buffers which may be allocated per process.
1056 The default value is zero which means unlimited. The minimum non-zero value
1057 will always be greater than "tune.buffers.reserve" and should ideally always
1058 be about twice as large. Forcing this value can be particularly useful to
1059 limit the amount of memory a process may take, while retaining a sane
1060 behaviour. When this limit is reached, sessions which need a buffer wait for
1061 another one to be released by another session. Since buffers are dynamically
1062 allocated and released, the waiting time is very short and not perceptible
1063 provided that limits remain reasonable. In fact sometimes reducing the limit
1064 may even increase performance by increasing the CPU cache's efficiency. Tests
1065 have shown good results on average HTTP traffic with a limit to 1/10 of the
1066 expected global maxconn setting, which also significantly reduces memory
1067 usage. The memory savings come from the fact that a number of connections
1068 will not allocate 2*tune.bufsize. It is best not to touch this value unless
1069 advised to do so by an haproxy core developer.
1070
Willy Tarreau1058ae72014-12-23 22:40:40 +01001071tune.buffers.reserve <number>
1072 Sets the number of buffers which are pre-allocated and reserved for use only
1073 during memory shortage conditions resulting in failed memory allocations. The
1074 minimum value is 2 and is also the default. There is no reason a user would
1075 want to change this value, it's mostly aimed at haproxy core developers.
1076
Willy Tarreau27a674e2009-08-17 07:23:33 +02001077tune.bufsize <number>
1078 Sets the buffer size to this size (in bytes). Lower values allow more
1079 sessions to coexist in the same amount of RAM, and higher values allow some
1080 applications with very large cookies to work. The default value is 16384 and
1081 can be changed at build time. It is strongly recommended not to change this
1082 from the default value, as very low values will break some services such as
1083 statistics, and values larger than default size will increase memory usage,
1084 possibly causing the system to run out of memory. At least the global maxconn
1085 parameter should be decreased by the same factor as this one is increased.
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +04001086 If HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will
1087 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
1088 than this size, haproxy will return HTTP 502 (Bad Gateway).
Willy Tarreau27a674e2009-08-17 07:23:33 +02001089
Willy Tarreau43961d52010-10-04 20:39:20 +02001090tune.chksize <number>
1091 Sets the check buffer size to this size (in bytes). Higher values may help
1092 find string or regex patterns in very large pages, though doing so may imply
1093 more memory and CPU usage. The default value is 16384 and can be changed at
1094 build time. It is not recommended to change this value, but to use better
1095 checks whenever possible.
1096
William Lallemandf3747832012-11-09 12:33:10 +01001097tune.comp.maxlevel <number>
1098 Sets the maximum compression level. The compression level affects CPU
1099 usage during compression. This value affects CPU usage during compression.
1100 Each session using compression initializes the compression algorithm with
1101 this value. The default value is 1.
1102
Willy Tarreau193b8c62012-11-22 00:17:38 +01001103tune.http.cookielen <number>
1104 Sets the maximum length of captured cookies. This is the maximum value that
1105 the "capture cookie xxx len yyy" will be allowed to take, and any upper value
1106 will automatically be truncated to this one. It is important not to set too
1107 high a value because all cookie captures still allocate this size whatever
1108 their configured value (they share a same pool). This value is per request
1109 per response, so the memory allocated is twice this value per connection.
1110 When not specified, the limit is set to 63 characters. It is recommended not
1111 to change this value.
1112
Willy Tarreauac1932d2011-10-24 19:14:41 +02001113tune.http.maxhdr <number>
1114 Sets the maximum number of headers in a request. When a request comes with a
1115 number of headers greater than this value (including the first line), it is
1116 rejected with a "400 Bad Request" status code. Similarly, too large responses
1117 are blocked with "502 Bad Gateway". The default value is 101, which is enough
1118 for all usages, considering that the widely deployed Apache server uses the
1119 same limit. It can be useful to push this limit further to temporarily allow
1120 a buggy application to work by the time it gets fixed. Keep in mind that each
1121 new header consumes 32bits of memory for each session, so don't push this
1122 limit too high.
1123
Willy Tarreau7e312732014-02-12 16:35:14 +01001124tune.idletimer <timeout>
1125 Sets the duration after which haproxy will consider that an empty buffer is
1126 probably associated with an idle stream. This is used to optimally adjust
1127 some packet sizes while forwarding large and small data alternatively. The
1128 decision to use splice() or to send large buffers in SSL is modulated by this
1129 parameter. The value is in milliseconds between 0 and 65535. A value of zero
1130 means that haproxy will not try to detect idle streams. The default is 1000,
1131 which seems to correctly detect end user pauses (eg: read a page before
1132 clicking). There should be not reason for changing this value. Please check
1133 tune.ssl.maxrecord below.
1134
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001135tune.lua.forced-yield <number>
1136 This directive forces the Lua engine to execute a yield each <number> of
1137 instructions executed. This permits interruptng a long script and allows the
1138 HAProxy scheduler to process other tasks like accepting connections or
1139 forwarding traffic. The default value is 10000 instructions. If HAProxy often
1140 executes some Lua code but more reactivity is required, this value can be
1141 lowered. If the Lua code is quite long and its result is absolutely required
1142 to process the data, the <number> can be increased.
1143
Willy Tarreau32f61e22015-03-18 17:54:59 +01001144tune.lua.maxmem
1145 Sets the maximum amount of RAM in megabytes per process usable by Lua. By
1146 default it is zero which means unlimited. It is important to set a limit to
1147 ensure that a bug in a script will not result in the system running out of
1148 memory.
1149
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001150tune.lua.session-timeout <timeout>
1151 This is the execution timeout for the Lua sessions. This is useful for
1152 preventing infinite loops or spending too much time in Lua. This timeout has a
1153 priority over other timeouts. For example, if this timeout is set to 4s and
1154 you run a 5s sleep, the code will be interrupted with an error after waiting
1155 4s.
1156
1157tune.lua.task-timeout <timeout>
1158 Purpose is the same as "tune.lua.session-timeout", but this timeout is
1159 dedicated to the tasks. By default, this timeout isn't set because a task may
1160 remain alive during of the lifetime of HAProxy. For example, a task used to
1161 check servers.
1162
Willy Tarreaua0250ba2008-01-06 11:22:57 +01001163tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +01001164 Sets the maximum number of consecutive connections a process may accept in a
1165 row before switching to other work. In single process mode, higher numbers
1166 give better performance at high connection rates. However in multi-process
1167 modes, keeping a bit of fairness between processes generally is better to
1168 increase performance. This value applies individually to each listener, so
1169 that the number of processes a listener is bound to is taken into account.
1170 This value defaults to 64. In multi-process mode, it is divided by twice
1171 the number of processes the listener is bound to. Setting this value to -1
1172 completely disables the limitation. It should normally not be needed to tweak
1173 this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +01001174
1175tune.maxpollevents <number>
1176 Sets the maximum amount of events that can be processed at once in a call to
1177 the polling system. The default value is adapted to the operating system. It
1178 has been noticed that reducing it below 200 tends to slightly decrease
1179 latency at the expense of network bandwidth, and increasing it above 200
1180 tends to trade latency for slightly increased bandwidth.
1181
Willy Tarreau27a674e2009-08-17 07:23:33 +02001182tune.maxrewrite <number>
1183 Sets the reserved buffer space to this size in bytes. The reserved space is
1184 used for header rewriting or appending. The first reads on sockets will never
1185 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
1186 bufsize, though that does not make much sense since there are rarely large
1187 numbers of headers to add. Setting it too high prevents processing of large
1188 requests or responses. Setting it too low prevents addition of new headers
1189 to already large requests or to POST requests. It is generally wise to set it
1190 to about 1024. It is automatically readjusted to half of bufsize if it is
1191 larger than that. This means you don't have to worry about it when changing
1192 bufsize.
1193
Willy Tarreauf3045d22015-04-29 16:24:50 +02001194tune.pattern.cache-size <number>
1195 Sets the size of the pattern lookup cache to <number> entries. This is an LRU
1196 cache which reminds previous lookups and their results. It is used by ACLs
1197 and maps on slow pattern lookups, namely the ones using the "sub", "reg",
1198 "dir", "dom", "end", "bin" match methods as well as the case-insensitive
1199 strings. It applies to pattern expressions which means that it will be able
1200 to memorize the result of a lookup among all the patterns specified on a
1201 configuration line (including all those loaded from files). It automatically
1202 invalidates entries which are updated using HTTP actions or on the CLI. The
1203 default cache size is set to 10000 entries, which limits its footprint to
1204 about 5 MB on 32-bit systems and 8 MB on 64-bit systems. There is a very low
1205 risk of collision in this cache, which is in the order of the size of the
1206 cache divided by 2^64. Typically, at 10000 requests per second with the
1207 default cache size of 10000 entries, there's 1% chance that a brute force
1208 attack could cause a single collision after 60 years, or 0.1% after 6 years.
1209 This is considered much lower than the risk of a memory corruption caused by
1210 aging components. If this is not acceptable, the cache can be disabled by
1211 setting this parameter to 0.
1212
Willy Tarreaubd9a0a72011-10-23 21:14:29 +02001213tune.pipesize <number>
1214 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
1215 are the default size for the system. But sometimes when using TCP splicing,
1216 it can improve performance to increase pipe sizes, especially if it is
1217 suspected that pipes are not filled and that many calls to splice() are
1218 performed. This has an impact on the kernel's memory footprint, so this must
1219 not be changed if impacts are not understood.
1220
Willy Tarreaue803de22010-01-21 17:43:04 +01001221tune.rcvbuf.client <number>
1222tune.rcvbuf.server <number>
1223 Forces the kernel socket receive buffer size on the client or the server side
1224 to the specified value in bytes. This value applies to all TCP/HTTP frontends
1225 and backends. It should normally never be set, and the default size (0) lets
1226 the kernel autotune this value depending on the amount of available memory.
1227 However it can sometimes help to set it to very low values (eg: 4096) in
1228 order to save kernel memory by preventing it from buffering too large amounts
1229 of received data. Lower values will significantly increase CPU usage though.
1230
1231tune.sndbuf.client <number>
1232tune.sndbuf.server <number>
1233 Forces the kernel socket send buffer size on the client or the server side to
1234 the specified value in bytes. This value applies to all TCP/HTTP frontends
1235 and backends. It should normally never be set, and the default size (0) lets
1236 the kernel autotune this value depending on the amount of available memory.
1237 However it can sometimes help to set it to very low values (eg: 4096) in
1238 order to save kernel memory by preventing it from buffering too large amounts
1239 of received data. Lower values will significantly increase CPU usage though.
1240 Another use case is to prevent write timeouts with extremely slow clients due
1241 to the kernel waiting for a large part of the buffer to be read before
1242 notifying haproxy again.
1243
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001244tune.ssl.cachesize <number>
Emeric Brunaf9619d2012-11-28 18:47:52 +01001245 Sets the size of the global SSL session cache, in a number of blocks. A block
1246 is large enough to contain an encoded session without peer certificate.
1247 An encoded session with peer certificate is stored in multiple blocks
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001248 depending on the size of the peer certificate. A block uses approximately
Emeric Brunaf9619d2012-11-28 18:47:52 +01001249 200 bytes of memory. The default value may be forced at build time, otherwise
1250 defaults to 20000. When the cache is full, the most idle entries are purged
1251 and reassigned. Higher values reduce the occurrence of such a purge, hence
1252 the number of CPU-intensive SSL handshakes by ensuring that all users keep
1253 their session as long as possible. All entries are pre-allocated upon startup
Emeric Brun22890a12012-12-28 14:41:32 +01001254 and are shared between all processes if "nbproc" is greater than 1. Setting
1255 this value to 0 disables the SSL session cache.
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001256
Emeric Brun8dc60392014-05-09 13:52:00 +02001257tune.ssl.force-private-cache
1258 This boolean disables SSL session cache sharing between all processes. It
1259 should normally not be used since it will force many renegotiations due to
1260 clients hitting a random process. But it may be required on some operating
1261 systems where none of the SSL cache synchronization method may be used. In
1262 this case, adding a first layer of hash-based load balancing before the SSL
1263 layer might limit the impact of the lack of session sharing.
1264
Emeric Brun4f65bff2012-11-16 15:11:00 +01001265tune.ssl.lifetime <timeout>
1266 Sets how long a cached SSL session may remain valid. This time is expressed
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001267 in seconds and defaults to 300 (5 min). It is important to understand that it
Emeric Brun4f65bff2012-11-16 15:11:00 +01001268 does not guarantee that sessions will last that long, because if the cache is
1269 full, the longest idle sessions will be purged despite their configured
1270 lifetime. The real usefulness of this setting is to prevent sessions from
1271 being used for too long.
1272
Willy Tarreaubfd59462013-02-21 07:46:09 +01001273tune.ssl.maxrecord <number>
1274 Sets the maximum amount of bytes passed to SSL_write() at a time. Default
1275 value 0 means there is no limit. Over SSL/TLS, the client can decipher the
1276 data only once it has received a full record. With large records, it means
1277 that clients might have to download up to 16kB of data before starting to
1278 process them. Limiting the value can improve page load times on browsers
1279 located over high latency or low bandwidth networks. It is suggested to find
1280 optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over
1281 Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled),
1282 keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and
1283 2859 gave good results during tests. Use "strace -e trace=write" to find the
Willy Tarreau7e312732014-02-12 16:35:14 +01001284 best value. Haproxy will automatically switch to this setting after an idle
1285 stream has been detected (see tune.idletimer above).
Willy Tarreaubfd59462013-02-21 07:46:09 +01001286
Remi Gacognef46cd6e2014-06-12 14:58:40 +02001287tune.ssl.default-dh-param <number>
1288 Sets the maximum size of the Diffie-Hellman parameters used for generating
1289 the ephemeral/temporary Diffie-Hellman key in case of DHE key exchange. The
1290 final size will try to match the size of the server's RSA (or DSA) key (e.g,
1291 a 2048 bits temporary DH key for a 2048 bits RSA key), but will not exceed
1292 this maximum value. Default value if 1024. Only 1024 or higher values are
1293 allowed. Higher values will increase the CPU load, and values greater than
1294 1024 bits are not supported by Java 7 and earlier clients. This value is not
Remi Gacogne47783ef2015-05-29 15:53:22 +02001295 used if static Diffie-Hellman parameters are supplied either directly
1296 in the certificate file or by using the ssl-dh-param-file parameter.
Remi Gacognef46cd6e2014-06-12 14:58:40 +02001297
Christopher Faulet31af49d2015-06-09 17:29:50 +02001298tune.ssl.ssl-ctx-cache-size <number>
1299 Sets the size of the cache used to store generated certificates to <number>
1300 entries. This is a LRU cache. Because generating a SSL certificate
1301 dynamically is expensive, they are cached. The default cache size is set to
1302 1000 entries.
1303
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001304tune.vars.global-max-size <size>
1305tune.vars.reqres-max-size <size>
1306tune.vars.sess-max-size <size>
1307tune.vars.txn-max-size <size>
1308 These four tunes helps to manage the allowed amount of memory used by the
1309 variables system. "global" limits the memory for all the systems. "sess" limit
1310 the memory by session, "txn" limits the memory by transaction and "reqres"
1311 limits the memory for each request or response processing. during the
1312 accounting, "sess" embbed "txn" and "txn" embed "reqres".
1313
1314 By example, we considers that "tune.vars.sess-max-size" is fixed to 100,
1315 "tune.vars.txn-max-size" is fixed to 100, "tune.vars.reqres-max-size" is
1316 also fixed to 100. If we create a variable "txn.var" that contains 100 bytes,
1317 we cannot create any more variable in the other contexts.
1318
William Lallemanda509e4c2012-11-07 16:54:34 +01001319tune.zlib.memlevel <number>
1320 Sets the memLevel parameter in zlib initialization for each session. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001321 defines how much memory should be allocated for the internal compression
William Lallemanda509e4c2012-11-07 16:54:34 +01001322 state. A value of 1 uses minimum memory but is slow and reduces compression
1323 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
1324 between 1 and 9. The default value is 8.
1325
1326tune.zlib.windowsize <number>
1327 Sets the window size (the size of the history buffer) as a parameter of the
1328 zlib initialization for each session. Larger values of this parameter result
1329 in better compression at the expense of memory usage. Can be a value between
1330 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001331
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013323.3. Debugging
1333--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02001334
1335debug
1336 Enables debug mode which dumps to stdout all exchanges, and disables forking
1337 into background. It is the equivalent of the command-line argument "-d". It
1338 should never be used in a production configuration since it may prevent full
1339 system startup.
1340
1341quiet
1342 Do not display any message during startup. It is equivalent to the command-
1343 line argument "-q".
1344
Emeric Brunf099e792010-09-27 12:05:28 +02001345
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010013463.4. Userlists
1347--------------
1348It is possible to control access to frontend/backend/listen sections or to
1349http stats by allowing only authenticated and authorized users. To do this,
1350it is required to create at least one userlist and to define users.
1351
1352userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +01001353 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001354 used to store authentication & authorization data for independent customers.
1355
1356group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +01001357 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001358 attach users to this group by using a comma separated list of names
1359 proceeded by "users" keyword.
1360
Cyril Bontéf0c60612010-02-06 14:44:47 +01001361user <username> [password|insecure-password <password>]
1362 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001363 Adds user <username> to the current userlist. Both secure (encrypted) and
1364 insecure (unencrypted) passwords can be used. Encrypted passwords are
Cyril Bonté78caf842010-03-10 22:41:43 +01001365 evaluated using the crypt(3) function so depending of the system's
1366 capabilities, different algorithms are supported. For example modern Glibc
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001367 based Linux system supports MD5, SHA-256, SHA-512 and of course classic,
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001368 DES-based method of encrypting passwords.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001369
1370
1371 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +01001372 userlist L1
1373 group G1 users tiger,scott
1374 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001375
Cyril Bontéf0c60612010-02-06 14:44:47 +01001376 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
1377 user scott insecure-password elgato
1378 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001379
Cyril Bontéf0c60612010-02-06 14:44:47 +01001380 userlist L2
1381 group G1
1382 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001383
Cyril Bontéf0c60612010-02-06 14:44:47 +01001384 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
1385 user scott insecure-password elgato groups G1,G2
1386 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001387
1388 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001389
Emeric Brunf099e792010-09-27 12:05:28 +02001390
13913.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +02001392----------
Emeric Brun94900952015-06-11 18:25:54 +02001393It is possible to propagate entries of any data-types in stick-tables between
1394several haproxy instances over TCP connections in a multi-master fashion. Each
1395instance pushes its local updates and insertions to remote peers. The pushed
1396values overwrite remote ones without aggregation. Interrupted exchanges are
1397automatically detected and recovered from the last known point.
1398In addition, during a soft restart, the old process connects to the new one
1399using such a TCP connection to push all its entries before the new process
1400tries to connect to other peers. That ensures very fast replication during a
1401reload, it typically takes a fraction of a second even for large tables.
1402Note that Server IDs are used to identify servers remotely, so it is important
1403that configurations look similar or at least that the same IDs are forced on
1404each server on all participants.
Emeric Brunf099e792010-09-27 12:05:28 +02001405
1406peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001407 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +02001408 which is referenced by one or more stick-tables.
1409
Willy Tarreau77e4bd12015-05-01 20:02:17 +02001410disabled
1411 Disables a peers section. It disables both listening and any synchronization
1412 related to this section. This is provided to disable synchronization of stick
1413 tables without having to comment out all "peers" references.
1414
1415enable
1416 This re-enables a disabled peers section which was previously disabled.
1417
Emeric Brunf099e792010-09-27 12:05:28 +02001418peer <peername> <ip>:<port>
1419 Defines a peer inside a peers section.
1420 If <peername> is set to the local peer name (by default hostname, or forced
1421 using "-L" command line option), haproxy will listen for incoming remote peer
1422 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
1423 to join the remote peer, and <peername> is used at the protocol level to
1424 identify and validate the remote peer on the server side.
1425
1426 During a soft restart, local peer <ip>:<port> is used by the old instance to
1427 connect the new one and initiate a complete replication (teaching process).
1428
1429 It is strongly recommended to have the exact same peers declaration on all
1430 peers and to only rely on the "-L" command line argument to change the local
1431 peer name. This makes it easier to maintain coherent configuration files
1432 across all peers.
1433
William Lallemandb2f07452015-05-12 14:27:13 +02001434 You may want to reference some environment variables in the address
1435 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01001436
Cyril Bontédc4d9032012-04-08 21:57:39 +02001437 Example:
Emeric Brunf099e792010-09-27 12:05:28 +02001438 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001439 peer haproxy1 192.168.0.1:1024
1440 peer haproxy2 192.168.0.2:1024
1441 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +02001442
1443 backend mybackend
1444 mode tcp
1445 balance roundrobin
1446 stick-table type ip size 20k peers mypeers
1447 stick on src
1448
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001449 server srv1 192.168.0.30:80
1450 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +02001451
1452
Simon Horman51a1cf62015-02-03 13:00:44 +090014533.6. Mailers
1454------------
1455It is possible to send email alerts when the state of servers changes.
1456If configured email alerts are sent to each mailer that is configured
1457in a mailers section. Email is sent to mailers using SMTP.
1458
Pieter Baauw386a1272015-08-16 15:26:24 +02001459mailers <mailersect>
Simon Horman51a1cf62015-02-03 13:00:44 +09001460 Creates a new mailer list with the name <mailersect>. It is an
1461 independent section which is referenced by one or more proxies.
1462
1463mailer <mailername> <ip>:<port>
1464 Defines a mailer inside a mailers section.
1465
1466 Example:
1467 mailers mymailers
1468 mailer smtp1 192.168.0.1:587
1469 mailer smtp2 192.168.0.2:587
1470
1471 backend mybackend
1472 mode tcp
1473 balance roundrobin
1474
1475 email-alert mailers mymailers
1476 email-alert from test1@horms.org
1477 email-alert to test2@horms.org
1478
1479 server srv1 192.168.0.30:80
1480 server srv2 192.168.0.31:80
1481
1482
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014834. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +02001484----------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001485
Willy Tarreau6a06a402007-07-15 20:15:28 +02001486Proxy configuration can be located in a set of sections :
William Lallemand6e62fb62015-04-28 16:55:23 +02001487 - defaults [<name>]
Willy Tarreau6a06a402007-07-15 20:15:28 +02001488 - frontend <name>
1489 - backend <name>
1490 - listen <name>
1491
1492A "defaults" section sets default parameters for all other sections following
1493its declaration. Those default parameters are reset by the next "defaults"
1494section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +01001495section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001496
1497A "frontend" section describes a set of listening sockets accepting client
1498connections.
1499
1500A "backend" section describes a set of servers to which the proxy will connect
1501to forward incoming connections.
1502
1503A "listen" section defines a complete proxy with its frontend and backend
1504parts combined in one section. It is generally useful for TCP-only traffic.
1505
Willy Tarreau0ba27502007-12-24 16:55:16 +01001506All proxy names must be formed from upper and lower case letters, digits,
1507'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
1508case-sensitive, which means that "www" and "WWW" are two different proxies.
1509
1510Historically, all proxy names could overlap, it just caused troubles in the
1511logs. Since the introduction of content switching, it is mandatory that two
1512proxies with overlapping capabilities (frontend/backend) have different names.
1513However, it is still permitted that a frontend and a backend share the same
1514name, as this configuration seems to be commonly encountered.
1515
1516Right now, two major proxy modes are supported : "tcp", also known as layer 4,
1517and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001518bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01001519protocol, and can interact with it by allowing, blocking, switching, adding,
1520modifying, or removing arbitrary contents in requests or responses, based on
1521arbitrary criteria.
1522
Willy Tarreau70dffda2014-01-30 03:07:23 +01001523In HTTP mode, the processing applied to requests and responses flowing over
1524a connection depends in the combination of the frontend's HTTP options and
1525the backend's. HAProxy supports 5 connection modes :
1526
1527 - KAL : keep alive ("option http-keep-alive") which is the default mode : all
1528 requests and responses are processed, and connections remain open but idle
1529 between responses and new requests.
1530
1531 - TUN: tunnel ("option http-tunnel") : this was the default mode for versions
1532 1.0 to 1.5-dev21 : only the first request and response are processed, and
1533 everything else is forwarded with no analysis at all. This mode should not
1534 be used as it creates lots of trouble with logging and HTTP processing.
1535
1536 - PCL: passive close ("option httpclose") : exactly the same as tunnel mode,
1537 but with "Connection: close" appended in both directions to try to make
1538 both ends close after the first request/response exchange.
1539
1540 - SCL: server close ("option http-server-close") : the server-facing
1541 connection is closed after the end of the response is received, but the
1542 client-facing connection remains open.
1543
1544 - FCL: forced close ("option forceclose") : the connection is actively closed
1545 after the end of the response.
1546
1547The effective mode that will be applied to a connection passing through a
1548frontend and a backend can be determined by both proxy modes according to the
1549following matrix, but in short, the modes are symmetric, keep-alive is the
1550weakest option and force close is the strongest.
1551
1552 Backend mode
1553
1554 | KAL | TUN | PCL | SCL | FCL
1555 ----+-----+-----+-----+-----+----
1556 KAL | KAL | TUN | PCL | SCL | FCL
1557 ----+-----+-----+-----+-----+----
1558 TUN | TUN | TUN | PCL | SCL | FCL
1559 Frontend ----+-----+-----+-----+-----+----
1560 mode PCL | PCL | PCL | PCL | FCL | FCL
1561 ----+-----+-----+-----+-----+----
1562 SCL | SCL | SCL | FCL | SCL | FCL
1563 ----+-----+-----+-----+-----+----
1564 FCL | FCL | FCL | FCL | FCL | FCL
1565
Willy Tarreau0ba27502007-12-24 16:55:16 +01001566
Willy Tarreau70dffda2014-01-30 03:07:23 +01001567
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015684.1. Proxy keywords matrix
1569--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001570
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001571The following list of keywords is supported. Most of them may only be used in a
1572limited set of section types. Some of them are marked as "deprecated" because
1573they are inherited from an old syntax which may be confusing or functionally
1574limited, and there are new recommended keywords to replace them. Keywords
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001575marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001576option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02001577and must be disabled for a specific instance. Such options may also be prefixed
1578with "default" in order to restore default settings regardless of what has been
1579specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001580
Willy Tarreau6a06a402007-07-15 20:15:28 +02001581
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001582 keyword defaults frontend listen backend
1583------------------------------------+----------+----------+---------+---------
1584acl - X X X
Willy Tarreau294d0f02015-08-10 19:40:12 +02001585appsession - - - -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001586backlog X X X -
1587balance X - X X
1588bind - X X -
1589bind-process X X X X
1590block - X X X
1591capture cookie - X X -
1592capture request header - X X -
1593capture response header - X X -
1594clitimeout (deprecated) X X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02001595compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001596contimeout (deprecated) X - X X
1597cookie X - X X
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02001598declare capture - X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001599default-server X - X X
1600default_backend X X X -
1601description - X X X
1602disabled X X X X
1603dispatch - - X X
Simon Horman51a1cf62015-02-03 13:00:44 +09001604email-alert from X X X X
Simon Horman64e34162015-02-06 11:11:57 +09001605email-alert level X X X X
Simon Horman51a1cf62015-02-03 13:00:44 +09001606email-alert mailers X X X X
1607email-alert myhostname X X X X
1608email-alert to X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001609enabled X X X X
1610errorfile X X X X
1611errorloc X X X X
1612errorloc302 X X X X
1613-- keyword -------------------------- defaults - frontend - listen -- backend -
1614errorloc303 X X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001615force-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001616fullconn X - X X
1617grace X X X X
1618hash-type X - X X
1619http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +01001620http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02001621http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001622http-request - X X X
Willy Tarreaue365c0b2013-06-11 16:06:12 +02001623http-response - X X X
Willy Tarreau30631952015-08-06 15:05:24 +02001624http-reuse X - X X
Baptiste Assmann2c42ef52013-10-09 21:57:02 +02001625http-send-name-header - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001626id - X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001627ignore-persist - X X X
William Lallemand0f99e342011-10-12 17:50:54 +02001628log (*) X X X X
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01001629log-format X X X -
Willy Tarreau094af4e2015-01-07 15:03:42 +01001630log-tag X X X X
Willy Tarreauc35362a2014-04-25 13:58:37 +02001631max-keep-alive-queue X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001632maxconn X X X -
1633mode X X X X
1634monitor fail - X X -
1635monitor-net X X X -
1636monitor-uri X X X -
1637option abortonclose (*) X - X X
1638option accept-invalid-http-request (*) X X X -
1639option accept-invalid-http-response (*) X - X X
1640option allbackups (*) X - X X
1641option checkcache (*) X - X X
1642option clitcpka (*) X X X -
1643option contstats (*) X X X -
1644option dontlog-normal (*) X X X -
1645option dontlognull (*) X X X -
1646option forceclose (*) X X X X
1647-- keyword -------------------------- defaults - frontend - listen -- backend -
1648option forwardfor X X X X
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02001649option http-buffer-request (*) X X X X
Willy Tarreau82649f92015-05-01 22:40:51 +02001650option http-ignore-probes (*) X X X -
Willy Tarreau16bfb022010-01-16 19:48:41 +01001651option http-keep-alive (*) X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02001652option http-no-delay (*) X X X X
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02001653option http-pretend-keepalive (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001654option http-server-close (*) X X X X
Willy Tarreau02bce8b2014-01-30 00:15:28 +01001655option http-tunnel (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001656option http-use-proxy-header (*) X X X -
1657option httpchk X - X X
1658option httpclose (*) X X X X
1659option httplog X X X X
1660option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001661option independent-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02001662option ldap-check X - X X
Simon Horman98637e52014-06-20 12:30:16 +09001663option external-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001664option log-health-checks (*) X - X X
1665option log-separate-errors (*) X X X -
1666option logasap (*) X X X -
1667option mysql-check X - X X
Rauf Kuliyev38b41562011-01-04 15:14:13 +01001668option pgsql-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001669option nolinger (*) X X X X
1670option originalto X X X X
1671option persist (*) X - X X
1672option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02001673option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001674option smtpchk X - X X
1675option socket-stats (*) X X X -
1676option splice-auto (*) X X X X
1677option splice-request (*) X X X X
1678option splice-response (*) X X X X
1679option srvtcpka (*) X - X X
1680option ssl-hello-chk X - X X
1681-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreaued179852013-12-16 01:07:00 +01001682option tcp-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001683option tcp-smart-accept (*) X X X -
1684option tcp-smart-connect (*) X - X X
1685option tcpka X X X X
1686option tcplog X X X X
1687option transparent (*) X - X X
Simon Horman98637e52014-06-20 12:30:16 +09001688external-check command X - X X
1689external-check path X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001690persist rdp-cookie X - X X
1691rate-limit sessions X X X -
1692redirect - X X X
1693redisp (deprecated) X - X X
1694redispatch (deprecated) X - X X
1695reqadd - X X X
1696reqallow - X X X
1697reqdel - X X X
1698reqdeny - X X X
1699reqiallow - X X X
1700reqidel - X X X
1701reqideny - X X X
1702reqipass - X X X
1703reqirep - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001704reqitarpit - X X X
1705reqpass - X X X
1706reqrep - X X X
1707-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001708reqtarpit - X X X
1709retries X - X X
1710rspadd - X X X
1711rspdel - X X X
1712rspdeny - X X X
1713rspidel - X X X
1714rspideny - X X X
1715rspirep - X X X
1716rsprep - X X X
1717server - - X X
1718source X - X X
1719srvtimeout (deprecated) X - X X
Cyril Bonté66c327d2010-10-12 00:14:37 +02001720stats admin - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001721stats auth X - X X
1722stats enable X - X X
1723stats hide-version X - X X
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02001724stats http-request - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001725stats realm X - X X
1726stats refresh X - X X
1727stats scope X - X X
1728stats show-desc X - X X
1729stats show-legends X - X X
1730stats show-node X - X X
1731stats uri X - X X
1732-- keyword -------------------------- defaults - frontend - listen -- backend -
1733stick match - - X X
1734stick on - - X X
1735stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02001736stick store-response - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001737stick-table - - X X
Willy Tarreau938c7fe2014-04-25 14:21:39 +02001738tcp-check connect - - X X
1739tcp-check expect - - X X
1740tcp-check send - - X X
1741tcp-check send-binary - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02001742tcp-request connection - X X -
1743tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02001744tcp-request inspect-delay - X X X
Emeric Brun0a3b67f2010-09-24 15:34:53 +02001745tcp-response content - - X X
1746tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001747timeout check X - X X
1748timeout client X X X -
Willy Tarreau05cdd962014-05-10 14:30:07 +02001749timeout client-fin X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001750timeout clitimeout (deprecated) X X X -
1751timeout connect X - X X
1752timeout contimeout (deprecated) X - X X
1753timeout http-keep-alive X X X X
1754timeout http-request X X X X
1755timeout queue X - X X
1756timeout server X - X X
Willy Tarreau05cdd962014-05-10 14:30:07 +02001757timeout server-fin X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001758timeout srvtimeout (deprecated) X - X X
1759timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02001760timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001761transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01001762unique-id-format X X X -
1763unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001764use_backend - X X -
Willy Tarreau4a5cade2012-04-05 21:09:48 +02001765use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001766------------------------------------+----------+----------+---------+---------
1767 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02001768
Willy Tarreau0ba27502007-12-24 16:55:16 +01001769
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017704.2. Alphabetically sorted keywords reference
1771---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001772
1773This section provides a description of each keyword and its usage.
1774
1775
1776acl <aclname> <criterion> [flags] [operator] <value> ...
1777 Declare or complete an access list.
1778 May be used in sections : defaults | frontend | listen | backend
1779 no | yes | yes | yes
1780 Example:
1781 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1782 acl invalid_src src_port 0:1023
1783 acl local_dst hdr(host) -i localhost
1784
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001785 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001786
1787
Cyril Bontéb21570a2009-11-29 20:04:48 +01001788appsession <cookie> len <length> timeout <holdtime>
1789 [request-learn] [prefix] [mode <path-parameters|query-string>]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001790 Define session stickiness on an existing application cookie.
1791 May be used in sections : defaults | frontend | listen | backend
1792 no | no | yes | yes
1793 Arguments :
1794 <cookie> this is the name of the cookie used by the application and which
1795 HAProxy will have to learn for each new session.
1796
Cyril Bontéb21570a2009-11-29 20:04:48 +01001797 <length> this is the max number of characters that will be memorized and
Willy Tarreau0ba27502007-12-24 16:55:16 +01001798 checked in each cookie value.
1799
1800 <holdtime> this is the time after which the cookie will be removed from
1801 memory if unused. If no unit is specified, this time is in
1802 milliseconds.
1803
Cyril Bontébf47aeb2009-10-15 00:15:40 +02001804 request-learn
1805 If this option is specified, then haproxy will be able to learn
1806 the cookie found in the request in case the server does not
1807 specify any in response. This is typically what happens with
1808 PHPSESSID cookies, or when haproxy's session expires before
1809 the application's session and the correct server is selected.
1810 It is recommended to specify this option to improve reliability.
1811
Cyril Bontéb21570a2009-11-29 20:04:48 +01001812 prefix When this option is specified, haproxy will match on the cookie
1813 prefix (or URL parameter prefix). The appsession value is the
1814 data following this prefix.
1815
1816 Example :
1817 appsession ASPSESSIONID len 64 timeout 3h prefix
1818
1819 This will match the cookie ASPSESSIONIDXXXX=XXXXX,
1820 the appsession value will be XXXX=XXXXX.
1821
1822 mode This option allows to change the URL parser mode.
1823 2 modes are currently supported :
1824 - path-parameters :
1825 The parser looks for the appsession in the path parameters
1826 part (each parameter is separated by a semi-colon), which is
1827 convenient for JSESSIONID for example.
1828 This is the default mode if the option is not set.
1829 - query-string :
1830 In this mode, the parser will look for the appsession in the
1831 query string.
1832
Willy Tarreau294d0f02015-08-10 19:40:12 +02001833 As of version 1.6, appsessions was removed. It is more flexible and more
1834 convenient to use stick-tables instead, and stick-tables support multi-master
1835 replication and data conservation across reloads, which appsessions did not.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001836
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001837 See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
1838 "ignore-persist", "nbproc" and "bind-process".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001839
1840
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001841backlog <conns>
1842 Give hints to the system about the approximate listen backlog desired size
1843 May be used in sections : defaults | frontend | listen | backend
1844 yes | yes | yes | no
1845 Arguments :
1846 <conns> is the number of pending connections. Depending on the operating
1847 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02001848 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001849
1850 In order to protect against SYN flood attacks, one solution is to increase
1851 the system's SYN backlog size. Depending on the system, sometimes it is just
1852 tunable via a system parameter, sometimes it is not adjustable at all, and
1853 sometimes the system relies on hints given by the application at the time of
1854 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
1855 to the listen() syscall. On systems which can make use of this value, it can
1856 sometimes be useful to be able to specify a different value, hence this
1857 backlog parameter.
1858
1859 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
1860 used as a hint and the system accepts up to the smallest greater power of
1861 two, and never more than some limits (usually 32768).
1862
1863 See also : "maxconn" and the target operating system's tuning guide.
1864
1865
Willy Tarreau0ba27502007-12-24 16:55:16 +01001866balance <algorithm> [ <arguments> ]
Willy Tarreau226071e2014-04-10 11:55:45 +02001867balance url_param <param> [check_post]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001868 Define the load balancing algorithm to be used in a backend.
1869 May be used in sections : defaults | frontend | listen | backend
1870 yes | no | yes | yes
1871 Arguments :
1872 <algorithm> is the algorithm used to select a server when doing load
1873 balancing. This only applies when no persistence information
1874 is available, or when a connection is redispatched to another
1875 server. <algorithm> may be one of the following :
1876
1877 roundrobin Each server is used in turns, according to their weights.
1878 This is the smoothest and fairest algorithm when the server's
1879 processing time remains equally distributed. This algorithm
1880 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02001881 on the fly for slow starts for instance. It is limited by
Godbacha34bdc02013-07-22 07:44:53 +08001882 design to 4095 active servers per backend. Note that in some
Willy Tarreau9757a382009-10-03 12:56:50 +02001883 large farms, when a server becomes up after having been down
1884 for a very short time, it may sometimes take a few hundreds
1885 requests for it to be re-integrated into the farm and start
1886 receiving traffic. This is normal, though very rare. It is
1887 indicated here in case you would have the chance to observe
1888 it, so that you don't worry.
1889
1890 static-rr Each server is used in turns, according to their weights.
1891 This algorithm is as similar to roundrobin except that it is
1892 static, which means that changing a server's weight on the
1893 fly will have no effect. On the other hand, it has no design
1894 limitation on the number of servers, and when a server goes
1895 up, it is always immediately reintroduced into the farm, once
1896 the full map is recomputed. It also uses slightly less CPU to
1897 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01001898
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01001899 leastconn The server with the lowest number of connections receives the
1900 connection. Round-robin is performed within groups of servers
1901 of the same load to ensure that all servers will be used. Use
1902 of this algorithm is recommended where very long sessions are
1903 expected, such as LDAP, SQL, TSE, etc... but is not very well
1904 suited for protocols using short sessions such as HTTP. This
1905 algorithm is dynamic, which means that server weights may be
1906 adjusted on the fly for slow starts for instance.
1907
Willy Tarreauf09c6602012-02-13 17:12:08 +01001908 first The first server with available connection slots receives the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001909 connection. The servers are chosen from the lowest numeric
Willy Tarreauf09c6602012-02-13 17:12:08 +01001910 identifier to the highest (see server parameter "id"), which
1911 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02001912 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01001913 not make sense to use this algorithm without setting maxconn.
1914 The purpose of this algorithm is to always use the smallest
1915 number of servers so that extra servers can be powered off
1916 during non-intensive hours. This algorithm ignores the server
1917 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02001918 or IMAP than HTTP, though it can be useful there too. In
1919 order to use this algorithm efficiently, it is recommended
1920 that a cloud controller regularly checks server usage to turn
1921 them off when unused, and regularly checks backend queue to
1922 turn new servers on when the queue inflates. Alternatively,
1923 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01001924
Willy Tarreau0ba27502007-12-24 16:55:16 +01001925 source The source IP address is hashed and divided by the total
1926 weight of the running servers to designate which server will
1927 receive the request. This ensures that the same client IP
1928 address will always reach the same server as long as no
1929 server goes down or up. If the hash result changes due to the
1930 number of running servers changing, many clients will be
1931 directed to a different server. This algorithm is generally
1932 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001933 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01001934 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001935 static by default, which means that changing a server's
1936 weight on the fly will have no effect, but this can be
1937 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001938
Oskar Stolc8dc41842012-05-19 10:19:54 +01001939 uri This algorithm hashes either the left part of the URI (before
1940 the question mark) or the whole URI (if the "whole" parameter
1941 is present) and divides the hash value by the total weight of
1942 the running servers. The result designates which server will
1943 receive the request. This ensures that the same URI will
1944 always be directed to the same server as long as no server
1945 goes up or down. This is used with proxy caches and
1946 anti-virus proxies in order to maximize the cache hit rate.
1947 Note that this algorithm may only be used in an HTTP backend.
1948 This algorithm is static by default, which means that
1949 changing a server's weight on the fly will have no effect,
1950 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001951
Oskar Stolc8dc41842012-05-19 10:19:54 +01001952 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001953 "depth", both followed by a positive integer number. These
1954 options may be helpful when it is needed to balance servers
1955 based on the beginning of the URI only. The "len" parameter
1956 indicates that the algorithm should only consider that many
1957 characters at the beginning of the URI to compute the hash.
1958 Note that having "len" set to 1 rarely makes sense since most
1959 URIs start with a leading "/".
1960
1961 The "depth" parameter indicates the maximum directory depth
1962 to be used to compute the hash. One level is counted for each
1963 slash in the request. If both parameters are specified, the
1964 evaluation stops when either is reached.
1965
Willy Tarreau0ba27502007-12-24 16:55:16 +01001966 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001967 the query string of each HTTP GET request.
1968
1969 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02001970 request entity will be searched for the parameter argument,
1971 when it is not found in a query string after a question mark
Willy Tarreau226071e2014-04-10 11:55:45 +02001972 ('?') in the URL. The message body will only start to be
1973 analyzed once either the advertised amount of data has been
1974 received or the request buffer is full. In the unlikely event
1975 that chunked encoding is used, only the first chunk is
Cyril Bontédc4d9032012-04-08 21:57:39 +02001976 scanned. Parameter values separated by a chunk boundary, may
Willy Tarreau226071e2014-04-10 11:55:45 +02001977 be randomly balanced if at all. This keyword used to support
1978 an optional <max_wait> parameter which is now ignored.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001979
1980 If the parameter is found followed by an equal sign ('=') and
1981 a value, then the value is hashed and divided by the total
1982 weight of the running servers. The result designates which
1983 server will receive the request.
1984
1985 This is used to track user identifiers in requests and ensure
1986 that a same user ID will always be sent to the same server as
1987 long as no server goes up or down. If no value is found or if
1988 the parameter is not found, then a round robin algorithm is
1989 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001990 backend. This algorithm is static by default, which means
1991 that changing a server's weight on the fly will have no
1992 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001993
Cyril Bontédc4d9032012-04-08 21:57:39 +02001994 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
1995 request. Just as with the equivalent ACL 'hdr()' function,
1996 the header name in parenthesis is not case sensitive. If the
1997 header is absent or if it does not contain any value, the
1998 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01001999
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002000 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01002001 reducing the hash algorithm to the main domain part with some
2002 specific headers such as 'Host'. For instance, in the Host
2003 value "haproxy.1wt.eu", only "1wt" will be considered.
2004
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002005 This algorithm is static by default, which means that
2006 changing a server's weight on the fly will have no effect,
2007 but this can be changed using "hash-type".
2008
Emeric Brun736aa232009-06-30 17:56:00 +02002009 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02002010 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02002011 The RDP cookie <name> (or "mstshash" if omitted) will be
2012 looked up and hashed for each incoming TCP request. Just as
2013 with the equivalent ACL 'req_rdp_cookie()' function, the name
2014 is not case-sensitive. This mechanism is useful as a degraded
2015 persistence mode, as it makes it possible to always send the
2016 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002017 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02002018 used instead.
2019
2020 Note that for this to work, the frontend must ensure that an
2021 RDP cookie is already present in the request buffer. For this
2022 you must use 'tcp-request content accept' rule combined with
2023 a 'req_rdp_cookie_cnt' ACL.
2024
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002025 This algorithm is static by default, which means that
2026 changing a server's weight on the fly will have no effect,
2027 but this can be changed using "hash-type".
2028
Cyril Bontédc4d9032012-04-08 21:57:39 +02002029 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09002030
Willy Tarreau0ba27502007-12-24 16:55:16 +01002031 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02002032 algorithms. Right now, only "url_param" and "uri" support an
2033 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002034
Willy Tarreau3cd9af22009-03-15 14:06:41 +01002035 The load balancing algorithm of a backend is set to roundrobin when no other
2036 algorithm, mode nor option have been set. The algorithm may only be set once
2037 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002038
2039 Examples :
2040 balance roundrobin
2041 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002042 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01002043 balance hdr(User-Agent)
2044 balance hdr(host)
2045 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002046
2047 Note: the following caveats and limitations on using the "check_post"
2048 extension with "url_param" must be considered :
2049
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002050 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002051 to determine if the parameters will be found in the body or entity which
2052 may contain binary data. Therefore another method may be required to
2053 restrict consideration of POST requests that have no URL parameters in
2054 the body. (see acl reqideny http_end)
2055
2056 - using a <max_wait> value larger than the request buffer size does not
2057 make sense and is useless. The buffer size is set at build time, and
2058 defaults to 16 kB.
2059
2060 - Content-Encoding is not supported, the parameter search will probably
2061 fail; and load balancing will fall back to Round Robin.
2062
2063 - Expect: 100-continue is not supported, load balancing will fall back to
2064 Round Robin.
2065
2066 - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk.
2067 If the entire parameter value is not present in the first chunk, the
2068 selection of server is undefined (actually, defined by how little
2069 actually appeared in the first chunk).
2070
2071 - This feature does not support generation of a 100, 411 or 501 response.
2072
2073 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002074 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002075 white space or control characters are found, indicating the end of what
2076 might be a URL parameter list. This is probably not a concern with SGML
2077 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002078
Willy Tarreau294d0f02015-08-10 19:40:12 +02002079 See also : "dispatch", "cookie", "transparent", "hash-type" and "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002080
2081
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002082bind [<address>]:<port_range> [, ...] [param*]
2083bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002084 Define one or several listening addresses and/or ports in a frontend.
2085 May be used in sections : defaults | frontend | listen | backend
2086 no | yes | yes | no
2087 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01002088 <address> is optional and can be a host name, an IPv4 address, an IPv6
2089 address, or '*'. It designates the address the frontend will
2090 listen on. If unset, all IPv4 addresses of the system will be
2091 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01002092 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreau24709282013-03-10 21:32:12 +01002093 Optionally, an address family prefix may be used before the
2094 address to force the family regardless of the address format,
2095 which can be useful to specify a path to a unix socket with
2096 no slash ('/'). Currently supported prefixes are :
2097 - 'ipv4@' -> address is always IPv4
2098 - 'ipv6@' -> address is always IPv6
2099 - 'unix@' -> address is a path to a local unix socket
Willy Tarreau70f72e02014-07-08 00:37:50 +02002100 - 'abns@' -> address is in abstract namespace (Linux only).
2101 Note: since abstract sockets are not "rebindable", they
2102 do not cope well with multi-process mode during
2103 soft-restart, so it is better to avoid them if
2104 nbproc is greater than 1. The effect is that if the
2105 new process fails to start, only one of the old ones
2106 will be able to rebind to the socket.
Willy Tarreau40aa0702013-03-10 23:51:38 +01002107 - 'fd@<n>' -> use file descriptor <n> inherited from the
2108 parent. The fd must be bound and may or may not already
2109 be listening.
William Lallemandb2f07452015-05-12 14:27:13 +02002110 You may want to reference some environment variables in the
2111 address parameter, see section 2.3 about environment
2112 variables.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01002113
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002114 <port_range> is either a unique TCP port, or a port range for which the
2115 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002116 above. The port is mandatory for TCP listeners. Note that in
2117 the case of an IPv6 address, the port is always the number
2118 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002119 - a numerical port (ex: '80')
2120 - a dash-delimited ports range explicitly stating the lower
2121 and upper bounds (ex: '2000-2100') which are included in
2122 the range.
2123
2124 Particular care must be taken against port ranges, because
2125 every <address:port> couple consumes one socket (= a file
2126 descriptor), so it's easy to consume lots of descriptors
2127 with a simple range, and to run out of sockets. Also, each
2128 <address:port> couple must be used only once among all
2129 instances running on a same system. Please note that binding
2130 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002131 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002132 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002133
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002134 <path> is a UNIX socket path beginning with a slash ('/'). This is
2135 alternative to the TCP listening port. Haproxy will then
2136 receive UNIX connections on the socket located at this place.
2137 The path must begin with a slash and by default is absolute.
2138 It can be relative to the prefix defined by "unix-bind" in
2139 the global section. Note that the total length of the prefix
2140 followed by the socket path cannot exceed some system limits
2141 for UNIX sockets, which commonly are set to 107 characters.
2142
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002143 <param*> is a list of parameters common to all sockets declared on the
2144 same line. These numerous parameters depend on OS and build
2145 options and have a complete section dedicated to them. Please
2146 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002147
Willy Tarreau0ba27502007-12-24 16:55:16 +01002148 It is possible to specify a list of address:port combinations delimited by
2149 commas. The frontend will then listen on all of these addresses. There is no
2150 fixed limit to the number of addresses and ports which can be listened on in
2151 a frontend, as well as there is no limit to the number of "bind" statements
2152 in a frontend.
2153
2154 Example :
2155 listen http_proxy
2156 bind :80,:443
2157 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002158 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01002159
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002160 listen http_https_proxy
2161 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02002162 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002163
Willy Tarreau24709282013-03-10 21:32:12 +01002164 listen http_https_proxy_explicit
2165 bind ipv6@:80
2166 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
2167 bind unix@ssl-frontend.sock user root mode 600 accept-proxy
2168
Willy Tarreaudad36a32013-03-11 01:20:04 +01002169 listen external_bind_app1
William Lallemandb2f07452015-05-12 14:27:13 +02002170 bind "fd@${FD_APP1}"
Willy Tarreaudad36a32013-03-11 01:20:04 +01002171
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002172 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002173 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002174
2175
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002176bind-process [ all | odd | even | <number 1-64>[-<number 1-64>] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002177 Limit visibility of an instance to a certain set of processes numbers.
2178 May be used in sections : defaults | frontend | listen | backend
2179 yes | yes | yes | yes
2180 Arguments :
2181 all All process will see this instance. This is the default. It
2182 may be used to override a default value.
2183
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002184 odd This instance will be enabled on processes 1,3,5,...63. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002185 option may be combined with other numbers.
2186
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002187 even This instance will be enabled on processes 2,4,6,...64. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002188 option may be combined with other numbers. Do not use it
2189 with less than 2 processes otherwise some instances might be
2190 missing from all processes.
2191
Willy Tarreau110ecc12012-11-15 17:50:01 +01002192 number The instance will be enabled on this process number or range,
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002193 whose values must all be between 1 and 32 or 64 depending on
Willy Tarreau102df612014-05-07 23:56:38 +02002194 the machine's word size. If a proxy is bound to process
2195 numbers greater than the configured global.nbproc, it will
2196 either be forced to process #1 if a single process was
2197 specified, or to all processes otherwise.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002198
2199 This keyword limits binding of certain instances to certain processes. This
2200 is useful in order not to have too many processes listening to the same
2201 ports. For instance, on a dual-core machine, it might make sense to set
2202 'nbproc 2' in the global section, then distributes the listeners among 'odd'
2203 and 'even' instances.
2204
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002205 At the moment, it is not possible to reference more than 32 or 64 processes
2206 using this keyword, but this should be more than enough for most setups.
2207 Please note that 'all' really means all processes regardless of the machine's
2208 word size, and is not limited to the first 32 or 64.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002209
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02002210 Each "bind" line may further be limited to a subset of the proxy's processes,
2211 please consult the "process" bind keyword in section 5.1.
2212
Willy Tarreaub369a042014-09-16 13:21:03 +02002213 When a frontend has no explicit "bind-process" line, it tries to bind to all
2214 the processes referenced by its "bind" lines. That means that frontends can
2215 easily adapt to their listeners' processes.
2216
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002217 If some backends are referenced by frontends bound to other processes, the
2218 backend automatically inherits the frontend's processes.
2219
2220 Example :
2221 listen app_ip1
2222 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02002223 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002224
2225 listen app_ip2
2226 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02002227 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002228
2229 listen management
2230 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02002231 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002232
Willy Tarreau110ecc12012-11-15 17:50:01 +01002233 listen management
2234 bind 10.0.0.4:80
2235 bind-process 1-4
2236
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02002237 See also : "nbproc" in global section, and "process" in section 5.1.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002238
2239
Willy Tarreau0ba27502007-12-24 16:55:16 +01002240block { if | unless } <condition>
2241 Block a layer 7 request if/unless a condition is matched
2242 May be used in sections : defaults | frontend | listen | backend
2243 no | yes | yes | yes
2244
2245 The HTTP request will be blocked very early in the layer 7 processing
2246 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002247 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02002248 typically used to deny access to certain sensitive resources if some
Willy Tarreau0ba27502007-12-24 16:55:16 +01002249 conditions are met or not met. There is no fixed limit to the number of
2250 "block" statements per instance.
2251
2252 Example:
2253 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
2254 acl invalid_src src_port 0:1023
2255 acl local_dst hdr(host) -i localhost
2256 block if invalid_src || local_dst
2257
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002258 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002259
2260
2261capture cookie <name> len <length>
2262 Capture and log a cookie in the request and in the response.
2263 May be used in sections : defaults | frontend | listen | backend
2264 no | yes | yes | no
2265 Arguments :
2266 <name> is the beginning of the name of the cookie to capture. In order
2267 to match the exact name, simply suffix the name with an equal
2268 sign ('='). The full name will appear in the logs, which is
2269 useful with application servers which adjust both the cookie name
2270 and value (eg: ASPSESSIONXXXXX).
2271
2272 <length> is the maximum number of characters to report in the logs, which
2273 include the cookie name, the equal sign and the value, all in the
2274 standard "name=value" form. The string will be truncated on the
2275 right if it exceeds <length>.
2276
2277 Only the first cookie is captured. Both the "cookie" request headers and the
2278 "set-cookie" response headers are monitored. This is particularly useful to
2279 check for application bugs causing session crossing or stealing between
2280 users, because generally the user's cookies can only change on a login page.
2281
2282 When the cookie was not presented by the client, the associated log column
2283 will report "-". When a request does not cause a cookie to be assigned by the
2284 server, a "-" is reported in the response column.
2285
2286 The capture is performed in the frontend only because it is necessary that
2287 the log format does not change for a given frontend depending on the
2288 backends. This may change in the future. Note that there can be only one
Willy Tarreau193b8c62012-11-22 00:17:38 +01002289 "capture cookie" statement in a frontend. The maximum capture length is set
2290 by the global "tune.http.cookielen" setting and defaults to 63 characters. It
2291 is not possible to specify a capture in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002292
2293 Example:
2294 capture cookie ASPSESSION len 32
2295
2296 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002297 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002298
2299
2300capture request header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01002301 Capture and log the last occurrence of the specified request header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002302 May be used in sections : defaults | frontend | listen | backend
2303 no | yes | yes | no
2304 Arguments :
2305 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002306 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01002307 appear in the requests, with the first letter of each word in
2308 upper case. The header name will not appear in the logs, only the
2309 value is reported, but the position in the logs is respected.
2310
2311 <length> is the maximum number of characters to extract from the value and
2312 report in the logs. The string will be truncated on the right if
2313 it exceeds <length>.
2314
Willy Tarreau4460d032012-11-21 23:37:37 +01002315 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01002316 value will be added to the logs between braces ('{}'). If multiple headers
2317 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002318 in the same order they were declared in the configuration. Non-existent
2319 headers will be logged just as an empty string. Common uses for request
2320 header captures include the "Host" field in virtual hosting environments, the
2321 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002322 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002323 environments to find where the request came from.
2324
2325 Note that when capturing headers such as "User-agent", some spaces may be
2326 logged, making the log analysis more difficult. Thus be careful about what
2327 you log if you know your log parser is not smart enough to rely on the
2328 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002329
Willy Tarreau0900abb2012-11-22 00:21:46 +01002330 There is no limit to the number of captured request headers nor to their
2331 length, though it is wise to keep them low to limit memory usage per session.
2332 In order to keep log format consistent for a same frontend, header captures
2333 can only be declared in a frontend. It is not possible to specify a capture
2334 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002335
2336 Example:
2337 capture request header Host len 15
2338 capture request header X-Forwarded-For len 15
2339 capture request header Referrer len 15
2340
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002341 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01002342 about logging.
2343
2344
2345capture response header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01002346 Capture and log the last occurrence of the specified response header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002347 May be used in sections : defaults | frontend | listen | backend
2348 no | yes | yes | no
2349 Arguments :
2350 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002351 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01002352 appear in the response, with the first letter of each word in
2353 upper case. The header name will not appear in the logs, only the
2354 value is reported, but the position in the logs is respected.
2355
2356 <length> is the maximum number of characters to extract from the value and
2357 report in the logs. The string will be truncated on the right if
2358 it exceeds <length>.
2359
Willy Tarreau4460d032012-11-21 23:37:37 +01002360 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01002361 result will be added to the logs between braces ('{}') after the captured
2362 request headers. If multiple headers are captured, they will be delimited by
2363 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002364 the configuration. Non-existent headers will be logged just as an empty
2365 string. Common uses for response header captures include the "Content-length"
2366 header which indicates how many bytes are expected to be returned, the
2367 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002368
Willy Tarreau0900abb2012-11-22 00:21:46 +01002369 There is no limit to the number of captured response headers nor to their
2370 length, though it is wise to keep them low to limit memory usage per session.
2371 In order to keep log format consistent for a same frontend, header captures
2372 can only be declared in a frontend. It is not possible to specify a capture
2373 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002374
2375 Example:
2376 capture response header Content-length len 9
2377 capture response header Location len 15
2378
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002379 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01002380 about logging.
2381
2382
Cyril Bontéf0c60612010-02-06 14:44:47 +01002383clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002384 Set the maximum inactivity time on the client side.
2385 May be used in sections : defaults | frontend | listen | backend
2386 yes | yes | yes | no
2387 Arguments :
2388 <timeout> is the timeout value is specified in milliseconds by default, but
2389 can be in any other unit if the number is suffixed by the unit,
2390 as explained at the top of this document.
2391
2392 The inactivity timeout applies when the client is expected to acknowledge or
2393 send data. In HTTP mode, this timeout is particularly important to consider
2394 during the first phase, when the client sends the request, and during the
2395 response while it is reading data sent by the server. The value is specified
2396 in milliseconds by default, but can be in any other unit if the number is
2397 suffixed by the unit, as specified at the top of this document. In TCP mode
2398 (and to a lesser extent, in HTTP mode), it is highly recommended that the
2399 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002400 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01002401 losses by specifying timeouts that are slightly above multiples of 3 seconds
2402 (eg: 4 or 5 seconds).
2403
2404 This parameter is specific to frontends, but can be specified once for all in
2405 "defaults" sections. This is in fact one of the easiest solutions not to
2406 forget about it. An unspecified timeout results in an infinite timeout, which
2407 is not recommended. Such a usage is accepted and works but reports a warning
2408 during startup because it may results in accumulation of expired sessions in
2409 the system if the system's timeouts are not configured either.
2410
2411 This parameter is provided for compatibility but is currently deprecated.
2412 Please use "timeout client" instead.
2413
Willy Tarreau036fae02008-01-06 13:24:40 +01002414 See also : "timeout client", "timeout http-request", "timeout server", and
2415 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002416
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002417compression algo <algorithm> ...
2418compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02002419compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02002420 Enable HTTP compression.
2421 May be used in sections : defaults | frontend | listen | backend
2422 yes | yes | yes | yes
2423 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002424 algo is followed by the list of supported compression algorithms.
2425 type is followed by the list of MIME types that will be compressed.
2426 offload makes haproxy work as a compression offloader only (see notes).
2427
2428 The currently supported algorithms are :
Willy Tarreauc91840a2015-03-28 17:00:39 +01002429 identity this is mostly for debugging, and it was useful for developing
2430 the compression feature. Identity does not apply any change on
2431 data.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002432
Willy Tarreauc91840a2015-03-28 17:00:39 +01002433 gzip applies gzip compression. This setting is only available when
2434 support for zlib was built in.
2435
2436 deflate same as "gzip", but with deflate algorithm and zlib format.
2437 Note that this algorithm has ambiguous support on many
2438 browsers and no support at all from recent ones. It is
2439 strongly recommended not to use it for anything else than
2440 experimentation. This setting is only available when support
2441 for zlib was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002442
Willy Tarreauc91840a2015-03-28 17:00:39 +01002443 raw-deflate same as "deflate" without the zlib wrapper, and used as an
2444 alternative when the browser wants "deflate". All major
2445 browsers understand it and despite violating the standards,
2446 it is known to work better than "deflate", at least on MSIE
2447 and some versions of Safari. Do not use it in conjunction
2448 with "deflate", use either one or the other since both react
2449 to the same Accept-Encoding token. This setting is only
2450 available when support for zlib was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002451
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04002452 Compression will be activated depending on the Accept-Encoding request
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002453 header. With identity, it does not take care of that header.
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04002454 If backend servers support HTTP compression, these directives
2455 will be no-op: haproxy will see the compressed response and will not
2456 compress again. If backend servers do not support HTTP compression and
2457 there is Accept-Encoding header in request, haproxy will compress the
2458 matching response.
Willy Tarreau70737d12012-10-27 00:34:28 +02002459
2460 The "offload" setting makes haproxy remove the Accept-Encoding header to
2461 prevent backend servers from compressing responses. It is strongly
2462 recommended not to do this because this means that all the compression work
2463 will be done on the single point where haproxy is located. However in some
2464 deployment scenarios, haproxy may be installed in front of a buggy gateway
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04002465 with broken HTTP compression implementation which can't be turned off.
2466 In that case haproxy can be used to prevent that gateway from emitting
2467 invalid payloads. In this case, simply removing the header in the
2468 configuration does not work because it applies before the header is parsed,
2469 so that prevents haproxy from compressing. The "offload" setting should
Willy Tarreauffea9fd2014-07-12 16:37:02 +02002470 then be used for such scenarios. Note: for now, the "offload" setting is
2471 ignored when set in a defaults section.
William Lallemand82fe75c2012-10-23 10:25:10 +02002472
William Lallemand05097442012-11-20 12:14:28 +01002473 Compression is disabled when:
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002474 * the request does not advertise a supported compression algorithm in the
2475 "Accept-Encoding" header
2476 * the response message is not HTTP/1.1
William Lallemandd3002612012-11-26 14:34:47 +01002477 * HTTP status code is not 200
William Lallemand8bb4e342013-12-10 17:28:48 +01002478 * response header "Transfer-Encoding" contains "chunked" (Temporary
2479 Workaround)
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002480 * response contain neither a "Content-Length" header nor a
2481 "Transfer-Encoding" whose last value is "chunked"
2482 * response contains a "Content-Type" header whose first value starts with
2483 "multipart"
2484 * the response contains the "no-transform" value in the "Cache-control"
2485 header
2486 * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7
2487 and later
2488 * The response contains a "Content-Encoding" header, indicating that the
2489 response is already compressed (see compression offload)
William Lallemand05097442012-11-20 12:14:28 +01002490
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002491 Note: The compression does not rewrite Etag headers, and does not emit the
2492 Warning header.
William Lallemand05097442012-11-20 12:14:28 +01002493
William Lallemand82fe75c2012-10-23 10:25:10 +02002494 Examples :
2495 compression algo gzip
2496 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01002497
Cyril Bontéf0c60612010-02-06 14:44:47 +01002498contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002499 Set the maximum time to wait for a connection attempt to a server to succeed.
2500 May be used in sections : defaults | frontend | listen | backend
2501 yes | no | yes | yes
2502 Arguments :
2503 <timeout> is the timeout value is specified in milliseconds by default, but
2504 can be in any other unit if the number is suffixed by the unit,
2505 as explained at the top of this document.
2506
2507 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002508 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01002509 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01002510 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
2511 connect timeout also presets the queue timeout to the same value if this one
2512 has not been specified. Historically, the contimeout was also used to set the
2513 tarpit timeout in a listen section, which is not possible in a pure frontend.
2514
2515 This parameter is specific to backends, but can be specified once for all in
2516 "defaults" sections. This is in fact one of the easiest solutions not to
2517 forget about it. An unspecified timeout results in an infinite timeout, which
2518 is not recommended. Such a usage is accepted and works but reports a warning
2519 during startup because it may results in accumulation of failed sessions in
2520 the system if the system's timeouts are not configured either.
2521
2522 This parameter is provided for backwards compatibility but is currently
2523 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
2524 instead.
2525
2526 See also : "timeout connect", "timeout queue", "timeout tarpit",
2527 "timeout server", "contimeout".
2528
2529
Willy Tarreau55165fe2009-05-10 12:02:55 +02002530cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02002531 [ postonly ] [ preserve ] [ httponly ] [ secure ]
2532 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002533 Enable cookie-based persistence in a backend.
2534 May be used in sections : defaults | frontend | listen | backend
2535 yes | no | yes | yes
2536 Arguments :
2537 <name> is the name of the cookie which will be monitored, modified or
2538 inserted in order to bring persistence. This cookie is sent to
2539 the client via a "Set-Cookie" header in the response, and is
2540 brought back by the client in a "Cookie" header in all requests.
2541 Special care should be taken to choose a name which does not
2542 conflict with any likely application cookie. Also, if the same
2543 backends are subject to be used by the same clients (eg:
2544 HTTP/HTTPS), care should be taken to use different cookie names
2545 between all backends if persistence between them is not desired.
2546
2547 rewrite This keyword indicates that the cookie will be provided by the
2548 server and that haproxy will have to modify its value to set the
2549 server's identifier in it. This mode is handy when the management
2550 of complex combinations of "Set-cookie" and "Cache-control"
2551 headers is left to the application. The application can then
2552 decide whether or not it is appropriate to emit a persistence
2553 cookie. Since all responses should be monitored, this mode only
2554 works in HTTP close mode. Unless the application behaviour is
2555 very complex and/or broken, it is advised not to start with this
2556 mode for new deployments. This keyword is incompatible with
2557 "insert" and "prefix".
2558
2559 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02002560 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002561
Willy Tarreaua79094d2010-08-31 22:54:15 +02002562 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002563 server. When used without the "preserve" option, if the server
2564 emits a cookie with the same name, it will be remove before
2565 processing. For this reason, this mode can be used to upgrade
2566 existing configurations running in the "rewrite" mode. The cookie
2567 will only be a session cookie and will not be stored on the
2568 client's disk. By default, unless the "indirect" option is added,
2569 the server will see the cookies emitted by the client. Due to
2570 caching effects, it is generally wise to add the "nocache" or
2571 "postonly" keywords (see below). The "insert" keyword is not
2572 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002573
2574 prefix This keyword indicates that instead of relying on a dedicated
2575 cookie for the persistence, an existing one will be completed.
2576 This may be needed in some specific environments where the client
2577 does not support more than one single cookie and the application
2578 already needs it. In this case, whenever the server sets a cookie
2579 named <name>, it will be prefixed with the server's identifier
2580 and a delimiter. The prefix will be removed from all client
2581 requests so that the server still finds the cookie it emitted.
2582 Since all requests and responses are subject to being modified,
2583 this mode requires the HTTP close mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02002584 not compatible with "rewrite" and "insert". Note: it is highly
2585 recommended not to use "indirect" with "prefix", otherwise server
2586 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002587
Willy Tarreaua79094d2010-08-31 22:54:15 +02002588 indirect When this option is specified, no cookie will be emitted to a
2589 client which already has a valid one for the server which has
2590 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002591 it will be removed, unless the "preserve" option is also set. In
2592 "insert" mode, this will additionally remove cookies from the
2593 requests transmitted to the server, making the persistence
2594 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02002595 Note: it is highly recommended not to use "indirect" with
2596 "prefix", otherwise server cookie updates would not be sent to
2597 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002598
2599 nocache This option is recommended in conjunction with the insert mode
2600 when there is a cache between the client and HAProxy, as it
2601 ensures that a cacheable response will be tagged non-cacheable if
2602 a cookie needs to be inserted. This is important because if all
2603 persistence cookies are added on a cacheable home page for
2604 instance, then all customers will then fetch the page from an
2605 outer cache and will all share the same persistence cookie,
2606 leading to one server receiving much more traffic than others.
2607 See also the "insert" and "postonly" options.
2608
2609 postonly This option ensures that cookie insertion will only be performed
2610 on responses to POST requests. It is an alternative to the
2611 "nocache" option, because POST responses are not cacheable, so
2612 this ensures that the persistence cookie will never get cached.
2613 Since most sites do not need any sort of persistence before the
2614 first POST which generally is a login request, this is a very
2615 efficient method to optimize caching without risking to find a
2616 persistence cookie in the cache.
2617 See also the "insert" and "nocache" options.
2618
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002619 preserve This option may only be used with "insert" and/or "indirect". It
2620 allows the server to emit the persistence cookie itself. In this
2621 case, if a cookie is found in the response, haproxy will leave it
2622 untouched. This is useful in order to end persistence after a
2623 logout request for instance. For this, the server just has to
2624 emit a cookie with an invalid value (eg: empty) or with a date in
2625 the past. By combining this mechanism with the "disable-on-404"
2626 check option, it is possible to perform a completely graceful
2627 shutdown because users will definitely leave the server after
2628 they logout.
2629
Willy Tarreau4992dd22012-05-31 21:02:17 +02002630 httponly This option tells haproxy to add an "HttpOnly" cookie attribute
2631 when a cookie is inserted. This attribute is used so that a
2632 user agent doesn't share the cookie with non-HTTP components.
2633 Please check RFC6265 for more information on this attribute.
2634
2635 secure This option tells haproxy to add a "Secure" cookie attribute when
2636 a cookie is inserted. This attribute is used so that a user agent
2637 never emits this cookie over non-secure channels, which means
2638 that a cookie learned with this flag will be presented only over
2639 SSL/TLS connections. Please check RFC6265 for more information on
2640 this attribute.
2641
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002642 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002643 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01002644 name. If the domain begins with a dot, the browser is allowed to
2645 use it for any host ending with that name. It is also possible to
2646 specify several domain names by invoking this option multiple
2647 times. Some browsers might have small limits on the number of
2648 domains, so be careful when doing that. For the record, sending
2649 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002650
Willy Tarreau996a92c2010-10-13 19:30:47 +02002651 maxidle This option allows inserted cookies to be ignored after some idle
2652 time. It only works with insert-mode cookies. When a cookie is
2653 sent to the client, the date this cookie was emitted is sent too.
2654 Upon further presentations of this cookie, if the date is older
2655 than the delay indicated by the parameter (in seconds), it will
2656 be ignored. Otherwise, it will be refreshed if needed when the
2657 response is sent to the client. This is particularly useful to
2658 prevent users who never close their browsers from remaining for
2659 too long on the same server (eg: after a farm size change). When
2660 this option is set and a cookie has no date, it is always
2661 accepted, but gets refreshed in the response. This maintains the
2662 ability for admins to access their sites. Cookies that have a
2663 date in the future further than 24 hours are ignored. Doing so
2664 lets admins fix timezone issues without risking kicking users off
2665 the site.
2666
2667 maxlife This option allows inserted cookies to be ignored after some life
2668 time, whether they're in use or not. It only works with insert
2669 mode cookies. When a cookie is first sent to the client, the date
2670 this cookie was emitted is sent too. Upon further presentations
2671 of this cookie, if the date is older than the delay indicated by
2672 the parameter (in seconds), it will be ignored. If the cookie in
2673 the request has no date, it is accepted and a date will be set.
2674 Cookies that have a date in the future further than 24 hours are
2675 ignored. Doing so lets admins fix timezone issues without risking
2676 kicking users off the site. Contrary to maxidle, this value is
2677 not refreshed, only the first visit date counts. Both maxidle and
2678 maxlife may be used at the time. This is particularly useful to
2679 prevent users who never close their browsers from remaining for
2680 too long on the same server (eg: after a farm size change). This
2681 is stronger than the maxidle method in that it forces a
2682 redispatch after some absolute delay.
2683
Willy Tarreau0ba27502007-12-24 16:55:16 +01002684 There can be only one persistence cookie per HTTP backend, and it can be
2685 declared in a defaults section. The value of the cookie will be the value
2686 indicated after the "cookie" keyword in a "server" statement. If no cookie
2687 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002688
Willy Tarreau0ba27502007-12-24 16:55:16 +01002689 Examples :
2690 cookie JSESSIONID prefix
2691 cookie SRV insert indirect nocache
2692 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02002693 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01002694
Willy Tarreau294d0f02015-08-10 19:40:12 +02002695 See also : "balance source", "capture cookie", "server" and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002696
Willy Tarreau983e01e2010-01-11 18:42:06 +01002697
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02002698declare capture [ request | response ] len <length>
2699 Declares a capture slot.
2700 May be used in sections : defaults | frontend | listen | backend
2701 no | yes | yes | no
2702 Arguments:
2703 <length> is the length allowed for the capture.
2704
2705 This declaration is only available in the frontend or listen section, but the
2706 reserved slot can be used in the backends. The "request" keyword allocates a
2707 capture slot for use in the request, and "response" allocates a capture slot
2708 for use in the response.
2709
2710 See also: "capture-req", "capture-res" (sample converters),
2711 "http-request capture" and "http-response capture".
2712
2713
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002714default-server [param*]
2715 Change default options for a server in a backend
2716 May be used in sections : defaults | frontend | listen | backend
2717 yes | no | yes | yes
2718 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01002719 <param*> is a list of parameters for this server. The "default-server"
2720 keyword accepts an important number of options and has a complete
2721 section dedicated to it. Please refer to section 5 for more
2722 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002723
Willy Tarreau983e01e2010-01-11 18:42:06 +01002724 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002725 default-server inter 1000 weight 13
2726
2727 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01002728
Willy Tarreau983e01e2010-01-11 18:42:06 +01002729
Willy Tarreau0ba27502007-12-24 16:55:16 +01002730default_backend <backend>
2731 Specify the backend to use when no "use_backend" rule has been matched.
2732 May be used in sections : defaults | frontend | listen | backend
2733 yes | yes | yes | no
2734 Arguments :
2735 <backend> is the name of the backend to use.
2736
2737 When doing content-switching between frontend and backends using the
2738 "use_backend" keyword, it is often useful to indicate which backend will be
2739 used when no rule has matched. It generally is the dynamic backend which
2740 will catch all undetermined requests.
2741
Willy Tarreau0ba27502007-12-24 16:55:16 +01002742 Example :
2743
2744 use_backend dynamic if url_dyn
2745 use_backend static if url_css url_img extension_img
2746 default_backend dynamic
2747
Willy Tarreau98d04852015-05-26 12:18:29 +02002748 See also : "use_backend"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002749
Willy Tarreau0ba27502007-12-24 16:55:16 +01002750
Baptiste Assmann27f51342013-10-09 06:51:49 +02002751description <string>
2752 Describe a listen, frontend or backend.
2753 May be used in sections : defaults | frontend | listen | backend
2754 no | yes | yes | yes
2755 Arguments : string
2756
2757 Allows to add a sentence to describe the related object in the HAProxy HTML
2758 stats page. The description will be printed on the right of the object name
2759 it describes.
2760 No need to backslash spaces in the <string> arguments.
2761
2762
Willy Tarreau0ba27502007-12-24 16:55:16 +01002763disabled
2764 Disable a proxy, frontend or backend.
2765 May be used in sections : defaults | frontend | listen | backend
2766 yes | yes | yes | yes
2767 Arguments : none
2768
2769 The "disabled" keyword is used to disable an instance, mainly in order to
2770 liberate a listening port or to temporarily disable a service. The instance
2771 will still be created and its configuration will be checked, but it will be
2772 created in the "stopped" state and will appear as such in the statistics. It
2773 will not receive any traffic nor will it send any health-checks or logs. It
2774 is possible to disable many instances at once by adding the "disabled"
2775 keyword in a "defaults" section.
2776
2777 See also : "enabled"
2778
2779
Willy Tarreau5ce94572010-06-07 14:35:41 +02002780dispatch <address>:<port>
2781 Set a default server address
2782 May be used in sections : defaults | frontend | listen | backend
2783 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002784 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02002785
2786 <address> is the IPv4 address of the default server. Alternatively, a
2787 resolvable hostname is supported, but this name will be resolved
2788 during start-up.
2789
2790 <ports> is a mandatory port specification. All connections will be sent
2791 to this port, and it is not permitted to use port offsets as is
2792 possible with normal servers.
2793
Willy Tarreau787aed52011-04-15 06:45:37 +02002794 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02002795 server can take the connection. In the past it was used to forward non
2796 persistent connections to an auxiliary load balancer. Due to its simple
2797 syntax, it has also been used for simple TCP relays. It is recommended not to
2798 use it for more clarity, and to use the "server" directive instead.
2799
2800 See also : "server"
2801
2802
Willy Tarreau0ba27502007-12-24 16:55:16 +01002803enabled
2804 Enable a proxy, frontend or backend.
2805 May be used in sections : defaults | frontend | listen | backend
2806 yes | yes | yes | yes
2807 Arguments : none
2808
2809 The "enabled" keyword is used to explicitly enable an instance, when the
2810 defaults has been set to "disabled". This is very rarely used.
2811
2812 See also : "disabled"
2813
2814
2815errorfile <code> <file>
2816 Return a file contents instead of errors generated by HAProxy
2817 May be used in sections : defaults | frontend | listen | backend
2818 yes | yes | yes | yes
2819 Arguments :
2820 <code> is the HTTP status code. Currently, HAProxy is capable of
CJ Ess108b1dd2015-04-07 12:03:37 -04002821 generating codes 200, 400, 403, 405, 408, 429, 500, 502, 503, and
2822 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002823
2824 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002825 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01002826 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01002827 error pages, and to use absolute paths, since files are read
2828 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002829
2830 It is important to understand that this keyword is not meant to rewrite
2831 errors returned by the server, but errors detected and returned by HAProxy.
2832 This is why the list of supported errors is limited to a small set.
2833
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002834 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2835
Willy Tarreau0ba27502007-12-24 16:55:16 +01002836 The files are returned verbatim on the TCP socket. This allows any trick such
2837 as redirections to another URL or site, as well as tricks to clean cookies,
2838 force enable or disable caching, etc... The package provides default error
2839 files returning the same contents as default errors.
2840
Willy Tarreau59140a22009-02-22 12:02:30 +01002841 The files should not exceed the configured buffer size (BUFSIZE), which
2842 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
2843 not to put any reference to local contents (eg: images) in order to avoid
2844 loops between the client and HAProxy when all servers are down, causing an
2845 error to be returned instead of an image. For better HTTP compliance, it is
2846 recommended that all header lines end with CR-LF and not LF alone.
2847
Willy Tarreau0ba27502007-12-24 16:55:16 +01002848 The files are read at the same time as the configuration and kept in memory.
2849 For this reason, the errors continue to be returned even when the process is
2850 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01002851 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002852 403 status code and interrogating a blocked URL.
2853
2854 See also : "errorloc", "errorloc302", "errorloc303"
2855
Willy Tarreau59140a22009-02-22 12:02:30 +01002856 Example :
2857 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
Willy Tarreau2705a612014-05-23 17:38:34 +02002858 errorfile 408 /dev/null # workaround Chrome pre-connect bug
Willy Tarreau59140a22009-02-22 12:02:30 +01002859 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
2860 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
2861
Willy Tarreau2769aa02007-12-27 18:26:09 +01002862
2863errorloc <code> <url>
2864errorloc302 <code> <url>
2865 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2866 May be used in sections : defaults | frontend | listen | backend
2867 yes | yes | yes | yes
2868 Arguments :
2869 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002870 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002871
2872 <url> it is the exact contents of the "Location" header. It may contain
2873 either a relative URI to an error page hosted on the same site,
2874 or an absolute URI designating an error page on another site.
2875 Special care should be given to relative URIs to avoid redirect
2876 loops if the URI itself may generate the same error (eg: 500).
2877
2878 It is important to understand that this keyword is not meant to rewrite
2879 errors returned by the server, but errors detected and returned by HAProxy.
2880 This is why the list of supported errors is limited to a small set.
2881
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002882 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2883
Willy Tarreau2769aa02007-12-27 18:26:09 +01002884 Note that both keyword return the HTTP 302 status code, which tells the
2885 client to fetch the designated URL using the same HTTP method. This can be
2886 quite problematic in case of non-GET methods such as POST, because the URL
2887 sent to the client might not be allowed for something other than GET. To
2888 workaround this problem, please use "errorloc303" which send the HTTP 303
2889 status code, indicating to the client that the URL must be fetched with a GET
2890 request.
2891
2892 See also : "errorfile", "errorloc303"
2893
2894
2895errorloc303 <code> <url>
2896 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2897 May be used in sections : defaults | frontend | listen | backend
2898 yes | yes | yes | yes
2899 Arguments :
2900 <code> is the HTTP status code. Currently, HAProxy is capable of
2901 generating codes 400, 403, 408, 500, 502, 503, and 504.
2902
2903 <url> it is the exact contents of the "Location" header. It may contain
2904 either a relative URI to an error page hosted on the same site,
2905 or an absolute URI designating an error page on another site.
2906 Special care should be given to relative URIs to avoid redirect
2907 loops if the URI itself may generate the same error (eg: 500).
2908
2909 It is important to understand that this keyword is not meant to rewrite
2910 errors returned by the server, but errors detected and returned by HAProxy.
2911 This is why the list of supported errors is limited to a small set.
2912
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002913 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2914
Willy Tarreau2769aa02007-12-27 18:26:09 +01002915 Note that both keyword return the HTTP 303 status code, which tells the
2916 client to fetch the designated URL using the same HTTP GET method. This
2917 solves the usual problems associated with "errorloc" and the 302 code. It is
2918 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002919 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002920
2921 See also : "errorfile", "errorloc", "errorloc302"
2922
2923
Simon Horman51a1cf62015-02-03 13:00:44 +09002924email-alert from <emailaddr>
2925 Declare the from email address to be used in both the envelope and header
2926 of email alerts. This is the address that email alerts are sent from.
2927 May be used in sections: defaults | frontend | listen | backend
2928 yes | yes | yes | yes
2929
2930 Arguments :
2931
2932 <emailaddr> is the from email address to use when sending email alerts
2933
2934 Also requires "email-alert mailers" and "email-alert to" to be set
2935 and if so sending email alerts is enabled for the proxy.
2936
Simon Horman64e34162015-02-06 11:11:57 +09002937 See also : "email-alert level", "email-alert mailers",
2938 "email-alert myhostname", "email-alert to", section 3.6 about mailers.
2939
2940
2941email-alert level <level>
2942 Declare the maximum log level of messages for which email alerts will be
2943 sent. This acts as a filter on the sending of email alerts.
2944 May be used in sections: defaults | frontend | listen | backend
2945 yes | yes | yes | yes
2946
2947 Arguments :
2948
2949 <level> One of the 8 syslog levels:
2950 emerg alert crit err warning notice info debug
2951 The above syslog levels are ordered from lowest to highest.
2952
2953 By default level is alert
2954
2955 Also requires "email-alert from", "email-alert mailers" and
2956 "email-alert to" to be set and if so sending email alerts is enabled
2957 for the proxy.
2958
Simon Horman1421e212015-04-30 13:10:35 +09002959 Alerts are sent when :
2960
2961 * An un-paused server is marked as down and <level> is alert or lower
2962 * A paused server is marked as down and <level> is notice or lower
2963 * A server is marked as up or enters the drain state and <level>
2964 is notice or lower
2965 * "option log-health-checks" is enabled, <level> is info or lower,
2966 and a health check status update occurs
2967
Simon Horman64e34162015-02-06 11:11:57 +09002968 See also : "email-alert from", "email-alert mailers",
2969 "email-alert myhostname", "email-alert to",
Simon Horman51a1cf62015-02-03 13:00:44 +09002970 section 3.6 about mailers.
2971
2972
2973email-alert mailers <mailersect>
2974 Declare the mailers to be used when sending email alerts
2975 May be used in sections: defaults | frontend | listen | backend
2976 yes | yes | yes | yes
2977
2978 Arguments :
2979
2980 <mailersect> is the name of the mailers section to send email alerts.
2981
2982 Also requires "email-alert from" and "email-alert to" to be set
2983 and if so sending email alerts is enabled for the proxy.
2984
Simon Horman64e34162015-02-06 11:11:57 +09002985 See also : "email-alert from", "email-alert level", "email-alert myhostname",
2986 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09002987
2988
2989email-alert myhostname <hostname>
2990 Declare the to hostname address to be used when communicating with
2991 mailers.
2992 May be used in sections: defaults | frontend | listen | backend
2993 yes | yes | yes | yes
2994
2995 Arguments :
2996
2997 <emailaddr> is the to email address to use when sending email alerts
2998
2999 By default the systems hostname is used.
3000
3001 Also requires "email-alert from", "email-alert mailers" and
3002 "email-alert to" to be set and if so sending email alerts is enabled
3003 for the proxy.
3004
Simon Horman64e34162015-02-06 11:11:57 +09003005 See also : "email-alert from", "email-alert level", "email-alert mailers",
3006 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09003007
3008
3009email-alert to <emailaddr>
3010 Declare both the recipent address in the envelope and to address in the
3011 header of email alerts. This is the address that email alerts are sent to.
3012 May be used in sections: defaults | frontend | listen | backend
3013 yes | yes | yes | yes
3014
3015 Arguments :
3016
3017 <emailaddr> is the to email address to use when sending email alerts
3018
3019 Also requires "email-alert mailers" and "email-alert to" to be set
3020 and if so sending email alerts is enabled for the proxy.
3021
Simon Horman64e34162015-02-06 11:11:57 +09003022 See also : "email-alert from", "email-alert level", "email-alert mailers",
Simon Horman51a1cf62015-02-03 13:00:44 +09003023 "email-alert myhostname", section 3.6 about mailers.
3024
3025
Willy Tarreau4de91492010-01-22 19:10:05 +01003026force-persist { if | unless } <condition>
3027 Declare a condition to force persistence on down servers
3028 May be used in sections: defaults | frontend | listen | backend
3029 no | yes | yes | yes
3030
3031 By default, requests are not dispatched to down servers. It is possible to
3032 force this using "option persist", but it is unconditional and redispatches
3033 to a valid server if "option redispatch" is set. That leaves with very little
3034 possibilities to force some requests to reach a server which is artificially
3035 marked down for maintenance operations.
3036
3037 The "force-persist" statement allows one to declare various ACL-based
3038 conditions which, when met, will cause a request to ignore the down status of
3039 a server and still try to connect to it. That makes it possible to start a
3040 server, still replying an error to the health checks, and run a specially
3041 configured browser to test the service. Among the handy methods, one could
3042 use a specific source IP address, or a specific cookie. The cookie also has
3043 the advantage that it can easily be added/removed on the browser from a test
3044 page. Once the service is validated, it is then possible to open the service
3045 to the world by returning a valid response to health checks.
3046
3047 The forced persistence is enabled when an "if" condition is met, or unless an
3048 "unless" condition is met. The final redispatch is always disabled when this
3049 is used.
3050
Cyril Bonté0d4bf012010-04-25 23:21:46 +02003051 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02003052 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01003053
3054
Willy Tarreau2769aa02007-12-27 18:26:09 +01003055fullconn <conns>
3056 Specify at what backend load the servers will reach their maxconn
3057 May be used in sections : defaults | frontend | listen | backend
3058 yes | no | yes | yes
3059 Arguments :
3060 <conns> is the number of connections on the backend which will make the
3061 servers use the maximal number of connections.
3062
Willy Tarreau198a7442008-01-17 12:05:32 +01003063 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01003064 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01003065 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01003066 load. The server will then always accept at least <minconn> connections,
3067 never more than <maxconn>, and the limit will be on the ramp between both
3068 values when the backend has less than <conns> concurrent connections. This
3069 makes it possible to limit the load on the servers during normal loads, but
3070 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003071 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003072
Willy Tarreaufbb78422011-06-05 15:38:35 +02003073 Since it's hard to get this value right, haproxy automatically sets it to
3074 10% of the sum of the maxconns of all frontends that may branch to this
Bertrand Jacquin702d44f2013-11-19 11:43:06 +01003075 backend (based on "use_backend" and "default_backend" rules). That way it's
3076 safe to leave it unset. However, "use_backend" involving dynamic names are
3077 not counted since there is no way to know if they could match or not.
Willy Tarreaufbb78422011-06-05 15:38:35 +02003078
Willy Tarreau2769aa02007-12-27 18:26:09 +01003079 Example :
3080 # The servers will accept between 100 and 1000 concurrent connections each
3081 # and the maximum of 1000 will be reached when the backend reaches 10000
3082 # connections.
3083 backend dynamic
3084 fullconn 10000
3085 server srv1 dyn1:80 minconn 100 maxconn 1000
3086 server srv2 dyn2:80 minconn 100 maxconn 1000
3087
3088 See also : "maxconn", "server"
3089
3090
3091grace <time>
3092 Maintain a proxy operational for some time after a soft stop
3093 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01003094 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01003095 Arguments :
3096 <time> is the time (by default in milliseconds) for which the instance
3097 will remain operational with the frontend sockets still listening
3098 when a soft-stop is received via the SIGUSR1 signal.
3099
3100 This may be used to ensure that the services disappear in a certain order.
3101 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003102 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01003103 needed by the equipment to detect the failure.
3104
3105 Note that currently, there is very little benefit in using this parameter,
3106 and it may in fact complicate the soft-reconfiguration process more than
3107 simplify it.
3108
Willy Tarreau0ba27502007-12-24 16:55:16 +01003109
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003110hash-type <method> <function> <modifier>
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003111 Specify a method to use for mapping hashes to servers
3112 May be used in sections : defaults | frontend | listen | backend
3113 yes | no | yes | yes
3114 Arguments :
Bhaskar98634f02013-10-29 23:30:51 -04003115 <method> is the method used to select a server from the hash computed by
3116 the <function> :
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003117
Bhaskar98634f02013-10-29 23:30:51 -04003118 map-based the hash table is a static array containing all alive servers.
3119 The hashes will be very smooth, will consider weights, but
3120 will be static in that weight changes while a server is up
3121 will be ignored. This means that there will be no slow start.
3122 Also, since a server is selected by its position in the array,
3123 most mappings are changed when the server count changes. This
3124 means that when a server goes up or down, or when a server is
3125 added to a farm, most connections will be redistributed to
3126 different servers. This can be inconvenient with caches for
3127 instance.
Willy Tarreau798a39c2010-11-24 15:04:29 +01003128
Bhaskar98634f02013-10-29 23:30:51 -04003129 consistent the hash table is a tree filled with many occurrences of each
3130 server. The hash key is looked up in the tree and the closest
3131 server is chosen. This hash is dynamic, it supports changing
3132 weights while the servers are up, so it is compatible with the
3133 slow start feature. It has the advantage that when a server
3134 goes up or down, only its associations are moved. When a
3135 server is added to the farm, only a few part of the mappings
3136 are redistributed, making it an ideal method for caches.
3137 However, due to its principle, the distribution will never be
3138 very smooth and it may sometimes be necessary to adjust a
3139 server's weight or its ID to get a more balanced distribution.
3140 In order to get the same distribution on multiple load
3141 balancers, it is important that all servers have the exact
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003142 same IDs. Note: consistent hash uses sdbm and avalanche if no
3143 hash function is specified.
Bhaskar98634f02013-10-29 23:30:51 -04003144
3145 <function> is the hash function to be used :
3146
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03003147 sdbm this function was created initially for sdbm (a public-domain
Bhaskar98634f02013-10-29 23:30:51 -04003148 reimplementation of ndbm) database library. It was found to do
3149 well in scrambling bits, causing better distribution of the keys
3150 and fewer splits. It also happens to be a good general hashing
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003151 function with good distribution, unless the total server weight
3152 is a multiple of 64, in which case applying the avalanche
3153 modifier may help.
Bhaskar98634f02013-10-29 23:30:51 -04003154
3155 djb2 this function was first proposed by Dan Bernstein many years ago
3156 on comp.lang.c. Studies have shown that for certain workload this
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003157 function provides a better distribution than sdbm. It generally
3158 works well with text-based inputs though it can perform extremely
3159 poorly with numeric-only input or when the total server weight is
3160 a multiple of 33, unless the avalanche modifier is also used.
3161
Willy Tarreaua0f42712013-11-14 14:30:35 +01003162 wt6 this function was designed for haproxy while testing other
3163 functions in the past. It is not as smooth as the other ones, but
3164 is much less sensible to the input data set or to the number of
3165 servers. It can make sense as an alternative to sdbm+avalanche or
3166 djb2+avalanche for consistent hashing or when hashing on numeric
3167 data such as a source IP address or a visitor identifier in a URL
3168 parameter.
3169
Willy Tarreau324f07f2015-01-20 19:44:50 +01003170 crc32 this is the most common CRC32 implementation as used in Ethernet,
3171 gzip, PNG, etc. It is slower than the other ones but may provide
3172 a better distribution or less predictable results especially when
3173 used on strings.
3174
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05003175 <modifier> indicates an optional method applied after hashing the key :
3176
3177 avalanche This directive indicates that the result from the hash
3178 function above should not be used in its raw form but that
3179 a 4-byte full avalanche hash must be applied first. The
3180 purpose of this step is to mix the resulting bits from the
3181 previous hash in order to avoid any undesired effect when
3182 the input contains some limited values or when the number of
3183 servers is a multiple of one of the hash's components (64
3184 for SDBM, 33 for DJB2). Enabling avalanche tends to make the
3185 result less predictable, but it's also not as smooth as when
3186 using the original function. Some testing might be needed
3187 with some workloads. This hash is one of the many proposed
3188 by Bob Jenkins.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003189
Bhaskar98634f02013-10-29 23:30:51 -04003190 The default hash type is "map-based" and is recommended for most usages. The
3191 default function is "sdbm", the selection of a function should be based on
3192 the range of the values being hashed.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003193
3194 See also : "balance", "server"
3195
3196
Willy Tarreau0ba27502007-12-24 16:55:16 +01003197http-check disable-on-404
3198 Enable a maintenance mode upon HTTP/404 response to health-checks
3199 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01003200 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01003201 Arguments : none
3202
3203 When this option is set, a server which returns an HTTP code 404 will be
3204 excluded from further load-balancing, but will still receive persistent
3205 connections. This provides a very convenient method for Web administrators
3206 to perform a graceful shutdown of their servers. It is also important to note
3207 that a server which is detected as failed while it was in this mode will not
3208 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
3209 will immediately be reinserted into the farm. The status on the stats page
3210 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01003211 option only works in conjunction with the "httpchk" option. If this option
3212 is used with "http-check expect", then it has precedence over it so that 404
3213 responses will still be considered as soft-stop.
3214
3215 See also : "option httpchk", "http-check expect"
3216
3217
3218http-check expect [!] <match> <pattern>
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003219 Make HTTP health checks consider response contents or specific status codes
Willy Tarreaubd741542010-03-16 18:46:54 +01003220 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau1ee51a62011-08-19 20:04:17 +02003221 yes | no | yes | yes
Willy Tarreaubd741542010-03-16 18:46:54 +01003222 Arguments :
3223 <match> is a keyword indicating how to look for a specific pattern in the
3224 response. The keyword may be one of "status", "rstatus",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003225 "string", or "rstring". The keyword may be preceded by an
Willy Tarreaubd741542010-03-16 18:46:54 +01003226 exclamation mark ("!") to negate the match. Spaces are allowed
3227 between the exclamation mark and the keyword. See below for more
3228 details on the supported keywords.
3229
3230 <pattern> is the pattern to look for. It may be a string or a regular
3231 expression. If the pattern contains spaces, they must be escaped
3232 with the usual backslash ('\').
3233
3234 By default, "option httpchk" considers that response statuses 2xx and 3xx
3235 are valid, and that others are invalid. When "http-check expect" is used,
3236 it defines what is considered valid or invalid. Only one "http-check"
3237 statement is supported in a backend. If a server fails to respond or times
3238 out, the check obviously fails. The available matches are :
3239
3240 status <string> : test the exact string match for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003241 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01003242 response's status code is exactly this string. If the
3243 "status" keyword is prefixed with "!", then the response
3244 will be considered invalid if the status code matches.
3245
3246 rstatus <regex> : test a regular expression for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003247 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01003248 response's status code matches the expression. If the
3249 "rstatus" keyword is prefixed with "!", then the response
3250 will be considered invalid if the status code matches.
3251 This is mostly used to check for multiple codes.
3252
3253 string <string> : test the exact string match in the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003254 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01003255 response's body contains this exact string. If the
3256 "string" keyword is prefixed with "!", then the response
3257 will be considered invalid if the body contains this
3258 string. This can be used to look for a mandatory word at
3259 the end of a dynamic page, or to detect a failure when a
3260 specific error appears on the check page (eg: a stack
3261 trace).
3262
3263 rstring <regex> : test a regular expression on the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003264 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01003265 response's body matches this expression. If the "rstring"
3266 keyword is prefixed with "!", then the response will be
3267 considered invalid if the body matches the expression.
3268 This can be used to look for a mandatory word at the end
3269 of a dynamic page, or to detect a failure when a specific
3270 error appears on the check page (eg: a stack trace).
3271
3272 It is important to note that the responses will be limited to a certain size
3273 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
3274 Thus, too large responses may not contain the mandatory pattern when using
3275 "string" or "rstring". If a large response is absolutely required, it is
3276 possible to change the default max size by setting the global variable.
3277 However, it is worth keeping in mind that parsing very large responses can
3278 waste some CPU cycles, especially when regular expressions are used, and that
3279 it is always better to focus the checks on smaller resources.
3280
Cyril Bonté32602d22015-01-30 00:07:07 +01003281 Also "http-check expect" doesn't support HTTP keep-alive. Keep in mind that it
3282 will automatically append a "Connection: close" header, meaning that this
3283 header should not be present in the request provided by "option httpchk".
3284
Willy Tarreaubd741542010-03-16 18:46:54 +01003285 Last, if "http-check expect" is combined with "http-check disable-on-404",
3286 then this last one has precedence when the server responds with 404.
3287
3288 Examples :
3289 # only accept status 200 as valid
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01003290 http-check expect status 200
Willy Tarreaubd741542010-03-16 18:46:54 +01003291
3292 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01003293 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01003294
3295 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01003296 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01003297
3298 # check that we have a correct hexadecimal tag before /html
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01003299 http-check expect rstring <!--tag:[0-9a-f]*</html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01003300
Willy Tarreaubd741542010-03-16 18:46:54 +01003301 See also : "option httpchk", "http-check disable-on-404"
Willy Tarreau2769aa02007-12-27 18:26:09 +01003302
3303
Willy Tarreauef781042010-01-27 11:53:01 +01003304http-check send-state
3305 Enable emission of a state header with HTTP health checks
3306 May be used in sections : defaults | frontend | listen | backend
3307 yes | no | yes | yes
3308 Arguments : none
3309
3310 When this option is set, haproxy will systematically send a special header
3311 "X-Haproxy-Server-State" with a list of parameters indicating to each server
3312 how they are seen by haproxy. This can be used for instance when a server is
3313 manipulated without access to haproxy and the operator needs to know whether
3314 haproxy still sees it up or not, or if the server is the last one in a farm.
3315
3316 The header is composed of fields delimited by semi-colons, the first of which
3317 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
3318 checks on the total number before transition, just as appears in the stats
3319 interface. Next headers are in the form "<variable>=<value>", indicating in
3320 no specific order some values available in the stats interface :
Joseph Lynch514061c2015-01-15 17:52:59 -08003321 - a variable "address", containing the address of the backend server.
3322 This corresponds to the <address> field in the server declaration. For
3323 unix domain sockets, it will read "unix".
3324
3325 - a variable "port", containing the port of the backend server. This
3326 corresponds to the <port> field in the server declaration. For unix
3327 domain sockets, it will read "unix".
3328
Willy Tarreauef781042010-01-27 11:53:01 +01003329 - a variable "name", containing the name of the backend followed by a slash
3330 ("/") then the name of the server. This can be used when a server is
3331 checked in multiple backends.
3332
3333 - a variable "node" containing the name of the haproxy node, as set in the
3334 global "node" variable, otherwise the system's hostname if unspecified.
3335
3336 - a variable "weight" indicating the weight of the server, a slash ("/")
3337 and the total weight of the farm (just counting usable servers). This
3338 helps to know if other servers are available to handle the load when this
3339 one fails.
3340
3341 - a variable "scur" indicating the current number of concurrent connections
3342 on the server, followed by a slash ("/") then the total number of
3343 connections on all servers of the same backend.
3344
3345 - a variable "qcur" indicating the current number of requests in the
3346 server's queue.
3347
3348 Example of a header received by the application server :
3349 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
3350 scur=13/22; qcur=0
3351
3352 See also : "option httpchk", "http-check disable-on-404"
3353
Willy Tarreauccbcc372012-12-27 12:37:57 +01003354http-request { allow | deny | tarpit | auth [realm <realm>] | redirect <rule> |
Willy Tarreauf4c43c12013-06-11 17:01:13 +02003355 add-header <name> <fmt> | set-header <name> <fmt> |
Thierry FOURNIER82bf70d2015-05-26 17:58:29 +02003356 capture <sample> [ len <length> | id <id> ] |
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02003357 del-header <name> | set-nice <nice> | set-log-level <level> |
Sasha Pachev218f0642014-06-16 12:05:59 -06003358 replace-header <name> <match-regex> <replace-fmt> |
3359 replace-value <name> <match-regex> <replace-fmt> |
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01003360 set-method <fmt> | set-path <fmt> | set-query <fmt> |
3361 set-uri <fmt> | set-tos <tos> | set-mark <mark> |
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02003362 add-acl(<file name>) <key fmt> |
3363 del-acl(<file name>) <key fmt> |
3364 del-map(<file name>) <key fmt> |
Baptiste Assmannbb7e86a2014-09-03 18:29:47 +02003365 set-map(<file name>) <key fmt> <value fmt> |
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02003366 set-var(<var name>) <expr> |
Thierry FOURNIER90da1912015-03-05 11:17:06 +01003367 { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] |
3368 lua <function name>
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02003369 }
Cyril Bontéf0c60612010-02-06 14:44:47 +01003370 [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01003371 Access control for Layer 7 requests
3372
3373 May be used in sections: defaults | frontend | listen | backend
3374 no | yes | yes | yes
3375
Willy Tarreau20b0de52012-12-24 15:45:22 +01003376 The http-request statement defines a set of rules which apply to layer 7
3377 processing. The rules are evaluated in their declaration order when they are
3378 met in a frontend, listen or backend section. Any rule may optionally be
3379 followed by an ACL-based condition, in which case it will only be evaluated
3380 if the condition is true.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01003381
Willy Tarreau20b0de52012-12-24 15:45:22 +01003382 The first keyword is the rule's action. Currently supported actions include :
3383 - "allow" : this stops the evaluation of the rules and lets the request
3384 pass the check. No further "http-request" rules are evaluated.
3385
3386 - "deny" : this stops the evaluation of the rules and immediately rejects
3387 the request and emits an HTTP 403 error. No further "http-request" rules
3388 are evaluated.
3389
Willy Tarreauccbcc372012-12-27 12:37:57 +01003390 - "tarpit" : this stops the evaluation of the rules and immediately blocks
3391 the request without responding for a delay specified by "timeout tarpit"
3392 or "timeout connect" if the former is not set. After that delay, if the
3393 client is still connected, an HTTP error 500 is returned so that the
3394 client does not suspect it has been tarpitted. Logs will report the flags
3395 "PT". The goal of the tarpit rule is to slow down robots during an attack
3396 when they're limited on the number of concurrent requests. It can be very
3397 efficient against very dumb robots, and will significantly reduce the
3398 load on firewalls compared to a "deny" rule. But when facing "correctly"
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03003399 developed robots, it can make things worse by forcing haproxy and the
Willy Tarreauccbcc372012-12-27 12:37:57 +01003400 front firewall to support insane number of concurrent connections.
3401
Willy Tarreau20b0de52012-12-24 15:45:22 +01003402 - "auth" : this stops the evaluation of the rules and immediately responds
3403 with an HTTP 401 or 407 error code to invite the user to present a valid
3404 user name and password. No further "http-request" rules are evaluated. An
3405 optional "realm" parameter is supported, it sets the authentication realm
3406 that is returned with the response (typically the application's name).
3407
Willy Tarreau81499eb2012-12-27 12:19:02 +01003408 - "redirect" : this performs an HTTP redirection based on a redirect rule.
3409 This is exactly the same as the "redirect" statement except that it
3410 inserts a redirect rule which can be processed in the middle of other
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01003411 "http-request" rules and that these rules use the "log-format" strings.
3412 See the "redirect" keyword for the rule's syntax.
Willy Tarreau81499eb2012-12-27 12:19:02 +01003413
Willy Tarreau20b0de52012-12-24 15:45:22 +01003414 - "add-header" appends an HTTP header field whose name is specified in
3415 <name> and whose value is defined by <fmt> which follows the log-format
3416 rules (see Custom Log Format in section 8.2.4). This is particularly
3417 useful to pass connection-specific information to the server (eg: the
3418 client's SSL certificate), or to combine several headers into one. This
3419 rule is not final, so it is possible to add other similar rules. Note
3420 that header addition is performed immediately, so one rule might reuse
3421 the resulting header from a previous rule.
3422
3423 - "set-header" does the same as "add-header" except that the header name
3424 is first removed if it existed. This is useful when passing security
3425 information to the server, where the header must not be manipulated by
Willy Tarreau85603282015-01-21 20:39:27 +01003426 external users. Note that the new value is computed before the removal so
3427 it is possible to concatenate a value to an existing header.
Willy Tarreau20b0de52012-12-24 15:45:22 +01003428
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02003429 - "del-header" removes all HTTP header fields whose name is specified in
3430 <name>.
3431
Sasha Pachev218f0642014-06-16 12:05:59 -06003432 - "replace-header" matches the regular expression in all occurrences of
3433 header field <name> according to <match-regex>, and replaces them with
3434 the <replace-fmt> argument. Format characters are allowed in replace-fmt
3435 and work like in <fmt> arguments in "add-header". The match is only
3436 case-sensitive. It is important to understand that this action only
3437 considers whole header lines, regardless of the number of values they
3438 may contain. This usage is suited to headers naturally containing commas
3439 in their value, such as If-Modified-Since and so on.
3440
3441 Example:
3442
3443 http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2
3444
3445 applied to:
3446
3447 Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT;
3448
3449 outputs:
3450
3451 Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT;
3452
3453 assuming the backend IP is 192.168.1.20
3454
3455 - "replace-value" works like "replace-header" except that it matches the
3456 regex against every comma-delimited value of the header field <name>
3457 instead of the entire header. This is suited for all headers which are
3458 allowed to carry more than one value. An example could be the Accept
3459 header.
3460
3461 Example:
3462
3463 http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1
3464
3465 applied to:
3466
3467 X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37
3468
3469 outputs:
3470
3471 X-Forwarded-For: 172.16.10.1, 172.16.13.24, 10.0.0.37
3472
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01003473 - "set-method" rewrites the request method with the result of the
3474 evaluation of format string <fmt>. There should be very few valid reasons
3475 for having to do so as this is more likely to break something than to fix
3476 it.
3477
3478 - "set-path" rewrites the request path with the result of the evaluation of
3479 format string <fmt>. The query string, if any, is left intact. If a
3480 scheme and authority is found before the path, they are left intact as
3481 well. If the request doesn't have a path ("*"), this one is replaced with
3482 the format. This can be used to prepend a directory component in front of
3483 a path for example. See also "set-query" and "set-uri".
3484
3485 Example :
3486 # prepend the host name before the path
3487 http-request set-path /%[hdr(host)]%[path]
3488
3489 - "set-query" rewrites the request's query string which appears after the
3490 first question mark ("?") with the result of the evaluation of format
3491 string <fmt>. The part prior to the question mark is left intact. If the
3492 request doesn't contain a question mark and the new value is not empty,
3493 then one is added at the end of the URI, followed by the new value. If
3494 a question mark was present, it will never be removed even if the value
3495 is empty. This can be used to add or remove parameters from the query
3496 string. See also "set-query" and "set-uri".
3497
3498 Example :
3499 # replace "%3D" with "=" in the query string
3500 http-request set-query %[query,regsub(%3D,=,g)]
3501
3502 - "set-uri" rewrites the request URI with the result of the evaluation of
3503 format string <fmt>. The scheme, authority, path and query string are all
3504 replaced at once. This can be used to rewrite hosts in front of proxies,
3505 or to perform complex modifications to the URI such as moving parts
3506 between the path and the query string. See also "set-path" and
3507 "set-query".
3508
Willy Tarreauf4c43c12013-06-11 17:01:13 +02003509 - "set-nice" sets the "nice" factor of the current request being processed.
3510 It only has effect against the other requests being processed at the same
3511 time. The default value is 0, unless altered by the "nice" setting on the
3512 "bind" line. The accepted range is -1024..1024. The higher the value, the
3513 nicest the request will be. Lower values will make the request more
3514 important than other ones. This can be useful to improve the speed of
3515 some requests, or lower the priority of non-important requests. Using
3516 this setting without prior experimentation can cause some major slowdown.
3517
Willy Tarreau9a355ec2013-06-11 17:45:46 +02003518 - "set-log-level" is used to change the log level of the current request
3519 when a certain condition is met. Valid levels are the 8 syslog levels
3520 (see the "log" keyword) plus the special level "silent" which disables
3521 logging for this request. This rule is not final so the last matching
3522 rule wins. This rule can be useful to disable health checks coming from
3523 another equipment.
3524
Willy Tarreau42cf39e2013-06-11 18:51:32 +02003525 - "set-tos" is used to set the TOS or DSCP field value of packets sent to
3526 the client to the value passed in <tos> on platforms which support this.
3527 This value represents the whole 8 bits of the IP TOS field, and can be
3528 expressed both in decimal or hexadecimal format (prefixed by "0x"). Note
3529 that only the 6 higher bits are used in DSCP or TOS, and the two lower
3530 bits are always 0. This can be used to adjust some routing behaviour on
3531 border routers based on some information from the request. See RFC 2474,
3532 2597, 3260 and 4594 for more information.
3533
Willy Tarreau51347ed2013-06-11 19:34:13 +02003534 - "set-mark" is used to set the Netfilter MARK on all packets sent to the
3535 client to the value passed in <mark> on platforms which support it. This
3536 value is an unsigned 32 bit value which can be matched by netfilter and
3537 by the routing table. It can be expressed both in decimal or hexadecimal
3538 format (prefixed by "0x"). This can be useful to force certain packets to
3539 take a different route (for example a cheaper network path for bulk
3540 downloads). This works on Linux kernels 2.6.32 and above and requires
3541 admin privileges.
3542
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02003543 - "add-acl" is used to add a new entry into an ACL. The ACL must be loaded
3544 from a file (even a dummy empty file). The file name of the ACL to be
3545 updated is passed between parentheses. It takes one argument: <key fmt>,
3546 which follows log-format rules, to collect content of the new entry. It
3547 performs a lookup in the ACL before insertion, to avoid duplicated (or
3548 more) values. This lookup is done by a linear search and can be expensive
3549 with large lists! It is the equivalent of the "add acl" command from the
3550 stats socket, but can be triggered by an HTTP request.
3551
3552 - "del-acl" is used to delete an entry from an ACL. The ACL must be loaded
3553 from a file (even a dummy empty file). The file name of the ACL to be
3554 updated is passed between parentheses. It takes one argument: <key fmt>,
3555 which follows log-format rules, to collect content of the entry to delete.
3556 It is the equivalent of the "del acl" command from the stats socket, but
3557 can be triggered by an HTTP request.
3558
3559 - "del-map" is used to delete an entry from a MAP. The MAP must be loaded
3560 from a file (even a dummy empty file). The file name of the MAP to be
3561 updated is passed between parentheses. It takes one argument: <key fmt>,
3562 which follows log-format rules, to collect content of the entry to delete.
3563 It takes one argument: "file name" It is the equivalent of the "del map"
3564 command from the stats socket, but can be triggered by an HTTP request.
3565
3566 - "set-map" is used to add a new entry into a MAP. The MAP must be loaded
3567 from a file (even a dummy empty file). The file name of the MAP to be
3568 updated is passed between parentheses. It takes 2 arguments: <key fmt>,
3569 which follows log-format rules, used to collect MAP key, and <value fmt>,
3570 which follows log-format rules, used to collect content for the new entry.
3571 It performs a lookup in the MAP before insertion, to avoid duplicated (or
3572 more) values. This lookup is done by a linear search and can be expensive
3573 with large lists! It is the equivalent of the "set map" command from the
3574 stats socket, but can be triggered by an HTTP request.
3575
Thierry FOURNIER82bf70d2015-05-26 17:58:29 +02003576 - capture <sample> [ len <length> | id <id> ] :
Willy Tarreaua9083d02015-05-08 15:27:59 +02003577 captures sample expression <sample> from the request buffer, and converts
3578 it to a string of at most <len> characters. The resulting string is
3579 stored into the next request "capture" slot, so it will possibly appear
3580 next to some captured HTTP headers. It will then automatically appear in
3581 the logs, and it will be possible to extract it using sample fetch rules
3582 to feed it into headers or anything. The length should be limited given
3583 that this size will be allocated for each capture during the whole
3584 session life. Please check section 7.3 (Fetching samples) and "capture
3585 request header" for more information.
3586
Thierry FOURNIER82bf70d2015-05-26 17:58:29 +02003587 If the keyword "id" is used instead of "len", the action tries to store
3588 the captured string in a previously declared capture slot. This is useful
3589 to run captures in backends. The slot id can be declared by a previous
3590 directive "http-request capture" or with the "declare capture" keyword.
3591
Willy Tarreau09448f72014-06-25 18:12:15 +02003592 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] :
3593 enables tracking of sticky counters from current request. These rules
3594 do not stop evaluation and do not change default action. Three sets of
3595 counters may be simultaneously tracked by the same connection. The first
3596 "track-sc0" rule executed enables tracking of the counters of the
3597 specified table as the first set. The first "track-sc1" rule executed
3598 enables tracking of the counters of the specified table as the second
3599 set. The first "track-sc2" rule executed enables tracking of the
3600 counters of the specified table as the third set. It is a recommended
3601 practice to use the first set of counters for the per-frontend counters
3602 and the second set for the per-backend ones. But this is just a
3603 guideline, all may be used everywhere.
3604
3605 These actions take one or two arguments :
3606 <key> is mandatory, and is a sample expression rule as described
3607 in section 7.3. It describes what elements of the incoming
3608 request or connection will be analysed, extracted, combined,
3609 and used to select which table entry to update the counters.
3610
3611 <table> is an optional table to be used instead of the default one,
3612 which is the stick-table declared in the current proxy. All
3613 the counters for the matches and updates for the key will
3614 then be performed in that table until the session ends.
3615
3616 Once a "track-sc*" rule is executed, the key is looked up in the table
3617 and if it is not found, an entry is allocated for it. Then a pointer to
3618 that entry is kept during all the session's life, and this entry's
3619 counters are updated as often as possible, every time the session's
3620 counters are updated, and also systematically when the session ends.
3621 Counters are only updated for events that happen after the tracking has
3622 been started. As an exception, connection counters and request counters
3623 are systematically updated so that they reflect useful information.
3624
3625 If the entry tracks concurrent connection counters, one connection is
3626 counted for as long as the entry is tracked, and the entry will not
3627 expire during that time. Tracking counters also provides a performance
3628 advantage over just checking the keys, because only one table lookup is
3629 performed for all ACL checks that make use of it.
3630
Thierry FOURNIER90da1912015-03-05 11:17:06 +01003631 - "lua" is used to run a Lua function if the action is executed. The single
3632 parameter is the name of the function to run. The prototype of the
3633 function is documented in the API documentation.
3634
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02003635 - set-var(<var-name>) <expr> :
3636 Is used to set the contents of a variable. The variable is declared
3637 inline.
3638
3639 <var-name> The name of the variable starts by an indication about its
3640 scope. The allowed scopes are:
3641 "sess" : the variable is shared with all the session,
3642 "txn" : the variable is shared with all the transaction
3643 (request and response)
3644 "req" : the variable is shared only during the request
3645 processing
3646 "res" : the variable is shared only during the response
3647 processing.
3648 This prefix is followed by a name. The separator is a '.'.
3649 The name may only contain characters 'a-z', 'A-Z', '0-9',
3650 and '_'.
3651
3652 <expr> Is a standard HAProxy expression formed by a sample-fetch
3653 followed by some converters.
3654
3655 Example:
3656
3657 http-request set-var(req.my_var) req.fhdr(user-agent),lower
3658
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02003659 - set-src <expr> :
3660 Is used to set the source IP address to the value of specified
3661 expression. Useful when a proxy in front of HAProxy rewrites source IP,
3662 but provides the correct IP in a HTTP header; or you want to mask
3663 source IP for privacy.
3664
3665 <expr> Is a standard HAProxy expression formed by a sample-fetch
3666 followed by some converters.
3667
3668 Example:
3669
3670 http-request set-src hdr(x-forwarded-for)
3671 http-request set-src src,ipmask(24)
3672
3673 When set-src is successful, the source port is set to 0.
3674
Willy Tarreau20b0de52012-12-24 15:45:22 +01003675 There is no limit to the number of http-request statements per instance.
3676
3677 It is important to know that http-request rules are processed very early in
3678 the HTTP processing, just after "block" rules and before "reqdel" or "reqrep"
3679 rules. That way, headers added by "add-header"/"set-header" are visible by
3680 almost all further ACL rules.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01003681
3682 Example:
Cyril Bonté78caf842010-03-10 22:41:43 +01003683 acl nagios src 192.168.129.3
3684 acl local_net src 192.168.0.0/16
3685 acl auth_ok http_auth(L1)
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01003686
Cyril Bonté78caf842010-03-10 22:41:43 +01003687 http-request allow if nagios
3688 http-request allow if local_net auth_ok
3689 http-request auth realm Gimme if local_net auth_ok
3690 http-request deny
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01003691
Cyril Bonté78caf842010-03-10 22:41:43 +01003692 Example:
3693 acl auth_ok http_auth_group(L1) G1
Cyril Bonté78caf842010-03-10 22:41:43 +01003694 http-request auth unless auth_ok
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01003695
Willy Tarreau20b0de52012-12-24 15:45:22 +01003696 Example:
3697 http-request set-header X-Haproxy-Current-Date %T
3698 http-request set-header X-SSL %[ssl_fc]
3699 http-request set-header X-SSL-Session_ID %[ssl_fc_session_id]
3700 http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
3701 http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
3702 http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
3703 http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
3704 http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
3705 http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
3706
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02003707 Example:
3708 acl key req.hdr(X-Add-Acl-Key) -m found
3709 acl add path /addacl
3710 acl del path /delacl
3711
3712 acl myhost hdr(Host) -f myhost.lst
3713
3714 http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add
3715 http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del
3716
3717 Example:
3718 acl value req.hdr(X-Value) -m found
3719 acl setmap path /setmap
3720 acl delmap path /delmap
3721
3722 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
3723
3724 http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value
3725 http-request del-map(map.lst) %[src] if delmap
3726
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02003727 See also : "stats http-request", section 3.4 about userlists and section 7
3728 about ACL usage.
Willy Tarreauef781042010-01-27 11:53:01 +01003729
Willy Tarreauf4c43c12013-06-11 17:01:13 +02003730http-response { allow | deny | add-header <name> <fmt> | set-nice <nice> |
Willy Tarreau51d861a2015-05-22 17:30:48 +02003731 capture <sample> id <id> | redirect <rule> |
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02003732 set-header <name> <fmt> | del-header <name> |
Sasha Pachev218f0642014-06-16 12:05:59 -06003733 replace-header <name> <regex-match> <replace-fmt> |
3734 replace-value <name> <regex-match> <replace-fmt> |
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02003735 set-log-level <level> | set-mark <mark> | set-tos <tos> |
3736 add-acl(<file name>) <key fmt> |
3737 del-acl(<file name>) <key fmt> |
3738 del-map(<file name>) <key fmt> |
Thierry FOURNIER90da1912015-03-05 11:17:06 +01003739 set-map(<file name>) <key fmt> <value fmt> |
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02003740 set-var(<var-name>) <expr> |
Thierry FOURNIER90da1912015-03-05 11:17:06 +01003741 lua <function name>
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02003742 }
Lukas Tribus2dd1d1a2013-06-19 23:34:41 +02003743 [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02003744 Access control for Layer 7 responses
3745
3746 May be used in sections: defaults | frontend | listen | backend
3747 no | yes | yes | yes
3748
3749 The http-response statement defines a set of rules which apply to layer 7
3750 processing. The rules are evaluated in their declaration order when they are
3751 met in a frontend, listen or backend section. Any rule may optionally be
3752 followed by an ACL-based condition, in which case it will only be evaluated
3753 if the condition is true. Since these rules apply on responses, the backend
3754 rules are applied first, followed by the frontend's rules.
3755
3756 The first keyword is the rule's action. Currently supported actions include :
3757 - "allow" : this stops the evaluation of the rules and lets the response
3758 pass the check. No further "http-response" rules are evaluated for the
3759 current section.
3760
3761 - "deny" : this stops the evaluation of the rules and immediately rejects
3762 the response and emits an HTTP 502 error. No further "http-response"
3763 rules are evaluated.
3764
3765 - "add-header" appends an HTTP header field whose name is specified in
3766 <name> and whose value is defined by <fmt> which follows the log-format
3767 rules (see Custom Log Format in section 8.2.4). This may be used to send
3768 a cookie to a client for example, or to pass some internal information.
3769 This rule is not final, so it is possible to add other similar rules.
3770 Note that header addition is performed immediately, so one rule might
3771 reuse the resulting header from a previous rule.
3772
3773 - "set-header" does the same as "add-header" except that the header name
3774 is first removed if it existed. This is useful when passing security
3775 information to the server, where the header must not be manipulated by
3776 external users.
3777
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02003778 - "del-header" removes all HTTP header fields whose name is specified in
3779 <name>.
3780
Sasha Pachev218f0642014-06-16 12:05:59 -06003781 - "replace-header" matches the regular expression in all occurrences of
3782 header field <name> according to <match-regex>, and replaces them with
3783 the <replace-fmt> argument. Format characters are allowed in replace-fmt
3784 and work like in <fmt> arguments in "add-header". The match is only
3785 case-sensitive. It is important to understand that this action only
3786 considers whole header lines, regardless of the number of values they
3787 may contain. This usage is suited to headers naturally containing commas
3788 in their value, such as Set-Cookie, Expires and so on.
3789
3790 Example:
3791
3792 http-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2
3793
3794 applied to:
3795
3796 Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT
3797
3798 outputs:
3799
3800 Set-Cookie: C=1;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT
3801
3802 assuming the backend IP is 192.168.1.20.
3803
3804 - "replace-value" works like "replace-header" except that it matches the
3805 regex against every comma-delimited value of the header field <name>
3806 instead of the entire header. This is suited for all headers which are
3807 allowed to carry more than one value. An example could be the Accept
3808 header.
3809
3810 Example:
3811
3812 http-response replace-value Cache-control ^public$ private
3813
3814 applied to:
3815
3816 Cache-Control: max-age=3600, public
3817
3818 outputs:
3819
3820 Cache-Control: max-age=3600, private
3821
Willy Tarreauf4c43c12013-06-11 17:01:13 +02003822 - "set-nice" sets the "nice" factor of the current request being processed.
3823 It only has effect against the other requests being processed at the same
3824 time. The default value is 0, unless altered by the "nice" setting on the
3825 "bind" line. The accepted range is -1024..1024. The higher the value, the
3826 nicest the request will be. Lower values will make the request more
3827 important than other ones. This can be useful to improve the speed of
3828 some requests, or lower the priority of non-important requests. Using
3829 this setting without prior experimentation can cause some major slowdown.
3830
Willy Tarreau9a355ec2013-06-11 17:45:46 +02003831 - "set-log-level" is used to change the log level of the current request
3832 when a certain condition is met. Valid levels are the 8 syslog levels
3833 (see the "log" keyword) plus the special level "silent" which disables
3834 logging for this request. This rule is not final so the last matching
3835 rule wins. This rule can be useful to disable health checks coming from
3836 another equipment.
3837
Willy Tarreau42cf39e2013-06-11 18:51:32 +02003838 - "set-tos" is used to set the TOS or DSCP field value of packets sent to
3839 the client to the value passed in <tos> on platforms which support this.
3840 This value represents the whole 8 bits of the IP TOS field, and can be
3841 expressed both in decimal or hexadecimal format (prefixed by "0x"). Note
3842 that only the 6 higher bits are used in DSCP or TOS, and the two lower
3843 bits are always 0. This can be used to adjust some routing behaviour on
3844 border routers based on some information from the request. See RFC 2474,
3845 2597, 3260 and 4594 for more information.
3846
Willy Tarreau51347ed2013-06-11 19:34:13 +02003847 - "set-mark" is used to set the Netfilter MARK on all packets sent to the
3848 client to the value passed in <mark> on platforms which support it. This
3849 value is an unsigned 32 bit value which can be matched by netfilter and
3850 by the routing table. It can be expressed both in decimal or hexadecimal
3851 format (prefixed by "0x"). This can be useful to force certain packets to
3852 take a different route (for example a cheaper network path for bulk
3853 downloads). This works on Linux kernels 2.6.32 and above and requires
3854 admin privileges.
3855
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02003856 - "add-acl" is used to add a new entry into an ACL. The ACL must be loaded
3857 from a file (even a dummy empty file). The file name of the ACL to be
3858 updated is passed between parentheses. It takes one argument: <key fmt>,
3859 which follows log-format rules, to collect content of the new entry. It
3860 performs a lookup in the ACL before insertion, to avoid duplicated (or
3861 more) values. This lookup is done by a linear search and can be expensive
3862 with large lists! It is the equivalent of the "add acl" command from the
3863 stats socket, but can be triggered by an HTTP response.
3864
3865 - "del-acl" is used to delete an entry from an ACL. The ACL must be loaded
3866 from a file (even a dummy empty file). The file name of the ACL to be
3867 updated is passed between parentheses. It takes one argument: <key fmt>,
3868 which follows log-format rules, to collect content of the entry to delete.
3869 It is the equivalent of the "del acl" command from the stats socket, but
3870 can be triggered by an HTTP response.
3871
3872 - "del-map" is used to delete an entry from a MAP. The MAP must be loaded
3873 from a file (even a dummy empty file). The file name of the MAP to be
3874 updated is passed between parentheses. It takes one argument: <key fmt>,
3875 which follows log-format rules, to collect content of the entry to delete.
3876 It takes one argument: "file name" It is the equivalent of the "del map"
3877 command from the stats socket, but can be triggered by an HTTP response.
3878
3879 - "set-map" is used to add a new entry into a MAP. The MAP must be loaded
3880 from a file (even a dummy empty file). The file name of the MAP to be
3881 updated is passed between parentheses. It takes 2 arguments: <key fmt>,
3882 which follows log-format rules, used to collect MAP key, and <value fmt>,
3883 which follows log-format rules, used to collect content for the new entry.
3884 It performs a lookup in the MAP before insertion, to avoid duplicated (or
3885 more) values. This lookup is done by a linear search and can be expensive
3886 with large lists! It is the equivalent of the "set map" command from the
3887 stats socket, but can be triggered by an HTTP response.
3888
Thierry FOURNIER90da1912015-03-05 11:17:06 +01003889 - "lua" is used to run a Lua function if the action is executed. The single
3890 parameter is the name of the function to run. The prototype of the
3891 function is documented in the API documentation.
3892
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02003893 - capture <sample> id <id> :
3894 captures sample expression <sample> from the response buffer, and converts
3895 it to a string. The resulting string is stored into the next request
3896 "capture" slot, so it will possibly appear next to some captured HTTP
3897 headers. It will then automatically appear in the logs, and it will be
3898 possible to extract it using sample fetch rules to feed it into headers or
3899 anything. Please check section 7.3 (Fetching samples) and "capture
3900 response header" for more information.
3901
3902 The keyword "id" is the id of the capture slot which is used for storing
3903 the string. The capture slot must be defined in an associated frontend.
3904 This is useful to run captures in backends. The slot id can be declared by
3905 a previous directive "http-response capture" or with the "declare capture"
3906 keyword.
3907
Willy Tarreau51d861a2015-05-22 17:30:48 +02003908 - "redirect" : this performs an HTTP redirection based on a redirect rule.
3909 This supports a format string similarly to "http-request redirect" rules,
3910 with the exception that only the "location" type of redirect is possible
3911 on the response. See the "redirect" keyword for the rule's syntax. When
3912 a redirect rule is applied during a response, connections to the server
3913 are closed so that no data can be forwarded from the server to the client.
3914
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02003915 - set-var(<var-name>) expr:
3916 Is used to set the contents of a variable. The variable is declared
3917 inline.
3918
3919 <var-name> The name of the variable starts by an indication about its
3920 scope. The allowed scopes are:
3921 "sess" : the variable is shared with all the session,
3922 "txn" : the variable is shared with all the transaction
3923 (request and response)
3924 "req" : the variable is shared only during the request
3925 processing
3926 "res" : the variable is shared only during the response
3927 processing.
3928 This prefix is followed by a name. The separator is a '.'.
3929 The name may only contain characters 'a-z', 'A-Z', '0-9',
3930 and '_'.
3931
3932 <expr> Is a standard HAProxy expression formed by a sample-fetch
3933 followed by some converters.
3934
3935 Example:
3936
3937 http-response set-var(sess.last_redir) res.hdr(location)
3938
Willy Tarreaue365c0b2013-06-11 16:06:12 +02003939 There is no limit to the number of http-response statements per instance.
3940
Godbach09250262013-07-02 01:19:15 +08003941 It is important to know that http-response rules are processed very early in
Willy Tarreaue365c0b2013-06-11 16:06:12 +02003942 the HTTP processing, before "reqdel" or "reqrep" rules. That way, headers
3943 added by "add-header"/"set-header" are visible by almost all further ACL
3944 rules.
3945
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02003946 Example:
3947 acl key_acl res.hdr(X-Acl-Key) -m found
3948
3949 acl myhost hdr(Host) -f myhost.lst
3950
3951 http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
3952 http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
3953
3954 Example:
3955 acl value res.hdr(X-Value) -m found
3956
3957 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
3958
3959 http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value
3960 http-response del-map(map.lst) %[src] if ! value
3961
Willy Tarreaue365c0b2013-06-11 16:06:12 +02003962 See also : "http-request", section 3.4 about userlists and section 7 about
3963 ACL usage.
3964
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02003965
Willy Tarreau30631952015-08-06 15:05:24 +02003966http-reuse { never | safe | aggressive | always }
3967 Declare how idle HTTP connections may be shared between requests
3968
3969 May be used in sections: defaults | frontend | listen | backend
3970 yes | no | yes | yes
3971
3972 By default, a connection established between haproxy and the backend server
3973 belongs to the session that initiated it. The downside is that between the
3974 response and the next request, the connection remains idle and is not used.
3975 In many cases for performance reasons it is desirable to make it possible to
3976 reuse these idle connections to serve other requests from different sessions.
3977 This directive allows to tune this behaviour.
3978
3979 The argument indicates the desired connection reuse strategy :
3980
3981 - "never" : idle connections are never shared between sessions. This is
3982 the default choice. It may be enforced to cancel a different
3983 strategy inherited from a defaults section or for
3984 troubleshooting. For example, if an old bogus application
3985 considers that multiple requests over the same connection come
3986 from the same client and it is not possible to fix the
3987 application, it may be desirable to disable connection sharing
3988 in a single backend. An example of such an application could
3989 be an old haproxy using cookie insertion in tunnel mode and
3990 not checking any request past the first one.
3991
3992 - "safe" : this is the recommended strategy. The first request of a
3993 session is always sent over its own connection, and only
3994 subsequent requests may be dispatched over other existing
3995 connections. This ensures that in case the server closes the
3996 connection when the request is being sent, the browser can
3997 decide to silently retry it. Since it is exactly equivalent to
3998 regular keep-alive, there should be no side effects.
3999
4000 - "aggressive" : this mode may be useful in webservices environments where
4001 all servers are not necessarily known and where it would be
4002 appreciable to deliver most first requests over existing
4003 connections. In this case, first requests are only delivered
4004 over existing connections that have been reused at least once,
4005 proving that the server correctly supports connection reuse.
4006 It should only be used when it's sure that the client can
4007 retry a failed request once in a while and where the benefit
4008 of aggressive connection reuse significantly outweights the
4009 downsides of rare connection failures.
4010
4011 - "always" : this mode is only recommended when the path to the server is
4012 known for never breaking existing connections quickly after
4013 releasing them. It allows the first request of a session to be
4014 sent to an existing connection. This can provide a significant
4015 performance increase over the "safe" strategy when the backend
4016 is a cache farm, since such components tend to show a
4017 consistent behaviour and will benefit from the connection
4018 sharing. It is recommended that the "http-keep-alive" timeout
4019 remains low in this mode so that no dead connections remain
4020 usable. In most cases, this will lead to the same performance
4021 gains as "aggressive" but with more risks. It should only be
4022 used when it improves the situation over "aggressive".
4023
4024 When http connection sharing is enabled, a great care is taken to respect the
4025 connection properties and compatiblities. Specifically :
4026 - connections made with "usesrc" followed by a client-dependant value
4027 ("client", "clientip", "hdr_ip") are marked private and never shared ;
4028
4029 - connections sent to a server with a TLS SNI extension are marked private
4030 and are never shared ;
4031
4032 - connections receiving a status code 401 or 407 expect some authentication
4033 to be sent in return. Due to certain bogus authentication schemes (such
4034 as NTLM) relying on the connection, these connections are marked private
4035 and are never shared ;
4036
4037 No connection pool is involved, once a session dies, the last idle connection
4038 it was attached to is deleted at the same time. This ensures that connections
4039 may not last after all sessions are closed.
4040
4041 Note: connection reuse improves the accuracy of the "server maxconn" setting,
4042 because almost no new connection will be established while idle connections
4043 remain available. This is particularly true with the "always" strategy.
4044
4045 See also : "option http-keep-alive", "server maxconn"
4046
4047
Mark Lamourinec2247f02012-01-04 13:02:01 -05004048http-send-name-header [<header>]
4049 Add the server name to a request. Use the header string given by <header>
4050
4051 May be used in sections: defaults | frontend | listen | backend
4052 yes | no | yes | yes
4053
4054 Arguments :
4055
4056 <header> The header string to use to send the server name
4057
4058 The "http-send-name-header" statement causes the name of the target
4059 server to be added to the headers of an HTTP request. The name
4060 is added with the header string proved.
4061
4062 See also : "server"
4063
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01004064id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02004065 Set a persistent ID to a proxy.
4066 May be used in sections : defaults | frontend | listen | backend
4067 no | yes | yes | yes
4068 Arguments : none
4069
4070 Set a persistent ID for the proxy. This ID must be unique and positive.
4071 An unused ID will automatically be assigned if unset. The first assigned
4072 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01004073
4074
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004075ignore-persist { if | unless } <condition>
4076 Declare a condition to ignore persistence
4077 May be used in sections: defaults | frontend | listen | backend
4078 no | yes | yes | yes
4079
4080 By default, when cookie persistence is enabled, every requests containing
4081 the cookie are unconditionally persistent (assuming the target server is up
4082 and running).
4083
4084 The "ignore-persist" statement allows one to declare various ACL-based
4085 conditions which, when met, will cause a request to ignore persistence.
4086 This is sometimes useful to load balance requests for static files, which
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03004087 often don't require persistence. This can also be used to fully disable
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004088 persistence for a specific User-Agent (for example, some web crawler bots).
4089
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004090 The persistence is ignored when an "if" condition is met, or unless an
4091 "unless" condition is met.
4092
4093 See also : "force-persist", "cookie", and section 7 about ACL usage.
4094
4095
Willy Tarreau2769aa02007-12-27 18:26:09 +01004096log global
Willy Tarreau18324f52014-06-27 18:10:07 +02004097log <address> [len <length>] <facility> [<level> [<minlevel>]]
William Lallemand0f99e342011-10-12 17:50:54 +02004098no log
Willy Tarreau2769aa02007-12-27 18:26:09 +01004099 Enable per-instance logging of events and traffic.
4100 May be used in sections : defaults | frontend | listen | backend
4101 yes | yes | yes | yes
William Lallemand0f99e342011-10-12 17:50:54 +02004102
4103 Prefix :
4104 no should be used when the logger list must be flushed. For example,
4105 if you don't want to inherit from the default logger list. This
4106 prefix does not allow arguments.
4107
Willy Tarreau2769aa02007-12-27 18:26:09 +01004108 Arguments :
4109 global should be used when the instance's logging parameters are the
4110 same as the global ones. This is the most common usage. "global"
4111 replaces <address>, <facility> and <level> with those of the log
4112 entries found in the "global" section. Only one "log global"
4113 statement may be used per instance, and this form takes no other
4114 parameter.
4115
4116 <address> indicates where to send the logs. It takes the same format as
4117 for the "global" section's logs, and can be one of :
4118
4119 - An IPv4 address optionally followed by a colon (':') and a UDP
4120 port. If no port is specified, 514 is used by default (the
4121 standard syslog port).
4122
David du Colombier24bb5f52011-03-17 10:40:23 +01004123 - An IPv6 address followed by a colon (':') and optionally a UDP
4124 port. If no port is specified, 514 is used by default (the
4125 standard syslog port).
4126
Willy Tarreau2769aa02007-12-27 18:26:09 +01004127 - A filesystem path to a UNIX domain socket, keeping in mind
4128 considerations for chroot (be sure the path is accessible
4129 inside the chroot) and uid/gid (be sure the path is
4130 appropriately writeable).
4131
William Lallemandb2f07452015-05-12 14:27:13 +02004132 You may want to reference some environment variables in the
4133 address parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01004134
Willy Tarreau18324f52014-06-27 18:10:07 +02004135 <length> is an optional maximum line length. Log lines larger than this
4136 value will be truncated before being sent. The reason is that
4137 syslog servers act differently on log line length. All servers
4138 support the default value of 1024, but some servers simply drop
4139 larger lines while others do log them. If a server supports long
4140 lines, it may make sense to set this value here in order to avoid
4141 truncating long lines. Similarly, if a server drops long lines,
4142 it is preferable to truncate them before sending them. Accepted
4143 values are 80 to 65535 inclusive. The default value of 1024 is
4144 generally fine for all standard usages. Some specific cases of
4145 long captures or JSON-formated logs may require larger values.
4146
Willy Tarreau2769aa02007-12-27 18:26:09 +01004147 <facility> must be one of the 24 standard syslog facilities :
4148
4149 kern user mail daemon auth syslog lpr news
4150 uucp cron auth2 ftp ntp audit alert cron2
4151 local0 local1 local2 local3 local4 local5 local6 local7
4152
4153 <level> is optional and can be specified to filter outgoing messages. By
4154 default, all messages are sent. If a level is specified, only
4155 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02004156 will be sent. An optional minimum level can be specified. If it
4157 is set, logs emitted with a more severe level than this one will
4158 be capped to this level. This is used to avoid sending "emerg"
4159 messages on all terminals on some default syslog configurations.
4160 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01004161
4162 emerg alert crit err warning notice info debug
4163
William Lallemand0f99e342011-10-12 17:50:54 +02004164 It is important to keep in mind that it is the frontend which decides what to
4165 log from a connection, and that in case of content switching, the log entries
4166 from the backend will be ignored. Connections are logged at level "info".
Willy Tarreaucc6c8912009-02-22 10:53:55 +01004167
4168 However, backend log declaration define how and where servers status changes
4169 will be logged. Level "notice" will be used to indicate a server going up,
4170 "warning" will be used for termination signals and definitive service
4171 termination, and "alert" will be used for when a server goes down.
4172
4173 Note : According to RFC3164, messages are truncated to 1024 bytes before
4174 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01004175
4176 Example :
4177 log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02004178 log 127.0.0.1:514 local0 notice # only send important events
4179 log 127.0.0.1:514 local0 notice notice # same but limit output level
William Lallemandb2f07452015-05-12 14:27:13 +02004180 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
Willy Tarreaudad36a32013-03-11 01:20:04 +01004181
Willy Tarreau2769aa02007-12-27 18:26:09 +01004182
William Lallemand48940402012-01-30 16:47:22 +01004183log-format <string>
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01004184 Specifies the log format string to use for traffic logs
4185 May be used in sections: defaults | frontend | listen | backend
4186 yes | yes | yes | no
William Lallemand48940402012-01-30 16:47:22 +01004187
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01004188 This directive specifies the log format string that will be used for all logs
4189 resulting from traffic passing through the frontend using this line. If the
4190 directive is used in a defaults section, all subsequent frontends will use
4191 the same log format. Please see section 8.2.4 which covers the log format
4192 string in depth.
William Lallemand48940402012-01-30 16:47:22 +01004193
Willy Tarreau094af4e2015-01-07 15:03:42 +01004194log-tag <string>
4195 Specifies the log tag to use for all outgoing logs
4196 May be used in sections: defaults | frontend | listen | backend
4197 yes | yes | yes | yes
4198
4199 Sets the tag field in the syslog header to this string. It defaults to the
4200 log-tag set in the global section, otherwise the program name as launched
4201 from the command line, which usually is "haproxy". Sometimes it can be useful
4202 to differentiate between multiple processes running on the same host, or to
4203 differentiate customer instances running in the same process. In the backend,
4204 logs about servers up/down will use this tag. As a hint, it can be convenient
4205 to set a log-tag related to a hosted customer in a defaults section then put
4206 all the frontends and backends for that customer, then start another customer
4207 in a new defaults section. See also the global "log-tag" directive.
Willy Tarreau2769aa02007-12-27 18:26:09 +01004208
Willy Tarreauc35362a2014-04-25 13:58:37 +02004209max-keep-alive-queue <value>
4210 Set the maximum server queue size for maintaining keep-alive connections
4211 May be used in sections: defaults | frontend | listen | backend
4212 yes | no | yes | yes
4213
4214 HTTP keep-alive tries to reuse the same server connection whenever possible,
4215 but sometimes it can be counter-productive, for example if a server has a lot
4216 of connections while other ones are idle. This is especially true for static
4217 servers.
4218
4219 The purpose of this setting is to set a threshold on the number of queued
4220 connections at which haproxy stops trying to reuse the same server and prefers
4221 to find another one. The default value, -1, means there is no limit. A value
4222 of zero means that keep-alive requests will never be queued. For very close
4223 servers which can be reached with a low latency and which are not sensible to
4224 breaking keep-alive, a low value is recommended (eg: local static server can
4225 use a value of 10 or less). For remote servers suffering from a high latency,
4226 higher values might be needed to cover for the latency and/or the cost of
4227 picking a different server.
4228
4229 Note that this has no impact on responses which are maintained to the same
4230 server consecutively to a 401 response. They will still go to the same server
4231 even if they have to be queued.
4232
4233 See also : "option http-server-close", "option prefer-last-server", server
4234 "maxconn" and cookie persistence.
4235
4236
Willy Tarreau2769aa02007-12-27 18:26:09 +01004237maxconn <conns>
4238 Fix the maximum number of concurrent connections on a frontend
4239 May be used in sections : defaults | frontend | listen | backend
4240 yes | yes | yes | no
4241 Arguments :
4242 <conns> is the maximum number of concurrent connections the frontend will
4243 accept to serve. Excess connections will be queued by the system
4244 in the socket's listen queue and will be served once a connection
4245 closes.
4246
4247 If the system supports it, it can be useful on big sites to raise this limit
4248 very high so that haproxy manages connection queues, instead of leaving the
4249 clients with unanswered connection attempts. This value should not exceed the
4250 global maxconn. Also, keep in mind that a connection contains two buffers
4251 of 8kB each, as well as some other data resulting in about 17 kB of RAM being
4252 consumed per established connection. That means that a medium system equipped
4253 with 1GB of RAM can withstand around 40000-50000 concurrent connections if
4254 properly tuned.
4255
4256 Also, when <conns> is set to large values, it is possible that the servers
4257 are not sized to accept such loads, and for this reason it is generally wise
4258 to assign them some reasonable connection limits.
4259
Vincent Bernat6341be52012-06-27 17:18:30 +02004260 By default, this value is set to 2000.
4261
Willy Tarreau2769aa02007-12-27 18:26:09 +01004262 See also : "server", global section's "maxconn", "fullconn"
4263
4264
4265mode { tcp|http|health }
4266 Set the running mode or protocol of the instance
4267 May be used in sections : defaults | frontend | listen | backend
4268 yes | yes | yes | yes
4269 Arguments :
4270 tcp The instance will work in pure TCP mode. A full-duplex connection
4271 will be established between clients and servers, and no layer 7
4272 examination will be performed. This is the default mode. It
4273 should be used for SSL, SSH, SMTP, ...
4274
4275 http The instance will work in HTTP mode. The client request will be
4276 analyzed in depth before connecting to any server. Any request
4277 which is not RFC-compliant will be rejected. Layer 7 filtering,
4278 processing and switching will be possible. This is the mode which
4279 brings HAProxy most of its value.
4280
4281 health The instance will work in "health" mode. It will just reply "OK"
Willy Tarreau82569f92012-09-27 23:48:56 +02004282 to incoming connections and close the connection. Alternatively,
4283 If the "httpchk" option is set, "HTTP/1.0 200 OK" will be sent
4284 instead. Nothing will be logged in either case. This mode is used
4285 to reply to external components health checks. This mode is
4286 deprecated and should not be used anymore as it is possible to do
4287 the same and even better by combining TCP or HTTP modes with the
4288 "monitor" keyword.
Willy Tarreau2769aa02007-12-27 18:26:09 +01004289
Cyril Bonté108cf6e2012-04-21 23:30:29 +02004290 When doing content switching, it is mandatory that the frontend and the
4291 backend are in the same mode (generally HTTP), otherwise the configuration
4292 will be refused.
Willy Tarreau2769aa02007-12-27 18:26:09 +01004293
Cyril Bonté108cf6e2012-04-21 23:30:29 +02004294 Example :
Willy Tarreau2769aa02007-12-27 18:26:09 +01004295 defaults http_instances
4296 mode http
4297
Cyril Bonté108cf6e2012-04-21 23:30:29 +02004298 See also : "monitor", "monitor-net"
Willy Tarreau2769aa02007-12-27 18:26:09 +01004299
Willy Tarreau0ba27502007-12-24 16:55:16 +01004300
Cyril Bontéf0c60612010-02-06 14:44:47 +01004301monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01004302 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004303 May be used in sections : defaults | frontend | listen | backend
4304 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01004305 Arguments :
4306 if <cond> the monitor request will fail if the condition is satisfied,
4307 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004308 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01004309 are met, for instance a low number of servers both in a
4310 backend and its backup.
4311
4312 unless <cond> the monitor request will succeed only if the condition is
4313 satisfied, and will fail otherwise. Such a condition may be
4314 based on a test on the presence of a minimum number of active
4315 servers in a list of backends.
4316
4317 This statement adds a condition which can force the response to a monitor
4318 request to report a failure. By default, when an external component queries
4319 the URI dedicated to monitoring, a 200 response is returned. When one of the
4320 conditions above is met, haproxy will return 503 instead of 200. This is
4321 very useful to report a site failure to an external component which may base
4322 routing advertisements between multiple sites on the availability reported by
4323 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02004324 criterion. Note that "monitor fail" only works in HTTP mode. Both status
4325 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004326
4327 Example:
4328 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01004329 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01004330 acl site_dead nbsrv(dynamic) lt 2
4331 acl site_dead nbsrv(static) lt 2
4332 monitor-uri /site_alive
4333 monitor fail if site_dead
4334
Willy Tarreauae94d4d2011-05-11 16:28:49 +02004335 See also : "monitor-net", "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01004336
4337
4338monitor-net <source>
4339 Declare a source network which is limited to monitor requests
4340 May be used in sections : defaults | frontend | listen | backend
4341 yes | yes | yes | no
4342 Arguments :
4343 <source> is the source IPv4 address or network which will only be able to
4344 get monitor responses to any request. It can be either an IPv4
4345 address, a host name, or an address followed by a slash ('/')
4346 followed by a mask.
4347
4348 In TCP mode, any connection coming from a source matching <source> will cause
4349 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004350 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01004351 forwarding the connection to a remote server.
4352
4353 In HTTP mode, a connection coming from a source matching <source> will be
4354 accepted, the following response will be sent without waiting for a request,
4355 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
4356 enough for any front-end HTTP probe to detect that the service is UP and
Willy Tarreau82569f92012-09-27 23:48:56 +02004357 running without forwarding the request to a backend server. Note that this
4358 response is sent in raw format, without any transformation. This is important
4359 as it means that it will not be SSL-encrypted on SSL listeners.
Willy Tarreau2769aa02007-12-27 18:26:09 +01004360
Willy Tarreau82569f92012-09-27 23:48:56 +02004361 Monitor requests are processed very early, just after tcp-request connection
4362 ACLs which are the only ones able to block them. These connections are short
4363 lived and never wait for any data from the client. They cannot be logged, and
4364 it is the intended purpose. They are only used to report HAProxy's health to
4365 an upper component, nothing more. Please note that "monitor fail" rules do
4366 not apply to connections intercepted by "monitor-net".
Willy Tarreau2769aa02007-12-27 18:26:09 +01004367
Willy Tarreau95cd2832010-03-04 23:36:33 +01004368 Last, please note that only one "monitor-net" statement can be specified in
4369 a frontend. If more than one is found, only the last one will be considered.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02004370
Willy Tarreau2769aa02007-12-27 18:26:09 +01004371 Example :
4372 # addresses .252 and .253 are just probing us.
4373 frontend www
4374 monitor-net 192.168.0.252/31
4375
4376 See also : "monitor fail", "monitor-uri"
4377
4378
4379monitor-uri <uri>
4380 Intercept a URI used by external components' monitor requests
4381 May be used in sections : defaults | frontend | listen | backend
4382 yes | yes | yes | no
4383 Arguments :
4384 <uri> is the exact URI which we want to intercept to return HAProxy's
4385 health status instead of forwarding the request.
4386
4387 When an HTTP request referencing <uri> will be received on a frontend,
4388 HAProxy will not forward it nor log it, but instead will return either
4389 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
4390 conditions defined with "monitor fail". This is normally enough for any
4391 front-end HTTP probe to detect that the service is UP and running without
4392 forwarding the request to a backend server. Note that the HTTP method, the
4393 version and all headers are ignored, but the request must at least be valid
4394 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
4395
4396 Monitor requests are processed very early. It is not possible to block nor
4397 divert them using ACLs. They cannot be logged either, and it is the intended
4398 purpose. They are only used to report HAProxy's health to an upper component,
4399 nothing more. However, it is possible to add any number of conditions using
4400 "monitor fail" and ACLs so that the result can be adjusted to whatever check
4401 can be imagined (most often the number of available servers in a backend).
4402
4403 Example :
4404 # Use /haproxy_test to report haproxy's status
4405 frontend www
4406 mode http
4407 monitor-uri /haproxy_test
4408
4409 See also : "monitor fail", "monitor-net"
4410
Willy Tarreau0ba27502007-12-24 16:55:16 +01004411
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004412option abortonclose
4413no option abortonclose
4414 Enable or disable early dropping of aborted requests pending in queues.
4415 May be used in sections : defaults | frontend | listen | backend
4416 yes | no | yes | yes
4417 Arguments : none
4418
4419 In presence of very high loads, the servers will take some time to respond.
4420 The per-instance connection queue will inflate, and the response time will
4421 increase respective to the size of the queue times the average per-session
4422 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01004423 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004424 the queue, and slowing down other users, and the servers as well, because the
4425 request will eventually be served, then aborted at the first error
4426 encountered while delivering the response.
4427
4428 As there is no way to distinguish between a full STOP and a simple output
4429 close on the client side, HTTP agents should be conservative and consider
4430 that the client might only have closed its output channel while waiting for
4431 the response. However, this introduces risks of congestion when lots of users
4432 do the same, and is completely useless nowadays because probably no client at
4433 all will close the session while waiting for the response. Some HTTP agents
Willy Tarreaud72758d2010-01-12 10:42:19 +01004434 support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004435 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01004436 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004437 of being the single component to break rare but valid traffic is extremely
4438 low, which adds to the temptation to be able to abort a session early while
4439 still not served and not pollute the servers.
4440
4441 In HAProxy, the user can choose the desired behaviour using the option
4442 "abortonclose". By default (without the option) the behaviour is HTTP
4443 compliant and aborted requests will be served. But when the option is
4444 specified, a session with an incoming channel closed will be aborted while
4445 it is still possible, either pending in the queue for a connection slot, or
4446 during the connection establishment if the server has not yet acknowledged
4447 the connection request. This considerably reduces the queue size and the load
4448 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01004449 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004450
4451 If this option has been enabled in a "defaults" section, it can be disabled
4452 in a specific instance by prepending the "no" keyword before it.
4453
4454 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
4455
4456
Willy Tarreau4076a152009-04-02 15:18:36 +02004457option accept-invalid-http-request
4458no option accept-invalid-http-request
4459 Enable or disable relaxing of HTTP request parsing
4460 May be used in sections : defaults | frontend | listen | backend
4461 yes | yes | yes | no
4462 Arguments : none
4463
Willy Tarreau91852eb2015-05-01 13:26:00 +02004464 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02004465 means that invalid characters in header names are not permitted and cause an
4466 error to be returned to the client. This is the desired behaviour as such
4467 forbidden characters are essentially used to build attacks exploiting server
4468 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
4469 server will emit invalid header names for whatever reason (configuration,
4470 implementation) and the issue will not be immediately fixed. In such a case,
4471 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau422246e2012-01-07 23:54:13 +01004472 even if that does not make sense, by specifying this option. Similarly, the
4473 list of characters allowed to appear in a URI is well defined by RFC3986, and
4474 chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
4475 ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
4476 not allowed at all. Haproxy always blocks a number of them (0..32, 127). The
Willy Tarreau91852eb2015-05-01 13:26:00 +02004477 remaining ones are blocked by default unless this option is enabled. This
Willy Tarreau13317662015-05-01 13:47:08 +02004478 option also relaxes the test on the HTTP version, it allows HTTP/0.9 requests
4479 to pass through (no version specified) and multiple digits for both the major
4480 and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02004481
4482 This option should never be enabled by default as it hides application bugs
4483 and open security breaches. It should only be deployed after a problem has
4484 been confirmed.
4485
4486 When this option is enabled, erroneous header names will still be accepted in
4487 requests, but the complete request will be captured in order to permit later
Willy Tarreau422246e2012-01-07 23:54:13 +01004488 analysis using the "show errors" request on the UNIX stats socket. Similarly,
4489 requests containing invalid chars in the URI part will be logged. Doing this
Willy Tarreau4076a152009-04-02 15:18:36 +02004490 also helps confirming that the issue has been solved.
4491
4492 If this option has been enabled in a "defaults" section, it can be disabled
4493 in a specific instance by prepending the "no" keyword before it.
4494
4495 See also : "option accept-invalid-http-response" and "show errors" on the
4496 stats socket.
4497
4498
4499option accept-invalid-http-response
4500no option accept-invalid-http-response
4501 Enable or disable relaxing of HTTP response parsing
4502 May be used in sections : defaults | frontend | listen | backend
4503 yes | no | yes | yes
4504 Arguments : none
4505
Willy Tarreau91852eb2015-05-01 13:26:00 +02004506 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02004507 means that invalid characters in header names are not permitted and cause an
4508 error to be returned to the client. This is the desired behaviour as such
4509 forbidden characters are essentially used to build attacks exploiting server
4510 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
4511 server will emit invalid header names for whatever reason (configuration,
4512 implementation) and the issue will not be immediately fixed. In such a case,
4513 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau91852eb2015-05-01 13:26:00 +02004514 even if that does not make sense, by specifying this option. This option also
4515 relaxes the test on the HTTP version format, it allows multiple digits for
4516 both the major and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02004517
4518 This option should never be enabled by default as it hides application bugs
4519 and open security breaches. It should only be deployed after a problem has
4520 been confirmed.
4521
4522 When this option is enabled, erroneous header names will still be accepted in
4523 responses, but the complete response will be captured in order to permit
4524 later analysis using the "show errors" request on the UNIX stats socket.
4525 Doing this also helps confirming that the issue has been solved.
4526
4527 If this option has been enabled in a "defaults" section, it can be disabled
4528 in a specific instance by prepending the "no" keyword before it.
4529
4530 See also : "option accept-invalid-http-request" and "show errors" on the
4531 stats socket.
4532
4533
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004534option allbackups
4535no option allbackups
4536 Use either all backup servers at a time or only the first one
4537 May be used in sections : defaults | frontend | listen | backend
4538 yes | no | yes | yes
4539 Arguments : none
4540
4541 By default, the first operational backup server gets all traffic when normal
4542 servers are all down. Sometimes, it may be preferred to use multiple backups
4543 at once, because one will not be enough. When "option allbackups" is enabled,
4544 the load balancing will be performed among all backup servers when all normal
4545 ones are unavailable. The same load balancing algorithm will be used and the
4546 servers' weights will be respected. Thus, there will not be any priority
4547 order between the backup servers anymore.
4548
4549 This option is mostly used with static server farms dedicated to return a
4550 "sorry" page when an application is completely offline.
4551
4552 If this option has been enabled in a "defaults" section, it can be disabled
4553 in a specific instance by prepending the "no" keyword before it.
4554
4555
4556option checkcache
4557no option checkcache
Godbach7056a352013-12-11 20:01:07 +08004558 Analyze all server responses and block responses with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004559 May be used in sections : defaults | frontend | listen | backend
4560 yes | no | yes | yes
4561 Arguments : none
4562
4563 Some high-level frameworks set application cookies everywhere and do not
4564 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004565 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004566 high risk of session crossing or stealing between users traversing the same
4567 caches. In some situations, it is better to block the response than to let
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02004568 some sensitive session information go in the wild.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004569
4570 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004571 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01004572 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004573 response to check if there's a risk of caching a cookie on a client-side
4574 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01004575 to the client are :
4576 - all those without "Set-Cookie" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004577 - all those with a return code other than 200, 203, 206, 300, 301, 410,
Willy Tarreau198a7442008-01-17 12:05:32 +01004578 provided that the server has not set a "Cache-control: public" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004579 - all those that come from a POST request, provided that the server has not
4580 set a 'Cache-Control: public' header ;
4581 - those with a 'Pragma: no-cache' header
4582 - those with a 'Cache-control: private' header
4583 - those with a 'Cache-control: no-store' header
4584 - those with a 'Cache-control: max-age=0' header
4585 - those with a 'Cache-control: s-maxage=0' header
4586 - those with a 'Cache-control: no-cache' header
4587 - those with a 'Cache-control: no-cache="set-cookie"' header
4588 - those with a 'Cache-control: no-cache="set-cookie,' header
4589 (allowing other fields after set-cookie)
4590
4591 If a response doesn't respect these requirements, then it will be blocked
Willy Tarreau198a7442008-01-17 12:05:32 +01004592 just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004593 The session state shows "PH--" meaning that the proxy blocked the response
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004594 during headers processing. Additionally, an alert will be sent in the logs so
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004595 that admins are informed that there's something to be fixed.
4596
4597 Due to the high impact on the application, the application should be tested
4598 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004599 good practice to always activate it during tests, even if it is not used in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004600 production, as it will report potentially dangerous application behaviours.
4601
4602 If this option has been enabled in a "defaults" section, it can be disabled
4603 in a specific instance by prepending the "no" keyword before it.
4604
4605
4606option clitcpka
4607no option clitcpka
4608 Enable or disable the sending of TCP keepalive packets on the client side
4609 May be used in sections : defaults | frontend | listen | backend
4610 yes | yes | yes | no
4611 Arguments : none
4612
4613 When there is a firewall or any session-aware component between a client and
4614 a server, and when the protocol involves very long sessions with long idle
4615 periods (eg: remote desktops), there is a risk that one of the intermediate
4616 components decides to expire a session which has remained idle for too long.
4617
4618 Enabling socket-level TCP keep-alives makes the system regularly send packets
4619 to the other end of the connection, leaving it active. The delay between
4620 keep-alive probes is controlled by the system only and depends both on the
4621 operating system and its tuning parameters.
4622
4623 It is important to understand that keep-alive packets are neither emitted nor
4624 received at the application level. It is only the network stacks which sees
4625 them. For this reason, even if one side of the proxy already uses keep-alives
4626 to maintain its connection alive, those keep-alive packets will not be
4627 forwarded to the other side of the proxy.
4628
4629 Please note that this has nothing to do with HTTP keep-alive.
4630
4631 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
4632 client side of a connection, which should help when session expirations are
4633 noticed between HAProxy and a client.
4634
4635 If this option has been enabled in a "defaults" section, it can be disabled
4636 in a specific instance by prepending the "no" keyword before it.
4637
4638 See also : "option srvtcpka", "option tcpka"
4639
4640
Willy Tarreau0ba27502007-12-24 16:55:16 +01004641option contstats
4642 Enable continuous traffic statistics updates
4643 May be used in sections : defaults | frontend | listen | backend
4644 yes | yes | yes | no
4645 Arguments : none
4646
4647 By default, counters used for statistics calculation are incremented
4648 only when a session finishes. It works quite well when serving small
4649 objects, but with big ones (for example large images or archives) or
4650 with A/V streaming, a graph generated from haproxy counters looks like
4651 a hedgehog. With this option enabled counters get incremented continuously,
4652 during a whole session. Recounting touches a hotpath directly so
4653 it is not enabled by default, as it has small performance impact (~0.5%).
4654
4655
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02004656option dontlog-normal
4657no option dontlog-normal
4658 Enable or disable logging of normal, successful connections
4659 May be used in sections : defaults | frontend | listen | backend
4660 yes | yes | yes | no
4661 Arguments : none
4662
4663 There are large sites dealing with several thousand connections per second
4664 and for which logging is a major pain. Some of them are even forced to turn
4665 logs off and cannot debug production issues. Setting this option ensures that
4666 normal connections, those which experience no error, no timeout, no retry nor
4667 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
4668 mode, the response status code is checked and return codes 5xx will still be
4669 logged.
4670
4671 It is strongly discouraged to use this option as most of the time, the key to
4672 complex issues is in the normal logs which will not be logged here. If you
4673 need to separate logs, see the "log-separate-errors" option instead.
4674
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004675 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02004676 logging.
4677
4678
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004679option dontlognull
4680no option dontlognull
4681 Enable or disable logging of null connections
4682 May be used in sections : defaults | frontend | listen | backend
4683 yes | yes | yes | no
4684 Arguments : none
4685
4686 In certain environments, there are components which will regularly connect to
4687 various systems to ensure that they are still alive. It can be the case from
4688 another load balancer as well as from monitoring systems. By default, even a
4689 simple port probe or scan will produce a log. If those connections pollute
4690 the logs too much, it is possible to enable option "dontlognull" to indicate
4691 that a connection on which no data has been transferred will not be logged,
Willy Tarreau0f228a02015-05-01 15:37:53 +02004692 which typically corresponds to those probes. Note that errors will still be
4693 returned to the client and accounted for in the stats. If this is not what is
4694 desired, option http-ignore-probes can be used instead.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004695
4696 It is generally recommended not to use this option in uncontrolled
4697 environments (eg: internet), otherwise scans and other malicious activities
4698 would not be logged.
4699
4700 If this option has been enabled in a "defaults" section, it can be disabled
4701 in a specific instance by prepending the "no" keyword before it.
4702
Willy Tarreau0f228a02015-05-01 15:37:53 +02004703 See also : "log", "http-ignore-probes", "monitor-net", "monitor-uri", and
4704 section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004705
4706
4707option forceclose
4708no option forceclose
4709 Enable or disable active connection closing after response is transferred.
4710 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaua31e5df2009-12-30 01:10:35 +01004711 yes | yes | yes | yes
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004712 Arguments : none
4713
4714 Some HTTP servers do not necessarily close the connections when they receive
4715 the "Connection: close" set by "option httpclose", and if the client does not
4716 close either, then the connection remains open till the timeout expires. This
4717 causes high number of simultaneous connections on the servers and shows high
4718 global session times in the logs.
4719
4720 When this happens, it is possible to use "option forceclose". It will
Willy Tarreau82eeaf22009-12-29 12:09:05 +01004721 actively close the outgoing server channel as soon as the server has finished
Cyril Bonté653dcd62014-02-20 00:13:15 +01004722 to respond and release some resources earlier than with "option httpclose".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004723
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02004724 This option may also be combined with "option http-pretend-keepalive", which
4725 will disable sending of the "Connection: close" header, but will still cause
4726 the connection to be closed once the whole response is received.
4727
Cyril Bonté653dcd62014-02-20 00:13:15 +01004728 This option disables and replaces any previous "option httpclose", "option
4729 http-server-close", "option http-keep-alive", or "option http-tunnel".
Willy Tarreau02bce8b2014-01-30 00:15:28 +01004730
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004731 If this option has been enabled in a "defaults" section, it can be disabled
4732 in a specific instance by prepending the "no" keyword before it.
4733
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02004734 See also : "option httpclose" and "option http-pretend-keepalive"
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004735
4736
Willy Tarreau87cf5142011-08-19 22:57:24 +02004737option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01004738 Enable insertion of the X-Forwarded-For header to requests sent to servers
4739 May be used in sections : defaults | frontend | listen | backend
4740 yes | yes | yes | yes
4741 Arguments :
4742 <network> is an optional argument used to disable this option for sources
4743 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02004744 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01004745 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01004746
4747 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
4748 their client address. This is sometimes annoying when the client's IP address
4749 is expected in server logs. To solve this problem, the well-known HTTP header
4750 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
4751 This header contains a value representing the client's IP address. Since this
4752 header is always appended at the end of the existing header list, the server
4753 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02004754 the server's manual to find how to enable use of this standard header. Note
4755 that only the last occurrence of the header must be used, since it is really
4756 possible that the client has already brought one.
4757
Willy Tarreaud72758d2010-01-12 10:42:19 +01004758 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02004759 the default "X-Forwarded-For". This can be useful where you might already
Willy Tarreaud72758d2010-01-12 10:42:19 +01004760 have a "X-Forwarded-For" header from a different application (eg: stunnel),
4761 and you need preserve it. Also if your backend server doesn't use the
Ross Westaf72a1d2008-08-03 10:51:45 +02004762 "X-Forwarded-For" header and requires different one (eg: Zeus Web Servers
4763 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01004764
4765 Sometimes, a same HAProxy instance may be shared between a direct client
4766 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
4767 used to decrypt HTTPS traffic). It is possible to disable the addition of the
4768 header for a known source address or network by adding the "except" keyword
4769 followed by the network address. In this case, any source IP matching the
4770 network will not cause an addition of this header. Most common uses are with
4771 private networks or 127.0.0.1.
4772
Willy Tarreau87cf5142011-08-19 22:57:24 +02004773 Alternatively, the keyword "if-none" states that the header will only be
4774 added if it is not present. This should only be used in perfectly trusted
4775 environment, as this might cause a security issue if headers reaching haproxy
4776 are under the control of the end-user.
4777
Willy Tarreauc27debf2008-01-06 08:57:02 +01004778 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02004779 least one of them uses it, the header will be added. Note that the backend's
4780 setting of the header subargument takes precedence over the frontend's if
Willy Tarreau87cf5142011-08-19 22:57:24 +02004781 both are defined. In the case of the "if-none" argument, if at least one of
4782 the frontend or the backend does not specify it, it wants the addition to be
4783 mandatory, so it wins.
Willy Tarreauc27debf2008-01-06 08:57:02 +01004784
Ross Westaf72a1d2008-08-03 10:51:45 +02004785 Examples :
Willy Tarreauc27debf2008-01-06 08:57:02 +01004786 # Public HTTP address also used by stunnel on the same machine
4787 frontend www
4788 mode http
4789 option forwardfor except 127.0.0.1 # stunnel already adds the header
4790
Ross Westaf72a1d2008-08-03 10:51:45 +02004791 # Those servers want the IP Address in X-Client
4792 backend www
4793 mode http
4794 option forwardfor header X-Client
4795
Willy Tarreau87cf5142011-08-19 22:57:24 +02004796 See also : "option httpclose", "option http-server-close",
Willy Tarreau70dffda2014-01-30 03:07:23 +01004797 "option forceclose", "option http-keep-alive"
Willy Tarreauc27debf2008-01-06 08:57:02 +01004798
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02004799
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02004800option http-buffer-request
4801no option http-buffer-request
4802 Enable or disable waiting for whole HTTP request body before proceeding
4803 May be used in sections : defaults | frontend | listen | backend
4804 yes | yes | yes | yes
4805 Arguments : none
4806
4807 It is sometimes desirable to wait for the body of an HTTP request before
4808 taking a decision. This is what is being done by "balance url_param" for
4809 example. The first use case is to buffer requests from slow clients before
4810 connecting to the server. Another use case consists in taking the routing
4811 decision based on the request body's contents. This option placed in a
4812 frontend or backend forces the HTTP processing to wait until either the whole
4813 body is received, or the request buffer is full, or the first chunk is
4814 complete in case of chunked encoding. It can have undesired side effects with
4815 some applications abusing HTTP by expecting unbufferred transmissions between
4816 the frontend and the backend, so this should definitely not be used by
4817 default.
4818
4819 See also : "option http-no-delay"
4820
4821
Willy Tarreau0f228a02015-05-01 15:37:53 +02004822option http-ignore-probes
4823no option http-ignore-probes
4824 Enable or disable logging of null connections and request timeouts
4825 May be used in sections : defaults | frontend | listen | backend
4826 yes | yes | yes | no
4827 Arguments : none
4828
4829 Recently some browsers started to implement a "pre-connect" feature
4830 consisting in speculatively connecting to some recently visited web sites
4831 just in case the user would like to visit them. This results in many
4832 connections being established to web sites, which end up in 408 Request
4833 Timeout if the timeout strikes first, or 400 Bad Request when the browser
4834 decides to close them first. These ones pollute the log and feed the error
4835 counters. There was already "option dontlognull" but it's insufficient in
4836 this case. Instead, this option does the following things :
4837 - prevent any 400/408 message from being sent to the client if nothing
4838 was received over a connection before it was closed ;
4839 - prevent any log from being emitted in this situation ;
4840 - prevent any error counter from being incremented
4841
4842 That way the empty connection is silently ignored. Note that it is better
4843 not to use this unless it is clear that it is needed, because it will hide
4844 real problems. The most common reason for not receiving a request and seeing
4845 a 408 is due to an MTU inconsistency between the client and an intermediary
4846 element such as a VPN, which blocks too large packets. These issues are
4847 generally seen with POST requests as well as GET with large cookies. The logs
4848 are often the only way to detect them.
4849
4850 If this option has been enabled in a "defaults" section, it can be disabled
4851 in a specific instance by prepending the "no" keyword before it.
4852
4853 See also : "log", "dontlognull", "errorfile", and section 8 about logging.
4854
4855
Willy Tarreau16bfb022010-01-16 19:48:41 +01004856option http-keep-alive
4857no option http-keep-alive
4858 Enable or disable HTTP keep-alive from client to server
4859 May be used in sections : defaults | frontend | listen | backend
4860 yes | yes | yes | yes
4861 Arguments : none
4862
Willy Tarreau70dffda2014-01-30 03:07:23 +01004863 By default HAProxy operates in keep-alive mode with regards to persistent
4864 connections: for each connection it processes each request and response, and
4865 leaves the connection idle on both sides between the end of a response and the
4866 start of a new request. This mode may be changed by several options such as
4867 "option http-server-close", "option forceclose", "option httpclose" or
4868 "option http-tunnel". This option allows to set back the keep-alive mode,
4869 which can be useful when another mode was used in a defaults section.
4870
4871 Setting "option http-keep-alive" enables HTTP keep-alive mode on the client-
4872 and server- sides. This provides the lowest latency on the client side (slow
Willy Tarreau16bfb022010-01-16 19:48:41 +01004873 network) and the fastest session reuse on the server side at the expense
4874 of maintaining idle connections to the servers. In general, it is possible
4875 with this option to achieve approximately twice the request rate that the
4876 "http-server-close" option achieves on small objects. There are mainly two
4877 situations where this option may be useful :
4878
4879 - when the server is non-HTTP compliant and authenticates the connection
4880 instead of requests (eg: NTLM authentication)
4881
4882 - when the cost of establishing the connection to the server is significant
4883 compared to the cost of retrieving the associated object from the server.
4884
4885 This last case can happen when the server is a fast static server of cache.
4886 In this case, the server will need to be properly tuned to support high enough
4887 connection counts because connections will last until the client sends another
4888 request.
4889
4890 If the client request has to go to another backend or another server due to
4891 content switching or the load balancing algorithm, the idle connection will
Willy Tarreau9420b122013-12-15 18:58:25 +01004892 immediately be closed and a new one re-opened. Option "prefer-last-server" is
4893 available to try optimize server selection so that if the server currently
4894 attached to an idle connection is usable, it will be used.
Willy Tarreau16bfb022010-01-16 19:48:41 +01004895
4896 In general it is preferred to use "option http-server-close" with application
4897 servers, and some static servers might benefit from "option http-keep-alive".
4898
4899 At the moment, logs will not indicate whether requests came from the same
4900 session or not. The accept date reported in the logs corresponds to the end
4901 of the previous request, and the request time corresponds to the time spent
4902 waiting for a new request. The keep-alive request time is still bound to the
4903 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
4904 not set.
4905
Cyril Bonté653dcd62014-02-20 00:13:15 +01004906 This option disables and replaces any previous "option httpclose", "option
4907 http-server-close", "option forceclose" or "option http-tunnel". When backend
Willy Tarreau70dffda2014-01-30 03:07:23 +01004908 and frontend options differ, all of these 4 options have precedence over
Cyril Bonté653dcd62014-02-20 00:13:15 +01004909 "option http-keep-alive".
Willy Tarreau16bfb022010-01-16 19:48:41 +01004910
4911 See also : "option forceclose", "option http-server-close",
Willy Tarreau9420b122013-12-15 18:58:25 +01004912 "option prefer-last-server", "option http-pretend-keepalive",
4913 "option httpclose", and "1.1. The HTTP transaction model".
Willy Tarreau16bfb022010-01-16 19:48:41 +01004914
4915
Willy Tarreau96e31212011-05-30 18:10:30 +02004916option http-no-delay
4917no option http-no-delay
4918 Instruct the system to favor low interactive delays over performance in HTTP
4919 May be used in sections : defaults | frontend | listen | backend
4920 yes | yes | yes | yes
4921 Arguments : none
4922
4923 In HTTP, each payload is unidirectional and has no notion of interactivity.
4924 Any agent is expected to queue data somewhat for a reasonably low delay.
4925 There are some very rare server-to-server applications that abuse the HTTP
4926 protocol and expect the payload phase to be highly interactive, with many
4927 interleaved data chunks in both directions within a single request. This is
4928 absolutely not supported by the HTTP specification and will not work across
4929 most proxies or servers. When such applications attempt to do this through
4930 haproxy, it works but they will experience high delays due to the network
4931 optimizations which favor performance by instructing the system to wait for
4932 enough data to be available in order to only send full packets. Typical
4933 delays are around 200 ms per round trip. Note that this only happens with
4934 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
4935 affected.
4936
4937 When "option http-no-delay" is present in either the frontend or the backend
4938 used by a connection, all such optimizations will be disabled in order to
4939 make the exchanges as fast as possible. Of course this offers no guarantee on
4940 the functionality, as it may break at any other place. But if it works via
4941 HAProxy, it will work as fast as possible. This option should never be used
4942 by default, and should never be used at all unless such a buggy application
4943 is discovered. The impact of using this option is an increase of bandwidth
4944 usage and CPU usage, which may significantly lower performance in high
4945 latency environments.
4946
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02004947 See also : "option http-buffer-request"
4948
Willy Tarreau96e31212011-05-30 18:10:30 +02004949
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02004950option http-pretend-keepalive
4951no option http-pretend-keepalive
4952 Define whether haproxy will announce keepalive to the server or not
4953 May be used in sections : defaults | frontend | listen | backend
4954 yes | yes | yes | yes
4955 Arguments : none
4956
4957 When running with "option http-server-close" or "option forceclose", haproxy
4958 adds a "Connection: close" header to the request forwarded to the server.
4959 Unfortunately, when some servers see this header, they automatically refrain
4960 from using the chunked encoding for responses of unknown length, while this
4961 is totally unrelated. The immediate effect is that this prevents haproxy from
4962 maintaining the client connection alive. A second effect is that a client or
4963 a cache could receive an incomplete response without being aware of it, and
4964 consider the response complete.
4965
4966 By setting "option http-pretend-keepalive", haproxy will make the server
4967 believe it will keep the connection alive. The server will then not fall back
4968 to the abnormal undesired above. When haproxy gets the whole response, it
4969 will close the connection with the server just as it would do with the
4970 "forceclose" option. That way the client gets a normal response and the
4971 connection is correctly closed on the server side.
4972
4973 It is recommended not to enable this option by default, because most servers
4974 will more efficiently close the connection themselves after the last packet,
4975 and release its buffers slightly earlier. Also, the added packet on the
4976 network could slightly reduce the overall peak performance. However it is
4977 worth noting that when this option is enabled, haproxy will have slightly
4978 less work to do. So if haproxy is the bottleneck on the whole architecture,
4979 enabling this option might save a few CPU cycles.
4980
4981 This option may be set both in a frontend and in a backend. It is enabled if
4982 at least one of the frontend or backend holding a connection has it enabled.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004983 This option may be combined with "option httpclose", which will cause
Willy Tarreau22a95342010-09-29 14:31:41 +02004984 keepalive to be announced to the server and close to be announced to the
4985 client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02004986
4987 If this option has been enabled in a "defaults" section, it can be disabled
4988 in a specific instance by prepending the "no" keyword before it.
4989
Willy Tarreau16bfb022010-01-16 19:48:41 +01004990 See also : "option forceclose", "option http-server-close", and
4991 "option http-keep-alive"
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02004992
Willy Tarreauc27debf2008-01-06 08:57:02 +01004993
Willy Tarreaub608feb2010-01-02 22:47:18 +01004994option http-server-close
4995no option http-server-close
4996 Enable or disable HTTP connection closing on the server side
4997 May be used in sections : defaults | frontend | listen | backend
4998 yes | yes | yes | yes
4999 Arguments : none
5000
Willy Tarreau70dffda2014-01-30 03:07:23 +01005001 By default HAProxy operates in keep-alive mode with regards to persistent
5002 connections: for each connection it processes each request and response, and
5003 leaves the connection idle on both sides between the end of a response and
5004 the start of a new request. This mode may be changed by several options such
5005 as "option http-server-close", "option forceclose", "option httpclose" or
5006 "option http-tunnel". Setting "option http-server-close" enables HTTP
5007 connection-close mode on the server side while keeping the ability to support
5008 HTTP keep-alive and pipelining on the client side. This provides the lowest
5009 latency on the client side (slow network) and the fastest session reuse on
5010 the server side to save server resources, similarly to "option forceclose".
5011 It also permits non-keepalive capable servers to be served in keep-alive mode
5012 to the clients if they conform to the requirements of RFC2616. Please note
5013 that some servers do not always conform to those requirements when they see
5014 "Connection: close" in the request. The effect will be that keep-alive will
5015 never be used. A workaround consists in enabling "option
5016 http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01005017
5018 At the moment, logs will not indicate whether requests came from the same
5019 session or not. The accept date reported in the logs corresponds to the end
5020 of the previous request, and the request time corresponds to the time spent
5021 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01005022 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
5023 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01005024
5025 This option may be set both in a frontend and in a backend. It is enabled if
5026 at least one of the frontend or backend holding a connection has it enabled.
Cyril Bonté653dcd62014-02-20 00:13:15 +01005027 It disables and replaces any previous "option httpclose", "option forceclose",
5028 "option http-tunnel" or "option http-keep-alive". Please check section 4
Willy Tarreau70dffda2014-01-30 03:07:23 +01005029 ("Proxies") to see how this option combines with others when frontend and
5030 backend options differ.
Willy Tarreaub608feb2010-01-02 22:47:18 +01005031
5032 If this option has been enabled in a "defaults" section, it can be disabled
5033 in a specific instance by prepending the "no" keyword before it.
5034
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02005035 See also : "option forceclose", "option http-pretend-keepalive",
Willy Tarreau16bfb022010-01-16 19:48:41 +01005036 "option httpclose", "option http-keep-alive", and
5037 "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01005038
5039
Willy Tarreau02bce8b2014-01-30 00:15:28 +01005040option http-tunnel
5041no option http-tunnel
5042 Disable or enable HTTP connection processing after first transaction
5043 May be used in sections : defaults | frontend | listen | backend
5044 yes | yes | yes | yes
5045 Arguments : none
5046
Willy Tarreau70dffda2014-01-30 03:07:23 +01005047 By default HAProxy operates in keep-alive mode with regards to persistent
5048 connections: for each connection it processes each request and response, and
5049 leaves the connection idle on both sides between the end of a response and
5050 the start of a new request. This mode may be changed by several options such
5051 as "option http-server-close", "option forceclose", "option httpclose" or
5052 "option http-tunnel".
5053
5054 Option "http-tunnel" disables any HTTP processing past the first request and
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03005055 the first response. This is the mode which was used by default in versions
Willy Tarreau70dffda2014-01-30 03:07:23 +01005056 1.0 to 1.5-dev21. It is the mode with the lowest processing overhead, which
5057 is normally not needed anymore unless in very specific cases such as when
5058 using an in-house protocol that looks like HTTP but is not compatible, or
5059 just to log one request per client in order to reduce log size. Note that
5060 everything which works at the HTTP level, including header parsing/addition,
5061 cookie processing or content switching will only work for the first request
5062 and will be ignored after the first response.
Willy Tarreau02bce8b2014-01-30 00:15:28 +01005063
5064 If this option has been enabled in a "defaults" section, it can be disabled
5065 in a specific instance by prepending the "no" keyword before it.
5066
5067 See also : "option forceclose", "option http-server-close",
5068 "option httpclose", "option http-keep-alive", and
5069 "1.1. The HTTP transaction model".
5070
5071
Willy Tarreau88d349d2010-01-25 12:15:43 +01005072option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01005073no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01005074 Make use of non-standard Proxy-Connection header instead of Connection
5075 May be used in sections : defaults | frontend | listen | backend
5076 yes | yes | yes | no
5077 Arguments : none
5078
5079 While RFC2616 explicitly states that HTTP/1.1 agents must use the
5080 Connection header to indicate their wish of persistent or non-persistent
5081 connections, both browsers and proxies ignore this header for proxied
5082 connections and make use of the undocumented, non-standard Proxy-Connection
5083 header instead. The issue begins when trying to put a load balancer between
5084 browsers and such proxies, because there will be a difference between what
5085 haproxy understands and what the client and the proxy agree on.
5086
5087 By setting this option in a frontend, haproxy can automatically switch to use
5088 that non-standard header if it sees proxied requests. A proxied request is
5089 defined here as one where the URI begins with neither a '/' nor a '*'. The
5090 choice of header only affects requests passing through proxies making use of
5091 one of the "httpclose", "forceclose" and "http-server-close" options. Note
5092 that this option can only be specified in a frontend and will affect the
5093 request along its whole life.
5094
Willy Tarreau844a7e72010-01-31 21:46:18 +01005095 Also, when this option is set, a request which requires authentication will
5096 automatically switch to use proxy authentication headers if it is itself a
5097 proxied request. That makes it possible to check or enforce authentication in
5098 front of an existing proxy.
5099
Willy Tarreau88d349d2010-01-25 12:15:43 +01005100 This option should normally never be used, except in front of a proxy.
5101
5102 See also : "option httpclose", "option forceclose" and "option
5103 http-server-close".
5104
5105
Willy Tarreaud63335a2010-02-26 12:56:52 +01005106option httpchk
5107option httpchk <uri>
5108option httpchk <method> <uri>
5109option httpchk <method> <uri> <version>
5110 Enable HTTP protocol to check on the servers health
5111 May be used in sections : defaults | frontend | listen | backend
5112 yes | no | yes | yes
5113 Arguments :
5114 <method> is the optional HTTP method used with the requests. When not set,
5115 the "OPTIONS" method is used, as it generally requires low server
5116 processing and is easy to filter out from the logs. Any method
5117 may be used, though it is not recommended to invent non-standard
5118 ones.
5119
5120 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
5121 which is accessible by default on almost any server, but may be
5122 changed to any other URI. Query strings are permitted.
5123
5124 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
5125 but some servers might behave incorrectly in HTTP 1.0, so turning
5126 it to HTTP/1.1 may sometimes help. Note that the Host field is
5127 mandatory in HTTP/1.1, and as a trick, it is possible to pass it
5128 after "\r\n" following the version string.
5129
5130 By default, server health checks only consist in trying to establish a TCP
5131 connection. When "option httpchk" is specified, a complete HTTP request is
5132 sent once the TCP connection is established, and responses 2xx and 3xx are
5133 considered valid, while all other ones indicate a server failure, including
5134 the lack of any response.
5135
5136 The port and interval are specified in the server configuration.
5137
5138 This option does not necessarily require an HTTP backend, it also works with
5139 plain TCP backends. This is particularly useful to check simple scripts bound
5140 to some dedicated ports using the inetd daemon.
5141
5142 Examples :
5143 # Relay HTTPS traffic to Apache instance and check service availability
5144 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
5145 backend https_relay
5146 mode tcp
5147 option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www
5148 server apache1 192.168.1.1:443 check port 80
5149
Simon Hormanafc47ee2013-11-25 10:46:35 +09005150 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
5151 "option pgsql-check", "http-check" and the "check", "port" and
5152 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01005153
5154
Willy Tarreauc27debf2008-01-06 08:57:02 +01005155option httpclose
5156no option httpclose
5157 Enable or disable passive HTTP connection closing
5158 May be used in sections : defaults | frontend | listen | backend
5159 yes | yes | yes | yes
5160 Arguments : none
5161
Willy Tarreau70dffda2014-01-30 03:07:23 +01005162 By default HAProxy operates in keep-alive mode with regards to persistent
5163 connections: for each connection it processes each request and response, and
5164 leaves the connection idle on both sides between the end of a response and
5165 the start of a new request. This mode may be changed by several options such
Cyril Bonté653dcd62014-02-20 00:13:15 +01005166 as "option http-server-close", "option forceclose", "option httpclose" or
Willy Tarreau70dffda2014-01-30 03:07:23 +01005167 "option http-tunnel".
5168
5169 If "option httpclose" is set, HAProxy will work in HTTP tunnel mode and check
5170 if a "Connection: close" header is already set in each direction, and will
5171 add one if missing. Each end should react to this by actively closing the TCP
5172 connection after each transfer, thus resulting in a switch to the HTTP close
5173 mode. Any "Connection" header different from "close" will also be removed.
5174 Note that this option is deprecated since what it does is very cheap but not
5175 reliable. Using "option http-server-close" or "option forceclose" is strongly
5176 recommended instead.
Willy Tarreauc27debf2008-01-06 08:57:02 +01005177
5178 It seldom happens that some servers incorrectly ignore this header and do not
Jamie Gloudonaaa21002012-08-25 00:18:33 -04005179 close the connection even though they reply "Connection: close". For this
Willy Tarreau0dfdf192010-01-05 11:33:11 +01005180 reason, they are not compatible with older HTTP 1.0 browsers. If this happens
5181 it is possible to use the "option forceclose" which actively closes the
5182 request connection once the server responds. Option "forceclose" also
5183 releases the server connection earlier because it does not have to wait for
5184 the client to acknowledge it.
Willy Tarreauc27debf2008-01-06 08:57:02 +01005185
5186 This option may be set both in a frontend and in a backend. It is enabled if
5187 at least one of the frontend or backend holding a connection has it enabled.
Cyril Bonté653dcd62014-02-20 00:13:15 +01005188 It disables and replaces any previous "option http-server-close",
5189 "option forceclose", "option http-keep-alive" or "option http-tunnel". Please
Willy Tarreau70dffda2014-01-30 03:07:23 +01005190 check section 4 ("Proxies") to see how this option combines with others when
5191 frontend and backend options differ.
Willy Tarreauc27debf2008-01-06 08:57:02 +01005192
5193 If this option has been enabled in a "defaults" section, it can be disabled
5194 in a specific instance by prepending the "no" keyword before it.
5195
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02005196 See also : "option forceclose", "option http-server-close" and
5197 "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01005198
5199
Emeric Brun3a058f32009-06-30 18:26:00 +02005200option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01005201 Enable logging of HTTP request, session state and timers
5202 May be used in sections : defaults | frontend | listen | backend
5203 yes | yes | yes | yes
Emeric Brun3a058f32009-06-30 18:26:00 +02005204 Arguments :
5205 clf if the "clf" argument is added, then the output format will be
5206 the CLF format instead of HAProxy's default HTTP format. You can
5207 use this when you need to feed HAProxy's logs through a specific
5208 log analyser which only support the CLF format and which is not
5209 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01005210
5211 By default, the log output format is very poor, as it only contains the
5212 source and destination addresses, and the instance name. By specifying
5213 "option httplog", each log line turns into a much richer format including,
5214 but not limited to, the HTTP request, the connection timers, the session
5215 status, the connections numbers, the captured headers and cookies, the
5216 frontend, backend and server name, and of course the source address and
5217 ports.
5218
5219 This option may be set either in the frontend or the backend.
5220
PiBa-NLbd556bf2014-12-11 21:31:54 +01005221 Specifying only "option httplog" will automatically clear the 'clf' mode
5222 if it was set by default.
Emeric Brun3a058f32009-06-30 18:26:00 +02005223
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005224 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01005225
Willy Tarreau55165fe2009-05-10 12:02:55 +02005226
5227option http_proxy
5228no option http_proxy
5229 Enable or disable plain HTTP proxy mode
5230 May be used in sections : defaults | frontend | listen | backend
5231 yes | yes | yes | yes
5232 Arguments : none
5233
5234 It sometimes happens that people need a pure HTTP proxy which understands
5235 basic proxy requests without caching nor any fancy feature. In this case,
5236 it may be worth setting up an HAProxy instance with the "option http_proxy"
5237 set. In this mode, no server is declared, and the connection is forwarded to
5238 the IP address and port found in the URL after the "http://" scheme.
5239
5240 No host address resolution is performed, so this only works when pure IP
5241 addresses are passed. Since this option's usage perimeter is rather limited,
5242 it will probably be used only by experts who know they need exactly it. Last,
5243 if the clients are susceptible of sending keep-alive requests, it will be
Cyril Bonté2409e682010-12-14 22:47:51 +01005244 needed to add "option httpclose" to ensure that all requests will correctly
Willy Tarreau55165fe2009-05-10 12:02:55 +02005245 be analyzed.
5246
5247 If this option has been enabled in a "defaults" section, it can be disabled
5248 in a specific instance by prepending the "no" keyword before it.
5249
5250 Example :
5251 # this backend understands HTTP proxy requests and forwards them directly.
5252 backend direct_forward
5253 option httpclose
5254 option http_proxy
5255
5256 See also : "option httpclose"
5257
Willy Tarreau211ad242009-10-03 21:45:07 +02005258
Jamie Gloudon801a0a32012-08-25 00:18:33 -04005259option independent-streams
5260no option independent-streams
5261 Enable or disable independent timeout processing for both directions
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02005262 May be used in sections : defaults | frontend | listen | backend
5263 yes | yes | yes | yes
5264 Arguments : none
5265
5266 By default, when data is sent over a socket, both the write timeout and the
5267 read timeout for that socket are refreshed, because we consider that there is
5268 activity on that socket, and we have no other means of guessing if we should
5269 receive data or not.
5270
5271 While this default behaviour is desirable for almost all applications, there
5272 exists a situation where it is desirable to disable it, and only refresh the
5273 read timeout if there are incoming data. This happens on sessions with large
5274 timeouts and low amounts of exchanged data such as telnet session. If the
5275 server suddenly disappears, the output data accumulates in the system's
5276 socket buffers, both timeouts are correctly refreshed, and there is no way
5277 to know the server does not receive them, so we don't timeout. However, when
5278 the underlying protocol always echoes sent data, it would be enough by itself
5279 to detect the issue using the read timeout. Note that this problem does not
5280 happen with more verbose protocols because data won't accumulate long in the
5281 socket buffers.
5282
5283 When this option is set on the frontend, it will disable read timeout updates
5284 on data sent to the client. There probably is little use of this case. When
5285 the option is set on the backend, it will disable read timeout updates on
5286 data sent to the server. Doing so will typically break large HTTP posts from
5287 slow lines, so use it with caution.
5288
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03005289 Note: older versions used to call this setting "option independent-streams"
Jamie Gloudon801a0a32012-08-25 00:18:33 -04005290 with a spelling mistake. This spelling is still supported but
5291 deprecated.
5292
Willy Tarreauce887fd2012-05-12 12:50:00 +02005293 See also : "timeout client", "timeout server" and "timeout tunnel"
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02005294
5295
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02005296option ldap-check
5297 Use LDAPv3 health checks for server testing
5298 May be used in sections : defaults | frontend | listen | backend
5299 yes | no | yes | yes
5300 Arguments : none
5301
5302 It is possible to test that the server correctly talks LDAPv3 instead of just
5303 testing that it accepts the TCP connection. When this option is set, an
5304 LDAPv3 anonymous simple bind message is sent to the server, and the response
5305 is analyzed to find an LDAPv3 bind response message.
5306
5307 The server is considered valid only when the LDAP response contains success
5308 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
5309
5310 Logging of bind requests is server dependent see your documentation how to
5311 configure it.
5312
5313 Example :
5314 option ldap-check
5315
5316 See also : "option httpchk"
5317
5318
Simon Horman98637e52014-06-20 12:30:16 +09005319option external-check
5320 Use external processes for server health checks
5321 May be used in sections : defaults | frontend | listen | backend
5322 yes | no | yes | yes
5323
5324 It is possible to test the health of a server using an external command.
5325 This is achieved by running the executable set using "external-check
5326 command".
5327
5328 Requires the "external-check" global to be set.
5329
5330 See also : "external-check", "external-check command", "external-check path"
5331
5332
Willy Tarreau211ad242009-10-03 21:45:07 +02005333option log-health-checks
5334no option log-health-checks
Willy Tarreaubef1b322014-05-13 21:01:39 +02005335 Enable or disable logging of health checks status updates
Willy Tarreau211ad242009-10-03 21:45:07 +02005336 May be used in sections : defaults | frontend | listen | backend
5337 yes | no | yes | yes
5338 Arguments : none
5339
Willy Tarreaubef1b322014-05-13 21:01:39 +02005340 By default, failed health check are logged if server is UP and successful
5341 health checks are logged if server is DOWN, so the amount of additional
5342 information is limited.
Willy Tarreau211ad242009-10-03 21:45:07 +02005343
Willy Tarreaubef1b322014-05-13 21:01:39 +02005344 When this option is enabled, any change of the health check status or to
5345 the server's health will be logged, so that it becomes possible to know
5346 that a server was failing occasional checks before crashing, or exactly when
5347 it failed to respond a valid HTTP status, then when the port started to
5348 reject connections, then when the server stopped responding at all.
5349
5350 Note that status changes not caused by health checks (eg: enable/disable on
5351 the CLI) are intentionally not logged by this option.
Willy Tarreau211ad242009-10-03 21:45:07 +02005352
Willy Tarreaubef1b322014-05-13 21:01:39 +02005353 See also: "option httpchk", "option ldap-check", "option mysql-check",
5354 "option pgsql-check", "option redis-check", "option smtpchk",
5355 "option tcp-check", "log" and section 8 about logging.
Willy Tarreau211ad242009-10-03 21:45:07 +02005356
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02005357
5358option log-separate-errors
5359no option log-separate-errors
5360 Change log level for non-completely successful connections
5361 May be used in sections : defaults | frontend | listen | backend
5362 yes | yes | yes | no
5363 Arguments : none
5364
5365 Sometimes looking for errors in logs is not easy. This option makes haproxy
5366 raise the level of logs containing potentially interesting information such
5367 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
5368 level changes from "info" to "err". This makes it possible to log them
5369 separately to a different file with most syslog daemons. Be careful not to
5370 remove them from the original file, otherwise you would lose ordering which
5371 provides very important information.
5372
5373 Using this option, large sites dealing with several thousand connections per
5374 second may log normal traffic to a rotating buffer and only archive smaller
5375 error logs.
5376
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005377 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02005378 logging.
5379
Willy Tarreauc27debf2008-01-06 08:57:02 +01005380
5381option logasap
5382no option logasap
5383 Enable or disable early logging of HTTP requests
5384 May be used in sections : defaults | frontend | listen | backend
5385 yes | yes | yes | no
5386 Arguments : none
5387
5388 By default, HTTP requests are logged upon termination so that the total
5389 transfer time and the number of bytes appear in the logs. When large objects
5390 are being transferred, it may take a while before the request appears in the
5391 logs. Using "option logasap", the request gets logged as soon as the server
5392 sends the complete headers. The only missing information in the logs will be
5393 the total number of bytes which will indicate everything except the amount
5394 of data transferred, and the total time which will not take the transfer
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01005395 time into account. In such a situation, it's a good practice to capture the
Willy Tarreauc27debf2008-01-06 08:57:02 +01005396 "Content-Length" response header so that the logs at least indicate how many
5397 bytes are expected to be transferred.
5398
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005399 Examples :
5400 listen http_proxy 0.0.0.0:80
5401 mode http
5402 option httplog
5403 option logasap
5404 log 192.168.2.200 local3
5405
5406 >>> Feb 6 12:14:14 localhost \
5407 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
5408 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
5409 "GET /image.iso HTTP/1.0"
5410
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005411 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01005412 logging.
5413
5414
Nenad Merdanovic6639a7c2014-05-30 14:26:32 +02005415option mysql-check [ user <username> [ post-41 ] ]
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02005416 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01005417 May be used in sections : defaults | frontend | listen | backend
5418 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02005419 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005420 <username> This is the username which will be used when connecting to MySQL
5421 server.
Nenad Merdanovic6639a7c2014-05-30 14:26:32 +02005422 post-41 Send post v4.1 client compatible checks
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02005423
5424 If you specify a username, the check consists of sending two MySQL packet,
5425 one Client Authentication packet, and one QUIT packet, to correctly close
5426 MySQL session. We then parse the MySQL Handshake Initialisation packet and/or
5427 Error packet. It is a basic but useful test which does not produce error nor
5428 aborted connect on the server. However, it requires adding an authorization
5429 in the MySQL table, like this :
5430
5431 USE mysql;
5432 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
5433 FLUSH PRIVILEGES;
5434
5435 If you don't specify a username (it is deprecated and not recommended), the
5436 check only consists in parsing the Mysql Handshake Initialisation packet or
5437 Error packet, we don't send anything in this mode. It was reported that it
5438 can generate lockout if check is too frequent and/or if there is not enough
5439 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
5440 value as if a connection is established successfully within fewer than MySQL
5441 "max_connect_errors" attempts after a previous connection was interrupted,
5442 the error count for the host is cleared to zero. If HAProxy's server get
5443 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
5444
5445 Remember that this does not check database presence nor database consistency.
5446 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01005447
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02005448 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01005449
5450 Most often, an incoming MySQL server needs to see the client's IP address for
5451 various purposes, including IP privilege matching and connection logging.
5452 When possible, it is often wise to masquerade the client's IP address when
5453 connecting to the server using the "usesrc" argument of the "source" keyword,
5454 which requires the cttproxy feature to be compiled in, and the MySQL server
5455 to route the client via the machine hosting haproxy.
5456
5457 See also: "option httpchk"
5458
5459
Willy Tarreaua453bdd2008-01-08 19:50:52 +01005460option nolinger
5461no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005462 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01005463 May be used in sections: defaults | frontend | listen | backend
5464 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005465 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01005466
5467 When clients or servers abort connections in a dirty way (eg: they are
5468 physically disconnected), the session timeouts triggers and the session is
5469 closed. But it will remain in FIN_WAIT1 state for some time in the system,
5470 using some resources and possibly limiting the ability to establish newer
5471 connections.
5472
5473 When this happens, it is possible to activate "option nolinger" which forces
5474 the system to immediately remove any socket's pending data on close. Thus,
5475 the session is instantly purged from the system's tables. This usually has
5476 side effects such as increased number of TCP resets due to old retransmits
5477 getting immediately rejected. Some firewalls may sometimes complain about
5478 this too.
5479
5480 For this reason, it is not recommended to use this option when not absolutely
5481 needed. You know that you need it when you have thousands of FIN_WAIT1
5482 sessions on your system (TIME_WAIT ones do not count).
5483
5484 This option may be used both on frontends and backends, depending on the side
5485 where it is required. Use it on the frontend for clients, and on the backend
5486 for servers.
5487
5488 If this option has been enabled in a "defaults" section, it can be disabled
5489 in a specific instance by prepending the "no" keyword before it.
5490
5491
Willy Tarreau55165fe2009-05-10 12:02:55 +02005492option originalto [ except <network> ] [ header <name> ]
5493 Enable insertion of the X-Original-To header to requests sent to servers
5494 May be used in sections : defaults | frontend | listen | backend
5495 yes | yes | yes | yes
5496 Arguments :
5497 <network> is an optional argument used to disable this option for sources
5498 matching <network>
5499 <name> an optional argument to specify a different "X-Original-To"
5500 header name.
5501
5502 Since HAProxy can work in transparent mode, every request from a client can
5503 be redirected to the proxy and HAProxy itself can proxy every request to a
5504 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
5505 be lost. This is annoying when you want access rules based on destination ip
5506 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
5507 added by HAProxy to all requests sent to the server. This header contains a
5508 value representing the original destination IP address. Since this must be
5509 configured to always use the last occurrence of this header only. Note that
5510 only the last occurrence of the header must be used, since it is really
5511 possible that the client has already brought one.
5512
5513 The keyword "header" may be used to supply a different header name to replace
5514 the default "X-Original-To". This can be useful where you might already
5515 have a "X-Original-To" header from a different application, and you need
5516 preserve it. Also if your backend server doesn't use the "X-Original-To"
5517 header and requires different one.
5518
5519 Sometimes, a same HAProxy instance may be shared between a direct client
5520 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
5521 used to decrypt HTTPS traffic). It is possible to disable the addition of the
5522 header for a known source address or network by adding the "except" keyword
5523 followed by the network address. In this case, any source IP matching the
5524 network will not cause an addition of this header. Most common uses are with
5525 private networks or 127.0.0.1.
5526
5527 This option may be specified either in the frontend or in the backend. If at
5528 least one of them uses it, the header will be added. Note that the backend's
5529 setting of the header subargument takes precedence over the frontend's if
5530 both are defined.
5531
Willy Tarreau55165fe2009-05-10 12:02:55 +02005532 Examples :
5533 # Original Destination address
5534 frontend www
5535 mode http
5536 option originalto except 127.0.0.1
5537
5538 # Those servers want the IP Address in X-Client-Dst
5539 backend www
5540 mode http
5541 option originalto header X-Client-Dst
5542
Willy Tarreau87cf5142011-08-19 22:57:24 +02005543 See also : "option httpclose", "option http-server-close",
5544 "option forceclose"
Willy Tarreau55165fe2009-05-10 12:02:55 +02005545
5546
Willy Tarreaua453bdd2008-01-08 19:50:52 +01005547option persist
5548no option persist
5549 Enable or disable forced persistence on down servers
5550 May be used in sections: defaults | frontend | listen | backend
5551 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005552 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01005553
5554 When an HTTP request reaches a backend with a cookie which references a dead
5555 server, by default it is redispatched to another server. It is possible to
5556 force the request to be sent to the dead server first using "option persist"
5557 if absolutely needed. A common use case is when servers are under extreme
5558 load and spend their time flapping. In this case, the users would still be
5559 directed to the server they opened the session on, in the hope they would be
5560 correctly served. It is recommended to use "option redispatch" in conjunction
5561 with this option so that in the event it would not be possible to connect to
5562 the server at all (server definitely dead), the client would finally be
5563 redirected to another valid server.
5564
5565 If this option has been enabled in a "defaults" section, it can be disabled
5566 in a specific instance by prepending the "no" keyword before it.
5567
Willy Tarreau4de91492010-01-22 19:10:05 +01005568 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01005569
5570
Willy Tarreau0c122822013-12-15 18:49:01 +01005571option pgsql-check [ user <username> ]
5572 Use PostgreSQL health checks for server testing
5573 May be used in sections : defaults | frontend | listen | backend
5574 yes | no | yes | yes
5575 Arguments :
5576 <username> This is the username which will be used when connecting to
5577 PostgreSQL server.
5578
5579 The check sends a PostgreSQL StartupMessage and waits for either
5580 Authentication request or ErrorResponse message. It is a basic but useful
5581 test which does not produce error nor aborted connect on the server.
5582 This check is identical with the "mysql-check".
5583
5584 See also: "option httpchk"
5585
5586
Willy Tarreau9420b122013-12-15 18:58:25 +01005587option prefer-last-server
5588no option prefer-last-server
5589 Allow multiple load balanced requests to remain on the same server
5590 May be used in sections: defaults | frontend | listen | backend
5591 yes | no | yes | yes
5592 Arguments : none
5593
5594 When the load balancing algorithm in use is not deterministic, and a previous
5595 request was sent to a server to which haproxy still holds a connection, it is
5596 sometimes desirable that subsequent requests on a same session go to the same
5597 server as much as possible. Note that this is different from persistence, as
5598 we only indicate a preference which haproxy tries to apply without any form
5599 of warranty. The real use is for keep-alive connections sent to servers. When
5600 this option is used, haproxy will try to reuse the same connection that is
5601 attached to the server instead of rebalancing to another server, causing a
5602 close of the connection. This can make sense for static file servers. It does
Willy Tarreau068621e2013-12-23 15:11:25 +01005603 not make much sense to use this in combination with hashing algorithms. Note,
5604 haproxy already automatically tries to stick to a server which sends a 401 or
5605 to a proxy which sends a 407 (authentication required). This is mandatory for
5606 use with the broken NTLM authentication challenge, and significantly helps in
5607 troubleshooting some faulty applications. Option prefer-last-server might be
5608 desirable in these environments as well, to avoid redistributing the traffic
5609 after every other response.
Willy Tarreau9420b122013-12-15 18:58:25 +01005610
5611 If this option has been enabled in a "defaults" section, it can be disabled
5612 in a specific instance by prepending the "no" keyword before it.
5613
5614 See also: "option http-keep-alive"
5615
5616
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005617option redispatch
Joseph Lynch726ab712015-05-11 23:25:34 -07005618option redispatch <interval>
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005619no option redispatch
5620 Enable or disable session redistribution in case of connection failure
5621 May be used in sections: defaults | frontend | listen | backend
5622 yes | no | yes | yes
Joseph Lynch726ab712015-05-11 23:25:34 -07005623 Arguments :
5624 <interval> The optional integer value that controls how often redispatches
5625 occur when retrying connections. Positive value P indicates a
5626 redispatch is desired on every Pth retry, and negative value
5627 N indicate a redispath is desired on the Nth retry prior to the
5628 last retry. For example, the default of -1 preserves the
5629 historical behaviour of redispatching on the last retry, a
5630 positive value of 1 would indicate a redispatch on every retry,
5631 and a positive value of 3 would indicate a redispatch on every
5632 third retry. You can disable redispatches with a value of 0.
5633
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005634
5635 In HTTP mode, if a server designated by a cookie is down, clients may
5636 definitely stick to it because they cannot flush the cookie, so they will not
5637 be able to access the service anymore.
5638
5639 Specifying "option redispatch" will allow the proxy to break their
5640 persistence and redistribute them to a working server.
5641
Joseph Lynch726ab712015-05-11 23:25:34 -07005642 It also allows to retry connections to another server in case of multiple
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005643 connection failures. Of course, it requires having "retries" set to a nonzero
5644 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01005645
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005646 This form is the preferred form, which replaces both the "redispatch" and
5647 "redisp" keywords.
5648
5649 If this option has been enabled in a "defaults" section, it can be disabled
5650 in a specific instance by prepending the "no" keyword before it.
5651
Willy Tarreau4de91492010-01-22 19:10:05 +01005652 See also : "redispatch", "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005653
Willy Tarreaua453bdd2008-01-08 19:50:52 +01005654
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02005655option redis-check
5656 Use redis health checks for server testing
5657 May be used in sections : defaults | frontend | listen | backend
5658 yes | no | yes | yes
5659 Arguments : none
5660
5661 It is possible to test that the server correctly talks REDIS protocol instead
5662 of just testing that it accepts the TCP connection. When this option is set,
5663 a PING redis command is sent to the server, and the response is analyzed to
5664 find the "+PONG" response message.
5665
5666 Example :
5667 option redis-check
5668
5669 See also : "option httpchk"
5670
5671
Willy Tarreaua453bdd2008-01-08 19:50:52 +01005672option smtpchk
5673option smtpchk <hello> <domain>
5674 Use SMTP health checks for server testing
5675 May be used in sections : defaults | frontend | listen | backend
5676 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01005677 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01005678 <hello> is an optional argument. It is the "hello" command to use. It can
5679 be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other
5680 values will be turned into the default command ("HELO").
5681
5682 <domain> is the domain name to present to the server. It may only be
5683 specified (and is mandatory) if the hello command has been
5684 specified. By default, "localhost" is used.
5685
5686 When "option smtpchk" is set, the health checks will consist in TCP
5687 connections followed by an SMTP command. By default, this command is
5688 "HELO localhost". The server's return code is analyzed and only return codes
5689 starting with a "2" will be considered as valid. All other responses,
5690 including a lack of response will constitute an error and will indicate a
5691 dead server.
5692
5693 This test is meant to be used with SMTP servers or relays. Depending on the
5694 request, it is possible that some servers do not log each connection attempt,
5695 so you may want to experiment to improve the behaviour. Using telnet on port
5696 25 is often easier than adjusting the configuration.
5697
5698 Most often, an incoming SMTP server needs to see the client's IP address for
5699 various purposes, including spam filtering, anti-spoofing and logging. When
5700 possible, it is often wise to masquerade the client's IP address when
5701 connecting to the server using the "usesrc" argument of the "source" keyword,
5702 which requires the cttproxy feature to be compiled in.
5703
5704 Example :
5705 option smtpchk HELO mydomain.org
5706
5707 See also : "option httpchk", "source"
5708
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005709
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02005710option socket-stats
5711no option socket-stats
5712
5713 Enable or disable collecting & providing separate statistics for each socket.
5714 May be used in sections : defaults | frontend | listen | backend
5715 yes | yes | yes | no
5716
5717 Arguments : none
5718
5719
Willy Tarreauff4f82d2009-02-06 11:28:13 +01005720option splice-auto
5721no option splice-auto
5722 Enable or disable automatic kernel acceleration on sockets in both directions
5723 May be used in sections : defaults | frontend | listen | backend
5724 yes | yes | yes | yes
5725 Arguments : none
5726
5727 When this option is enabled either on a frontend or on a backend, haproxy
5728 will automatically evaluate the opportunity to use kernel tcp splicing to
5729 forward data between the client and the server, in either direction. Haproxy
5730 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005731 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01005732 are not much aggressive in order to limit excessive use of splicing. This
5733 option requires splicing to be enabled at compile time, and may be globally
5734 disabled with the global option "nosplice". Since splice uses pipes, using it
5735 requires that there are enough spare pipes.
5736
5737 Important note: kernel-based TCP splicing is a Linux-specific feature which
5738 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
5739 transfer data between sockets without copying these data to user-space, thus
5740 providing noticeable performance gains and CPU cycles savings. Since many
5741 early implementations are buggy, corrupt data and/or are inefficient, this
5742 feature is not enabled by default, and it should be used with extreme care.
5743 While it is not possible to detect the correctness of an implementation,
5744 2.6.29 is the first version offering a properly working implementation. In
5745 case of doubt, splicing may be globally disabled using the global "nosplice"
5746 keyword.
5747
5748 Example :
5749 option splice-auto
5750
5751 If this option has been enabled in a "defaults" section, it can be disabled
5752 in a specific instance by prepending the "no" keyword before it.
5753
5754 See also : "option splice-request", "option splice-response", and global
5755 options "nosplice" and "maxpipes"
5756
5757
5758option splice-request
5759no option splice-request
5760 Enable or disable automatic kernel acceleration on sockets for requests
5761 May be used in sections : defaults | frontend | listen | backend
5762 yes | yes | yes | yes
5763 Arguments : none
5764
5765 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04005766 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01005767 the client to the server. It might still use the recv/send scheme if there
5768 are no spare pipes left. This option requires splicing to be enabled at
5769 compile time, and may be globally disabled with the global option "nosplice".
5770 Since splice uses pipes, using it requires that there are enough spare pipes.
5771
5772 Important note: see "option splice-auto" for usage limitations.
5773
5774 Example :
5775 option splice-request
5776
5777 If this option has been enabled in a "defaults" section, it can be disabled
5778 in a specific instance by prepending the "no" keyword before it.
5779
5780 See also : "option splice-auto", "option splice-response", and global options
5781 "nosplice" and "maxpipes"
5782
5783
5784option splice-response
5785no option splice-response
5786 Enable or disable automatic kernel acceleration on sockets for responses
5787 May be used in sections : defaults | frontend | listen | backend
5788 yes | yes | yes | yes
5789 Arguments : none
5790
5791 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04005792 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01005793 the server to the client. It might still use the recv/send scheme if there
5794 are no spare pipes left. This option requires splicing to be enabled at
5795 compile time, and may be globally disabled with the global option "nosplice".
5796 Since splice uses pipes, using it requires that there are enough spare pipes.
5797
5798 Important note: see "option splice-auto" for usage limitations.
5799
5800 Example :
5801 option splice-response
5802
5803 If this option has been enabled in a "defaults" section, it can be disabled
5804 in a specific instance by prepending the "no" keyword before it.
5805
5806 See also : "option splice-auto", "option splice-request", and global options
5807 "nosplice" and "maxpipes"
5808
5809
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005810option srvtcpka
5811no option srvtcpka
5812 Enable or disable the sending of TCP keepalive packets on the server side
5813 May be used in sections : defaults | frontend | listen | backend
5814 yes | no | yes | yes
5815 Arguments : none
5816
5817 When there is a firewall or any session-aware component between a client and
5818 a server, and when the protocol involves very long sessions with long idle
5819 periods (eg: remote desktops), there is a risk that one of the intermediate
5820 components decides to expire a session which has remained idle for too long.
5821
5822 Enabling socket-level TCP keep-alives makes the system regularly send packets
5823 to the other end of the connection, leaving it active. The delay between
5824 keep-alive probes is controlled by the system only and depends both on the
5825 operating system and its tuning parameters.
5826
5827 It is important to understand that keep-alive packets are neither emitted nor
5828 received at the application level. It is only the network stacks which sees
5829 them. For this reason, even if one side of the proxy already uses keep-alives
5830 to maintain its connection alive, those keep-alive packets will not be
5831 forwarded to the other side of the proxy.
5832
5833 Please note that this has nothing to do with HTTP keep-alive.
5834
5835 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
5836 server side of a connection, which should help when session expirations are
5837 noticed between HAProxy and a server.
5838
5839 If this option has been enabled in a "defaults" section, it can be disabled
5840 in a specific instance by prepending the "no" keyword before it.
5841
5842 See also : "option clitcpka", "option tcpka"
5843
5844
Willy Tarreaua453bdd2008-01-08 19:50:52 +01005845option ssl-hello-chk
5846 Use SSLv3 client hello health checks for server testing
5847 May be used in sections : defaults | frontend | listen | backend
5848 yes | no | yes | yes
5849 Arguments : none
5850
5851 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
5852 possible to test that the server correctly talks SSL instead of just testing
5853 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
5854 SSLv3 client hello messages are sent once the connection is established to
5855 the server, and the response is analyzed to find an SSL server hello message.
5856 The server is considered valid only when the response contains this server
5857 hello message.
5858
5859 All servers tested till there correctly reply to SSLv3 client hello messages,
5860 and most servers tested do not even log the requests containing only hello
5861 messages, which is appreciable.
5862
Willy Tarreau763a95b2012-10-04 23:15:39 +02005863 Note that this check works even when SSL support was not built into haproxy
5864 because it forges the SSL message. When SSL support is available, it is best
5865 to use native SSL health checks instead of this one.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01005866
Willy Tarreau763a95b2012-10-04 23:15:39 +02005867 See also: "option httpchk", "check-ssl"
5868
Willy Tarreaua453bdd2008-01-08 19:50:52 +01005869
Willy Tarreaued179852013-12-16 01:07:00 +01005870option tcp-check
5871 Perform health checks using tcp-check send/expect sequences
5872 May be used in sections: defaults | frontend | listen | backend
5873 yes | no | yes | yes
5874
5875 This health check method is intended to be combined with "tcp-check" command
5876 lists in order to support send/expect types of health check sequences.
5877
5878 TCP checks currently support 4 modes of operations :
5879 - no "tcp-check" directive : the health check only consists in a connection
5880 attempt, which remains the default mode.
5881
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03005882 - "tcp-check send" or "tcp-check send-binary" only is mentioned : this is
Willy Tarreaued179852013-12-16 01:07:00 +01005883 used to send a string along with a connection opening. With some
5884 protocols, it helps sending a "QUIT" message for example that prevents
5885 the server from logging a connection error for each health check. The
5886 check result will still be based on the ability to open the connection
5887 only.
5888
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03005889 - "tcp-check expect" only is mentioned : this is used to test a banner.
Willy Tarreaued179852013-12-16 01:07:00 +01005890 The connection is opened and haproxy waits for the server to present some
5891 contents which must validate some rules. The check result will be based
5892 on the matching between the contents and the rules. This is suited for
5893 POP, IMAP, SMTP, FTP, SSH, TELNET.
5894
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03005895 - both "tcp-check send" and "tcp-check expect" are mentioned : this is
Willy Tarreaued179852013-12-16 01:07:00 +01005896 used to test a hello-type protocol. Haproxy sends a message, the server
5897 responds and its response is analysed. the check result will be based on
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03005898 the matching between the response contents and the rules. This is often
Willy Tarreaued179852013-12-16 01:07:00 +01005899 suited for protocols which require a binding or a request/response model.
5900 LDAP, MySQL, Redis and SSL are example of such protocols, though they
5901 already all have their dedicated checks with a deeper understanding of
5902 the respective protocols.
5903 In this mode, many questions may be sent and many answers may be
5904 analysed.
5905
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02005906 A fifth mode can be used to insert comments in different steps of the
5907 script.
5908
5909 For each tcp-check rule you create, you can add a "comment" directive,
5910 followed by a string. This string will be reported in the log and stderr
5911 in debug mode. It is useful to make user-friendly error reporting.
5912 The "comment" is of course optional.
5913
5914
Willy Tarreaued179852013-12-16 01:07:00 +01005915 Examples :
5916 # perform a POP check (analyse only server's banner)
5917 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02005918 tcp-check expect string +OK\ POP3\ ready comment POP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01005919
5920 # perform an IMAP check (analyse only server's banner)
5921 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02005922 tcp-check expect string *\ OK\ IMAP4\ ready comment IMAP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01005923
5924 # look for the redis master server after ensuring it speaks well
5925 # redis protocol, then it exits properly.
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03005926 # (send a command then analyse the response 3 times)
Willy Tarreaued179852013-12-16 01:07:00 +01005927 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02005928 tcp-check comment PING\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01005929 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +02005930 tcp-check expect string +PONG
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02005931 tcp-check comment role\ check
Willy Tarreaued179852013-12-16 01:07:00 +01005932 tcp-check send info\ replication\r\n
5933 tcp-check expect string role:master
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02005934 tcp-check comment QUIT\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01005935 tcp-check send QUIT\r\n
5936 tcp-check expect string +OK
5937
5938 forge a HTTP request, then analyse the response
5939 (send many headers before analyzing)
5940 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02005941 tcp-check comment forge\ and\ send\ HTTP\ request
Willy Tarreaued179852013-12-16 01:07:00 +01005942 tcp-check send HEAD\ /\ HTTP/1.1\r\n
5943 tcp-check send Host:\ www.mydomain.com\r\n
5944 tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n
5945 tcp-check send \r\n
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02005946 tcp-check expect rstring HTTP/1\..\ (2..|3..) comment check\ HTTP\ response
Willy Tarreaued179852013-12-16 01:07:00 +01005947
5948
5949 See also : "tcp-check expect", "tcp-check send"
5950
5951
Willy Tarreau9ea05a72009-06-14 12:07:01 +02005952option tcp-smart-accept
5953no option tcp-smart-accept
5954 Enable or disable the saving of one ACK packet during the accept sequence
5955 May be used in sections : defaults | frontend | listen | backend
5956 yes | yes | yes | no
5957 Arguments : none
5958
5959 When an HTTP connection request comes in, the system acknowledges it on
5960 behalf of HAProxy, then the client immediately sends its request, and the
5961 system acknowledges it too while it is notifying HAProxy about the new
5962 connection. HAProxy then reads the request and responds. This means that we
5963 have one TCP ACK sent by the system for nothing, because the request could
5964 very well be acknowledged by HAProxy when it sends its response.
5965
5966 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
5967 sending this useless ACK on platforms which support it (currently at least
5968 Linux). It must not cause any problem, because the system will send it anyway
5969 after 40 ms if the response takes more time than expected to come.
5970
5971 During complex network debugging sessions, it may be desirable to disable
5972 this optimization because delayed ACKs can make troubleshooting more complex
5973 when trying to identify where packets are delayed. It is then possible to
5974 fall back to normal behaviour by specifying "no option tcp-smart-accept".
5975
5976 It is also possible to force it for non-HTTP proxies by simply specifying
5977 "option tcp-smart-accept". For instance, it can make sense with some services
5978 such as SMTP where the server speaks first.
5979
5980 It is recommended to avoid forcing this option in a defaults section. In case
5981 of doubt, consider setting it back to automatic values by prepending the
5982 "default" keyword before it, or disabling it using the "no" keyword.
5983
Willy Tarreaud88edf22009-06-14 15:48:17 +02005984 See also : "option tcp-smart-connect"
5985
5986
5987option tcp-smart-connect
5988no option tcp-smart-connect
5989 Enable or disable the saving of one ACK packet during the connect sequence
5990 May be used in sections : defaults | frontend | listen | backend
5991 yes | no | yes | yes
5992 Arguments : none
5993
5994 On certain systems (at least Linux), HAProxy can ask the kernel not to
5995 immediately send an empty ACK upon a connection request, but to directly
5996 send the buffer request instead. This saves one packet on the network and
5997 thus boosts performance. It can also be useful for some servers, because they
5998 immediately get the request along with the incoming connection.
5999
6000 This feature is enabled when "option tcp-smart-connect" is set in a backend.
6001 It is not enabled by default because it makes network troubleshooting more
6002 complex.
6003
6004 It only makes sense to enable it with protocols where the client speaks first
6005 such as HTTP. In other situations, if there is no data to send in place of
6006 the ACK, a normal ACK is sent.
6007
6008 If this option has been enabled in a "defaults" section, it can be disabled
6009 in a specific instance by prepending the "no" keyword before it.
6010
6011 See also : "option tcp-smart-accept"
6012
Willy Tarreau9ea05a72009-06-14 12:07:01 +02006013
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006014option tcpka
6015 Enable or disable the sending of TCP keepalive packets on both sides
6016 May be used in sections : defaults | frontend | listen | backend
6017 yes | yes | yes | yes
6018 Arguments : none
6019
6020 When there is a firewall or any session-aware component between a client and
6021 a server, and when the protocol involves very long sessions with long idle
6022 periods (eg: remote desktops), there is a risk that one of the intermediate
6023 components decides to expire a session which has remained idle for too long.
6024
6025 Enabling socket-level TCP keep-alives makes the system regularly send packets
6026 to the other end of the connection, leaving it active. The delay between
6027 keep-alive probes is controlled by the system only and depends both on the
6028 operating system and its tuning parameters.
6029
6030 It is important to understand that keep-alive packets are neither emitted nor
6031 received at the application level. It is only the network stacks which sees
6032 them. For this reason, even if one side of the proxy already uses keep-alives
6033 to maintain its connection alive, those keep-alive packets will not be
6034 forwarded to the other side of the proxy.
6035
6036 Please note that this has nothing to do with HTTP keep-alive.
6037
6038 Using option "tcpka" enables the emission of TCP keep-alive probes on both
6039 the client and server sides of a connection. Note that this is meaningful
6040 only in "defaults" or "listen" sections. If this option is used in a
6041 frontend, only the client side will get keep-alives, and if this option is
6042 used in a backend, only the server side will get keep-alives. For this
6043 reason, it is strongly recommended to explicitly use "option clitcpka" and
6044 "option srvtcpka" when the configuration is split between frontends and
6045 backends.
6046
6047 See also : "option clitcpka", "option srvtcpka"
6048
Willy Tarreau844e3c52008-01-11 16:28:18 +01006049
6050option tcplog
6051 Enable advanced logging of TCP connections with session state and timers
6052 May be used in sections : defaults | frontend | listen | backend
6053 yes | yes | yes | yes
6054 Arguments : none
6055
6056 By default, the log output format is very poor, as it only contains the
6057 source and destination addresses, and the instance name. By specifying
6058 "option tcplog", each log line turns into a much richer format including, but
6059 not limited to, the connection timers, the session status, the connections
6060 numbers, the frontend, backend and server name, and of course the source
6061 address and ports. This option is useful for pure TCP proxies in order to
6062 find which of the client or server disconnects or times out. For normal HTTP
6063 proxies, it's better to use "option httplog" which is even more complete.
6064
6065 This option may be set either in the frontend or the backend.
6066
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006067 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006068
6069
Willy Tarreau844e3c52008-01-11 16:28:18 +01006070option transparent
6071no option transparent
6072 Enable client-side transparent proxying
6073 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01006074 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01006075 Arguments : none
6076
6077 This option was introduced in order to provide layer 7 persistence to layer 3
6078 load balancers. The idea is to use the OS's ability to redirect an incoming
6079 connection for a remote address to a local process (here HAProxy), and let
6080 this process know what address was initially requested. When this option is
6081 used, sessions without cookies will be forwarded to the original destination
6082 IP address of the incoming request (which should match that of another
6083 equipment), while requests with cookies will still be forwarded to the
6084 appropriate server.
6085
6086 Note that contrary to a common belief, this option does NOT make HAProxy
6087 present the client's IP to the server when establishing the connection.
6088
Willy Tarreaua1146052011-03-01 09:51:54 +01006089 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006090 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006091
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006092
Simon Horman98637e52014-06-20 12:30:16 +09006093external-check command <command>
6094 Executable to run when performing an external-check
6095 May be used in sections : defaults | frontend | listen | backend
6096 yes | no | yes | yes
6097
6098 Arguments :
6099 <command> is the external command to run
6100
Simon Horman98637e52014-06-20 12:30:16 +09006101 The arguments passed to the to the command are:
6102
Cyril Bonté777be862014-12-02 21:21:35 +01006103 <proxy_address> <proxy_port> <server_address> <server_port>
Simon Horman98637e52014-06-20 12:30:16 +09006104
Cyril Bonté777be862014-12-02 21:21:35 +01006105 The <proxy_address> and <proxy_port> are derived from the first listener
6106 that is either IPv4, IPv6 or a UNIX socket. In the case of a UNIX socket
6107 listener the proxy_address will be the path of the socket and the
6108 <proxy_port> will be the string "NOT_USED". In a backend section, it's not
6109 possible to determine a listener, and both <proxy_address> and <proxy_port>
6110 will have the string value "NOT_USED".
Simon Horman98637e52014-06-20 12:30:16 +09006111
Cyril Bonté72cda2a2014-12-27 22:28:39 +01006112 Some values are also provided through environment variables.
6113
6114 Environment variables :
6115 HAPROXY_PROXY_ADDR The first bind address if available (or empty if not
6116 applicable, for example in a "backend" section).
6117
6118 HAPROXY_PROXY_ID The backend id.
6119
6120 HAPROXY_PROXY_NAME The backend name.
6121
6122 HAPROXY_PROXY_PORT The first bind port if available (or empty if not
6123 applicable, for example in a "backend" section or
6124 for a UNIX socket).
6125
6126 HAPROXY_SERVER_ADDR The server address.
6127
6128 HAPROXY_SERVER_CURCONN The current number of connections on the server.
6129
6130 HAPROXY_SERVER_ID The server id.
6131
6132 HAPROXY_SERVER_MAXCONN The server max connections.
6133
6134 HAPROXY_SERVER_NAME The server name.
6135
6136 HAPROXY_SERVER_PORT The server port if available (or empty for a UNIX
6137 socket).
6138
6139 PATH The PATH environment variable used when executing
6140 the command may be set using "external-check path".
6141
Simon Horman98637e52014-06-20 12:30:16 +09006142 If the command executed and exits with a zero status then the check is
6143 considered to have passed, otherwise the check is considered to have
6144 failed.
6145
6146 Example :
6147 external-check command /bin/true
6148
6149 See also : "external-check", "option external-check", "external-check path"
6150
6151
6152external-check path <path>
6153 The value of the PATH environment variable used when running an external-check
6154 May be used in sections : defaults | frontend | listen | backend
6155 yes | no | yes | yes
6156
6157 Arguments :
6158 <path> is the path used when executing external command to run
6159
6160 The default path is "".
6161
6162 Example :
6163 external-check path "/usr/bin:/bin"
6164
6165 See also : "external-check", "option external-check",
6166 "external-check command"
6167
6168
Emeric Brun647caf12009-06-30 17:57:00 +02006169persist rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02006170persist rdp-cookie(<name>)
Emeric Brun647caf12009-06-30 17:57:00 +02006171 Enable RDP cookie-based persistence
6172 May be used in sections : defaults | frontend | listen | backend
6173 yes | no | yes | yes
6174 Arguments :
6175 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02006176 default cookie name "msts" will be used. There currently is no
6177 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02006178
6179 This statement enables persistence based on an RDP cookie. The RDP cookie
6180 contains all information required to find the server in the list of known
6181 servers. So when this option is set in the backend, the request is analysed
6182 and if an RDP cookie is found, it is decoded. If it matches a known server
6183 which is still UP (or if "option persist" is set), then the connection is
6184 forwarded to this server.
6185
6186 Note that this only makes sense in a TCP backend, but for this to work, the
6187 frontend must have waited long enough to ensure that an RDP cookie is present
6188 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006189 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02006190 a single "listen" section.
6191
Willy Tarreau61e28f22010-05-16 22:31:05 +02006192 Also, it is important to understand that the terminal server will emit this
6193 RDP cookie only if it is configured for "token redirection mode", which means
6194 that the "IP address redirection" option is disabled.
6195
Emeric Brun647caf12009-06-30 17:57:00 +02006196 Example :
6197 listen tse-farm
6198 bind :3389
6199 # wait up to 5s for an RDP cookie in the request
6200 tcp-request inspect-delay 5s
6201 tcp-request content accept if RDP_COOKIE
6202 # apply RDP cookie persistence
6203 persist rdp-cookie
6204 # if server is unknown, let's balance on the same cookie.
Cyril Bontédc4d9032012-04-08 21:57:39 +02006205 # alternatively, "balance leastconn" may be useful too.
Emeric Brun647caf12009-06-30 17:57:00 +02006206 balance rdp-cookie
6207 server srv1 1.1.1.1:3389
6208 server srv2 1.1.1.2:3389
6209
Simon Hormanab814e02011-06-24 14:50:20 +09006210 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
6211 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02006212
6213
Willy Tarreau3a7d2072009-03-05 23:48:25 +01006214rate-limit sessions <rate>
6215 Set a limit on the number of new sessions accepted per second on a frontend
6216 May be used in sections : defaults | frontend | listen | backend
6217 yes | yes | yes | no
6218 Arguments :
6219 <rate> The <rate> parameter is an integer designating the maximum number
6220 of new sessions per second to accept on the frontend.
6221
6222 When the frontend reaches the specified number of new sessions per second, it
6223 stops accepting new connections until the rate drops below the limit again.
6224 During this time, the pending sessions will be kept in the socket's backlog
6225 (in system buffers) and haproxy will not even be aware that sessions are
6226 pending. When applying very low limit on a highly loaded service, it may make
6227 sense to increase the socket's backlog using the "backlog" keyword.
6228
6229 This feature is particularly efficient at blocking connection-based attacks
6230 or service abuse on fragile servers. Since the session rate is measured every
6231 millisecond, it is extremely accurate. Also, the limit applies immediately,
6232 no delay is needed at all to detect the threshold.
6233
6234 Example : limit the connection rate on SMTP to 10 per second max
6235 listen smtp
6236 mode tcp
6237 bind :25
6238 rate-limit sessions 10
6239 server 127.0.0.1:1025
6240
Willy Tarreaua17c2d92011-07-25 08:16:20 +02006241 Note : when the maximum rate is reached, the frontend's status is not changed
6242 but its sockets appear as "WAITING" in the statistics if the
6243 "socket-stats" option is enabled.
Willy Tarreau3a7d2072009-03-05 23:48:25 +01006244
6245 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
6246
6247
Willy Tarreau2e1dca82012-09-12 08:43:15 +02006248redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
6249redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
6250redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02006251 Return an HTTP redirection if/unless a condition is matched
6252 May be used in sections : defaults | frontend | listen | backend
6253 no | yes | yes | yes
6254
6255 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01006256 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02006257
Willy Tarreau0140f252008-11-19 21:07:09 +01006258 Arguments :
Willy Tarreau2e1dca82012-09-12 08:43:15 +02006259 <loc> With "redirect location", the exact value in <loc> is placed into
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01006260 the HTTP "Location" header. When used in an "http-request" rule,
6261 <loc> value follows the log-format rules and can include some
6262 dynamic values (see Custom Log Format in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02006263
6264 <pfx> With "redirect prefix", the "Location" header is built from the
6265 concatenation of <pfx> and the complete URI path, including the
6266 query string, unless the "drop-query" option is specified (see
6267 below). As a special case, if <pfx> equals exactly "/", then
6268 nothing is inserted before the original URI. It allows one to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01006269 redirect to the same URL (for instance, to insert a cookie). When
6270 used in an "http-request" rule, <pfx> value follows the log-format
6271 rules and can include some dynamic values (see Custom Log Format
6272 in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02006273
6274 <sch> With "redirect scheme", then the "Location" header is built by
6275 concatenating <sch> with "://" then the first occurrence of the
6276 "Host" header, and then the URI path, including the query string
6277 unless the "drop-query" option is specified (see below). If no
6278 path is found or if the path is "*", then "/" is used instead. If
6279 no "Host" header is found, then an empty host component will be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006280 returned, which most recent browsers interpret as redirecting to
Willy Tarreau2e1dca82012-09-12 08:43:15 +02006281 the same host. This directive is mostly used to redirect HTTP to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01006282 HTTPS. When used in an "http-request" rule, <sch> value follows
6283 the log-format rules and can include some dynamic values (see
6284 Custom Log Format in section 8.2.4).
Willy Tarreau0140f252008-11-19 21:07:09 +01006285
6286 <code> The code is optional. It indicates which type of HTTP redirection
Willy Tarreaub67fdc42013-03-29 19:28:11 +01006287 is desired. Only codes 301, 302, 303, 307 and 308 are supported,
6288 with 302 used by default if no code is specified. 301 means
6289 "Moved permanently", and a browser may cache the Location. 302
Baptiste Assmannea849c02015-08-03 11:42:50 +02006290 means "Moved temporarily" and means that the browser should not
Willy Tarreaub67fdc42013-03-29 19:28:11 +01006291 cache the redirection. 303 is equivalent to 302 except that the
6292 browser will fetch the location with a GET method. 307 is just
6293 like 302 but makes it clear that the same method must be reused.
6294 Likewise, 308 replaces 301 if the same method must be used.
Willy Tarreau0140f252008-11-19 21:07:09 +01006295
6296 <option> There are several options which can be specified to adjust the
6297 expected behaviour of a redirection :
6298
6299 - "drop-query"
6300 When this keyword is used in a prefix-based redirection, then the
6301 location will be set without any possible query-string, which is useful
6302 for directing users to a non-secure page for instance. It has no effect
6303 with a location-type redirect.
6304
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01006305 - "append-slash"
6306 This keyword may be used in conjunction with "drop-query" to redirect
6307 users who use a URL not ending with a '/' to the same one with the '/'.
6308 It can be useful to ensure that search engines will only see one URL.
6309 For this, a return code 301 is preferred.
6310
Willy Tarreau0140f252008-11-19 21:07:09 +01006311 - "set-cookie NAME[=value]"
6312 A "Set-Cookie" header will be added with NAME (and optionally "=value")
6313 to the response. This is sometimes used to indicate that a user has
6314 been seen, for instance to protect against some types of DoS. No other
6315 cookie option is added, so the cookie will be a session cookie. Note
6316 that for a browser, a sole cookie name without an equal sign is
6317 different from a cookie with an equal sign.
6318
6319 - "clear-cookie NAME[=]"
6320 A "Set-Cookie" header will be added with NAME (and optionally "="), but
6321 with the "Max-Age" attribute set to zero. This will tell the browser to
6322 delete this cookie. It is useful for instance on logout pages. It is
6323 important to note that clearing the cookie "NAME" will not remove a
6324 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
6325 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02006326
6327 Example: move the login URL only to HTTPS.
6328 acl clear dst_port 80
6329 acl secure dst_port 8080
6330 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01006331 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01006332 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01006333 acl cookie_set hdr_sub(cookie) SEEN=1
6334
6335 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01006336 redirect prefix https://mysite.com if login_page !secure
6337 redirect prefix http://mysite.com drop-query if login_page !uid_given
6338 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01006339 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02006340
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01006341 Example: send redirects for request for articles without a '/'.
6342 acl missing_slash path_reg ^/article/[^/]*$
6343 redirect code 301 prefix / drop-query append-slash if missing_slash
6344
Willy Tarreau2e1dca82012-09-12 08:43:15 +02006345 Example: redirect all HTTP traffic to HTTPS when SSL is handled by haproxy.
David BERARDe7153042012-11-03 00:11:31 +01006346 redirect scheme https if !{ ssl_fc }
Willy Tarreau2e1dca82012-09-12 08:43:15 +02006347
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01006348 Example: append 'www.' prefix in front of all hosts not having it
6349 http-request redirect code 301 location www.%[hdr(host)]%[req.uri] \
6350 unless { hdr_beg(host) -i www }
6351
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006352 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02006353
6354
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006355redisp (deprecated)
6356redispatch (deprecated)
6357 Enable or disable session redistribution in case of connection failure
6358 May be used in sections: defaults | frontend | listen | backend
6359 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006360 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006361
6362 In HTTP mode, if a server designated by a cookie is down, clients may
6363 definitely stick to it because they cannot flush the cookie, so they will not
6364 be able to access the service anymore.
6365
6366 Specifying "redispatch" will allow the proxy to break their persistence and
6367 redistribute them to a working server.
6368
6369 It also allows to retry last connection to another server in case of multiple
6370 connection failures. Of course, it requires having "retries" set to a nonzero
6371 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01006372
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006373 This form is deprecated, do not use it in any new configuration, use the new
6374 "option redispatch" instead.
6375
6376 See also : "option redispatch"
6377
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006378
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01006379reqadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01006380 Add a header at the end of the HTTP request
6381 May be used in sections : defaults | frontend | listen | backend
6382 no | yes | yes | yes
6383 Arguments :
6384 <string> is the complete line to be added. Any space or known delimiter
6385 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006386 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01006387
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01006388 <cond> is an optional matching condition built from ACLs. It makes it
6389 possible to ignore this rule when other conditions are not met.
6390
Willy Tarreau303c0352008-01-17 19:01:39 +01006391 A new line consisting in <string> followed by a line feed will be added after
6392 the last header of an HTTP request.
6393
6394 Header transformations only apply to traffic which passes through HAProxy,
6395 and not to traffic generated by HAProxy, such as health-checks or error
6396 responses.
6397
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01006398 Example : add "X-Proto: SSL" to requests coming via port 81
6399 acl is-ssl dst_port 81
6400 reqadd X-Proto:\ SSL if is-ssl
6401
6402 See also: "rspadd", section 6 about HTTP header manipulation, and section 7
6403 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01006404
6405
Willy Tarreau5321c422010-01-28 20:35:13 +01006406reqallow <search> [{if | unless} <cond>]
6407reqiallow <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01006408 Definitely allow an HTTP request if a line matches a regular expression
6409 May be used in sections : defaults | frontend | listen | backend
6410 no | yes | yes | yes
6411 Arguments :
6412 <search> is the regular expression applied to HTTP headers and to the
6413 request line. This is an extended regular expression. Parenthesis
6414 grouping is supported and no preliminary backslash is required.
6415 Any space or known delimiter must be escaped using a backslash
6416 ('\'). The pattern applies to a full line at a time. The
6417 "reqallow" keyword strictly matches case while "reqiallow"
6418 ignores case.
6419
Willy Tarreau5321c422010-01-28 20:35:13 +01006420 <cond> is an optional matching condition built from ACLs. It makes it
6421 possible to ignore this rule when other conditions are not met.
6422
Willy Tarreau303c0352008-01-17 19:01:39 +01006423 A request containing any line which matches extended regular expression
6424 <search> will mark the request as allowed, even if any later test would
6425 result in a deny. The test applies both to the request line and to request
6426 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01006427 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01006428
6429 It is easier, faster and more powerful to use ACLs to write access policies.
6430 Reqdeny, reqallow and reqpass should be avoided in new designs.
6431
6432 Example :
6433 # allow www.* but refuse *.local
6434 reqiallow ^Host:\ www\.
6435 reqideny ^Host:\ .*\.local
6436
Willy Tarreau5321c422010-01-28 20:35:13 +01006437 See also: "reqdeny", "block", section 6 about HTTP header manipulation, and
6438 section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01006439
6440
Willy Tarreau5321c422010-01-28 20:35:13 +01006441reqdel <search> [{if | unless} <cond>]
6442reqidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01006443 Delete all headers matching a regular expression in an HTTP request
6444 May be used in sections : defaults | frontend | listen | backend
6445 no | yes | yes | yes
6446 Arguments :
6447 <search> is the regular expression applied to HTTP headers and to the
6448 request line. This is an extended regular expression. Parenthesis
6449 grouping is supported and no preliminary backslash is required.
6450 Any space or known delimiter must be escaped using a backslash
6451 ('\'). The pattern applies to a full line at a time. The "reqdel"
6452 keyword strictly matches case while "reqidel" ignores case.
6453
Willy Tarreau5321c422010-01-28 20:35:13 +01006454 <cond> is an optional matching condition built from ACLs. It makes it
6455 possible to ignore this rule when other conditions are not met.
6456
Willy Tarreau303c0352008-01-17 19:01:39 +01006457 Any header line matching extended regular expression <search> in the request
6458 will be completely deleted. Most common use of this is to remove unwanted
6459 and/or dangerous headers or cookies from a request before passing it to the
6460 next servers.
6461
6462 Header transformations only apply to traffic which passes through HAProxy,
6463 and not to traffic generated by HAProxy, such as health-checks or error
6464 responses. Keep in mind that header names are not case-sensitive.
6465
6466 Example :
6467 # remove X-Forwarded-For header and SERVER cookie
6468 reqidel ^X-Forwarded-For:.*
6469 reqidel ^Cookie:.*SERVER=
6470
Willy Tarreau5321c422010-01-28 20:35:13 +01006471 See also: "reqadd", "reqrep", "rspdel", section 6 about HTTP header
6472 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01006473
6474
Willy Tarreau5321c422010-01-28 20:35:13 +01006475reqdeny <search> [{if | unless} <cond>]
6476reqideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01006477 Deny an HTTP request if a line matches a regular expression
6478 May be used in sections : defaults | frontend | listen | backend
6479 no | yes | yes | yes
6480 Arguments :
6481 <search> is the regular expression applied to HTTP headers and to the
6482 request line. This is an extended regular expression. Parenthesis
6483 grouping is supported and no preliminary backslash is required.
6484 Any space or known delimiter must be escaped using a backslash
6485 ('\'). The pattern applies to a full line at a time. The
6486 "reqdeny" keyword strictly matches case while "reqideny" ignores
6487 case.
6488
Willy Tarreau5321c422010-01-28 20:35:13 +01006489 <cond> is an optional matching condition built from ACLs. It makes it
6490 possible to ignore this rule when other conditions are not met.
6491
Willy Tarreau303c0352008-01-17 19:01:39 +01006492 A request containing any line which matches extended regular expression
6493 <search> will mark the request as denied, even if any later test would
6494 result in an allow. The test applies both to the request line and to request
6495 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01006496 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01006497
Willy Tarreauced27012008-01-17 20:35:34 +01006498 A denied request will generate an "HTTP 403 forbidden" response once the
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006499 complete request has been parsed. This is consistent with what is practiced
Willy Tarreaud72758d2010-01-12 10:42:19 +01006500 using ACLs.
Willy Tarreauced27012008-01-17 20:35:34 +01006501
Willy Tarreau303c0352008-01-17 19:01:39 +01006502 It is easier, faster and more powerful to use ACLs to write access policies.
6503 Reqdeny, reqallow and reqpass should be avoided in new designs.
6504
6505 Example :
6506 # refuse *.local, then allow www.*
6507 reqideny ^Host:\ .*\.local
6508 reqiallow ^Host:\ www\.
6509
Willy Tarreau5321c422010-01-28 20:35:13 +01006510 See also: "reqallow", "rspdeny", "block", section 6 about HTTP header
6511 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01006512
6513
Willy Tarreau5321c422010-01-28 20:35:13 +01006514reqpass <search> [{if | unless} <cond>]
6515reqipass <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01006516 Ignore any HTTP request line matching a regular expression in next rules
6517 May be used in sections : defaults | frontend | listen | backend
6518 no | yes | yes | yes
6519 Arguments :
6520 <search> is the regular expression applied to HTTP headers and to the
6521 request line. This is an extended regular expression. Parenthesis
6522 grouping is supported and no preliminary backslash is required.
6523 Any space or known delimiter must be escaped using a backslash
6524 ('\'). The pattern applies to a full line at a time. The
6525 "reqpass" keyword strictly matches case while "reqipass" ignores
6526 case.
6527
Willy Tarreau5321c422010-01-28 20:35:13 +01006528 <cond> is an optional matching condition built from ACLs. It makes it
6529 possible to ignore this rule when other conditions are not met.
6530
Willy Tarreau303c0352008-01-17 19:01:39 +01006531 A request containing any line which matches extended regular expression
6532 <search> will skip next rules, without assigning any deny or allow verdict.
6533 The test applies both to the request line and to request headers. Keep in
6534 mind that URLs in request line are case-sensitive while header names are not.
6535
6536 It is easier, faster and more powerful to use ACLs to write access policies.
6537 Reqdeny, reqallow and reqpass should be avoided in new designs.
6538
6539 Example :
6540 # refuse *.local, then allow www.*, but ignore "www.private.local"
6541 reqipass ^Host:\ www.private\.local
6542 reqideny ^Host:\ .*\.local
6543 reqiallow ^Host:\ www\.
6544
Willy Tarreau5321c422010-01-28 20:35:13 +01006545 See also: "reqallow", "reqdeny", "block", section 6 about HTTP header
6546 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01006547
6548
Willy Tarreau5321c422010-01-28 20:35:13 +01006549reqrep <search> <string> [{if | unless} <cond>]
6550reqirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01006551 Replace a regular expression with a string in an HTTP request line
6552 May be used in sections : defaults | frontend | listen | backend
6553 no | yes | yes | yes
6554 Arguments :
6555 <search> is the regular expression applied to HTTP headers and to the
6556 request line. This is an extended regular expression. Parenthesis
6557 grouping is supported and no preliminary backslash is required.
6558 Any space or known delimiter must be escaped using a backslash
6559 ('\'). The pattern applies to a full line at a time. The "reqrep"
6560 keyword strictly matches case while "reqirep" ignores case.
6561
6562 <string> is the complete line to be added. Any space or known delimiter
6563 must be escaped using a backslash ('\'). References to matched
6564 pattern groups are possible using the common \N form, with N
6565 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006566 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01006567
Willy Tarreau5321c422010-01-28 20:35:13 +01006568 <cond> is an optional matching condition built from ACLs. It makes it
6569 possible to ignore this rule when other conditions are not met.
6570
Willy Tarreau303c0352008-01-17 19:01:39 +01006571 Any line matching extended regular expression <search> in the request (both
6572 the request line and header lines) will be completely replaced with <string>.
6573 Most common use of this is to rewrite URLs or domain names in "Host" headers.
6574
6575 Header transformations only apply to traffic which passes through HAProxy,
6576 and not to traffic generated by HAProxy, such as health-checks or error
6577 responses. Note that for increased readability, it is suggested to add enough
6578 spaces between the request and the response. Keep in mind that URLs in
6579 request line are case-sensitive while header names are not.
6580
6581 Example :
6582 # replace "/static/" with "/" at the beginning of any request path.
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04006583 reqrep ^([^\ :]*)\ /static/(.*) \1\ /\2
Willy Tarreau303c0352008-01-17 19:01:39 +01006584 # replace "www.mydomain.com" with "www" in the host name.
6585 reqirep ^Host:\ www.mydomain.com Host:\ www
6586
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +04006587 See also: "reqadd", "reqdel", "rsprep", "tune.bufsize", section 6 about
6588 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01006589
6590
Willy Tarreau5321c422010-01-28 20:35:13 +01006591reqtarpit <search> [{if | unless} <cond>]
6592reqitarpit <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01006593 Tarpit an HTTP request containing a line matching a regular expression
6594 May be used in sections : defaults | frontend | listen | backend
6595 no | yes | yes | yes
6596 Arguments :
6597 <search> is the regular expression applied to HTTP headers and to the
6598 request line. This is an extended regular expression. Parenthesis
6599 grouping is supported and no preliminary backslash is required.
6600 Any space or known delimiter must be escaped using a backslash
6601 ('\'). The pattern applies to a full line at a time. The
6602 "reqtarpit" keyword strictly matches case while "reqitarpit"
6603 ignores case.
6604
Willy Tarreau5321c422010-01-28 20:35:13 +01006605 <cond> is an optional matching condition built from ACLs. It makes it
6606 possible to ignore this rule when other conditions are not met.
6607
Willy Tarreau303c0352008-01-17 19:01:39 +01006608 A request containing any line which matches extended regular expression
6609 <search> will be tarpitted, which means that it will connect to nowhere, will
Willy Tarreauced27012008-01-17 20:35:34 +01006610 be kept open for a pre-defined time, then will return an HTTP error 500 so
6611 that the attacker does not suspect it has been tarpitted. The status 500 will
6612 be reported in the logs, but the completion flags will indicate "PT". The
Willy Tarreau303c0352008-01-17 19:01:39 +01006613 delay is defined by "timeout tarpit", or "timeout connect" if the former is
6614 not set.
6615
6616 The goal of the tarpit is to slow down robots attacking servers with
6617 identifiable requests. Many robots limit their outgoing number of connections
6618 and stay connected waiting for a reply which can take several minutes to
6619 come. Depending on the environment and attack, it may be particularly
6620 efficient at reducing the load on the network and firewalls.
6621
Willy Tarreau5321c422010-01-28 20:35:13 +01006622 Examples :
Willy Tarreau303c0352008-01-17 19:01:39 +01006623 # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but
6624 # block all others.
6625 reqipass ^User-Agent:\.*(Mozilla|MSIE)
6626 reqitarpit ^User-Agent:
6627
Willy Tarreau5321c422010-01-28 20:35:13 +01006628 # block bad guys
6629 acl badguys src 10.1.0.3 172.16.13.20/28
6630 reqitarpit . if badguys
6631
6632 See also: "reqallow", "reqdeny", "reqpass", section 6 about HTTP header
6633 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01006634
6635
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02006636retries <value>
6637 Set the number of retries to perform on a server after a connection failure
6638 May be used in sections: defaults | frontend | listen | backend
6639 yes | no | yes | yes
6640 Arguments :
6641 <value> is the number of times a connection attempt should be retried on
6642 a server when a connection either is refused or times out. The
6643 default value is 3.
6644
6645 It is important to understand that this value applies to the number of
6646 connection attempts, not full requests. When a connection has effectively
6647 been established to a server, there will be no more retry.
6648
6649 In order to avoid immediate reconnections to a server which is restarting,
Joseph Lynch726ab712015-05-11 23:25:34 -07006650 a turn-around timer of min("timeout connect", one second) is applied before
6651 a retry occurs.
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02006652
6653 When "option redispatch" is set, the last retry may be performed on another
6654 server even if a cookie references a different server.
6655
6656 See also : "option redispatch"
6657
6658
Willy Tarreaufdb563c2010-01-31 15:43:27 +01006659rspadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01006660 Add a header at the end of the HTTP response
6661 May be used in sections : defaults | frontend | listen | backend
6662 no | yes | yes | yes
6663 Arguments :
6664 <string> is the complete line to be added. Any space or known delimiter
6665 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006666 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01006667
Willy Tarreaufdb563c2010-01-31 15:43:27 +01006668 <cond> is an optional matching condition built from ACLs. It makes it
6669 possible to ignore this rule when other conditions are not met.
6670
Willy Tarreau303c0352008-01-17 19:01:39 +01006671 A new line consisting in <string> followed by a line feed will be added after
6672 the last header of an HTTP response.
6673
6674 Header transformations only apply to traffic which passes through HAProxy,
6675 and not to traffic generated by HAProxy, such as health-checks or error
6676 responses.
6677
Willy Tarreaufdb563c2010-01-31 15:43:27 +01006678 See also: "reqadd", section 6 about HTTP header manipulation, and section 7
6679 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01006680
6681
Willy Tarreaufdb563c2010-01-31 15:43:27 +01006682rspdel <search> [{if | unless} <cond>]
6683rspidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01006684 Delete all headers matching a regular expression in an HTTP response
6685 May be used in sections : defaults | frontend | listen | backend
6686 no | yes | yes | yes
6687 Arguments :
6688 <search> is the regular expression applied to HTTP headers and to the
6689 response line. This is an extended regular expression, so
6690 parenthesis grouping is supported and no preliminary backslash
6691 is required. Any space or known delimiter must be escaped using
6692 a backslash ('\'). The pattern applies to a full line at a time.
6693 The "rspdel" keyword strictly matches case while "rspidel"
6694 ignores case.
6695
Willy Tarreaufdb563c2010-01-31 15:43:27 +01006696 <cond> is an optional matching condition built from ACLs. It makes it
6697 possible to ignore this rule when other conditions are not met.
6698
Willy Tarreau303c0352008-01-17 19:01:39 +01006699 Any header line matching extended regular expression <search> in the response
6700 will be completely deleted. Most common use of this is to remove unwanted
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02006701 and/or sensitive headers or cookies from a response before passing it to the
Willy Tarreau303c0352008-01-17 19:01:39 +01006702 client.
6703
6704 Header transformations only apply to traffic which passes through HAProxy,
6705 and not to traffic generated by HAProxy, such as health-checks or error
6706 responses. Keep in mind that header names are not case-sensitive.
6707
6708 Example :
6709 # remove the Server header from responses
Willy Tarreau5e80e022013-05-25 08:31:25 +02006710 rspidel ^Server:.*
Willy Tarreau303c0352008-01-17 19:01:39 +01006711
Willy Tarreaufdb563c2010-01-31 15:43:27 +01006712 See also: "rspadd", "rsprep", "reqdel", section 6 about HTTP header
6713 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01006714
6715
Willy Tarreaufdb563c2010-01-31 15:43:27 +01006716rspdeny <search> [{if | unless} <cond>]
6717rspideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01006718 Block an HTTP response if a line matches a regular expression
6719 May be used in sections : defaults | frontend | listen | backend
6720 no | yes | yes | yes
6721 Arguments :
6722 <search> is the regular expression applied to HTTP headers and to the
6723 response line. This is an extended regular expression, so
6724 parenthesis grouping is supported and no preliminary backslash
6725 is required. Any space or known delimiter must be escaped using
6726 a backslash ('\'). The pattern applies to a full line at a time.
6727 The "rspdeny" keyword strictly matches case while "rspideny"
6728 ignores case.
6729
Willy Tarreaufdb563c2010-01-31 15:43:27 +01006730 <cond> is an optional matching condition built from ACLs. It makes it
6731 possible to ignore this rule when other conditions are not met.
6732
Willy Tarreau303c0352008-01-17 19:01:39 +01006733 A response containing any line which matches extended regular expression
6734 <search> will mark the request as denied. The test applies both to the
6735 response line and to response headers. Keep in mind that header names are not
6736 case-sensitive.
6737
6738 Main use of this keyword is to prevent sensitive information leak and to
Willy Tarreauced27012008-01-17 20:35:34 +01006739 block the response before it reaches the client. If a response is denied, it
6740 will be replaced with an HTTP 502 error so that the client never retrieves
6741 any sensitive data.
Willy Tarreau303c0352008-01-17 19:01:39 +01006742
6743 It is easier, faster and more powerful to use ACLs to write access policies.
6744 Rspdeny should be avoided in new designs.
6745
6746 Example :
6747 # Ensure that no content type matching ms-word will leak
6748 rspideny ^Content-type:\.*/ms-word
6749
Willy Tarreaufdb563c2010-01-31 15:43:27 +01006750 See also: "reqdeny", "acl", "block", section 6 about HTTP header manipulation
6751 and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01006752
6753
Willy Tarreaufdb563c2010-01-31 15:43:27 +01006754rsprep <search> <string> [{if | unless} <cond>]
6755rspirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01006756 Replace a regular expression with a string in an HTTP response line
6757 May be used in sections : defaults | frontend | listen | backend
6758 no | yes | yes | yes
6759 Arguments :
6760 <search> is the regular expression applied to HTTP headers and to the
6761 response line. This is an extended regular expression, so
6762 parenthesis grouping is supported and no preliminary backslash
6763 is required. Any space or known delimiter must be escaped using
6764 a backslash ('\'). The pattern applies to a full line at a time.
6765 The "rsprep" keyword strictly matches case while "rspirep"
6766 ignores case.
6767
6768 <string> is the complete line to be added. Any space or known delimiter
6769 must be escaped using a backslash ('\'). References to matched
6770 pattern groups are possible using the common \N form, with N
6771 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006772 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01006773
Willy Tarreaufdb563c2010-01-31 15:43:27 +01006774 <cond> is an optional matching condition built from ACLs. It makes it
6775 possible to ignore this rule when other conditions are not met.
6776
Willy Tarreau303c0352008-01-17 19:01:39 +01006777 Any line matching extended regular expression <search> in the response (both
6778 the response line and header lines) will be completely replaced with
6779 <string>. Most common use of this is to rewrite Location headers.
6780
6781 Header transformations only apply to traffic which passes through HAProxy,
6782 and not to traffic generated by HAProxy, such as health-checks or error
6783 responses. Note that for increased readability, it is suggested to add enough
6784 spaces between the request and the response. Keep in mind that header names
6785 are not case-sensitive.
6786
6787 Example :
6788 # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com"
6789 rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com
6790
Willy Tarreaufdb563c2010-01-31 15:43:27 +01006791 See also: "rspadd", "rspdel", "reqrep", section 6 about HTTP header
6792 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01006793
6794
David du Colombier486df472011-03-17 10:40:26 +01006795server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006796 Declare a server in a backend
6797 May be used in sections : defaults | frontend | listen | backend
6798 no | no | yes | yes
6799 Arguments :
6800 <name> is the internal name assigned to this server. This name will
Cyril Bonté941a0c62012-10-15 19:44:24 +02006801 appear in logs and alerts. If "http-send-name-header" is
Mark Lamourinec2247f02012-01-04 13:02:01 -05006802 set, it will be added to the request header sent to the server.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006803
David du Colombier486df472011-03-17 10:40:26 +01006804 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
6805 resolvable hostname is supported, but this name will be resolved
6806 during start-up. Address "0.0.0.0" or "*" has a special meaning.
6807 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +02006808 address as the one from the client connection. This is useful in
6809 transparent proxy architectures where the client's connection is
6810 intercepted and haproxy must forward to the original destination
6811 address. This is more or less what the "transparent" keyword does
6812 except that with a server it's possible to limit concurrency and
Willy Tarreau24709282013-03-10 21:32:12 +01006813 to report statistics. Optionally, an address family prefix may be
6814 used before the address to force the family regardless of the
6815 address format, which can be useful to specify a path to a unix
6816 socket with no slash ('/'). Currently supported prefixes are :
6817 - 'ipv4@' -> address is always IPv4
6818 - 'ipv6@' -> address is always IPv6
6819 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +02006820 - 'abns@' -> address is in abstract namespace (Linux only)
William Lallemandb2f07452015-05-12 14:27:13 +02006821 You may want to reference some environment variables in the
6822 address parameter, see section 2.3 about environment
6823 variables.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006824
Willy Tarreaub6205fd2012-09-24 12:27:33 +02006825 <port> is an optional port specification. If set, all connections will
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006826 be sent to this port. If unset, the same port the client
6827 connected to will be used. The port may also be prefixed by a "+"
6828 or a "-". In this case, the server's port will be determined by
6829 adding this value to the client's port.
6830
6831 <param*> is a list of parameters for this server. The "server" keywords
6832 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006833 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006834
6835 Examples :
6836 server first 10.1.1.1:1080 cookie first check inter 1000
6837 server second 10.1.1.2:1080 cookie second check inter 1000
Willy Tarreau24709282013-03-10 21:32:12 +01006838 server transp ipv4@
William Lallemandb2f07452015-05-12 14:27:13 +02006839 server backup "${SRV_BACKUP}:1080" backup
6840 server www1_dc1 "${LAN_DC1}.101:80"
6841 server www1_dc2 "${LAN_DC2}.101:80"
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006842
Mark Lamourinec2247f02012-01-04 13:02:01 -05006843 See also: "default-server", "http-send-name-header" and section 5 about
6844 server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006845
6846
6847source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02006848source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01006849source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006850 Set the source address for outgoing connections
6851 May be used in sections : defaults | frontend | listen | backend
6852 yes | no | yes | yes
6853 Arguments :
6854 <addr> is the IPv4 address HAProxy will bind to before connecting to a
6855 server. This address is also used as a source for health checks.
Willy Tarreau24709282013-03-10 21:32:12 +01006856
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006857 The default value of 0.0.0.0 means that the system will select
Willy Tarreau24709282013-03-10 21:32:12 +01006858 the most appropriate address to reach its destination. Optionally
6859 an address family prefix may be used before the address to force
6860 the family regardless of the address format, which can be useful
6861 to specify a path to a unix socket with no slash ('/'). Currently
6862 supported prefixes are :
6863 - 'ipv4@' -> address is always IPv4
6864 - 'ipv6@' -> address is always IPv6
6865 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +02006866 - 'abns@' -> address is in abstract namespace (Linux only)
William Lallemandb2f07452015-05-12 14:27:13 +02006867 You may want to reference some environment variables in the address
6868 parameter, see section 2.3 about environment variables.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006869
6870 <port> is an optional port. It is normally not needed but may be useful
6871 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02006872 the system will select a free port. Note that port ranges are not
6873 supported in the backend. If you want to force port ranges, you
6874 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006875
6876 <addr2> is the IP address to present to the server when connections are
6877 forwarded in full transparent proxy mode. This is currently only
6878 supported on some patched Linux kernels. When this address is
6879 specified, clients connecting to the server will be presented
6880 with this address, while health checks will still use the address
6881 <addr>.
6882
6883 <port2> is the optional port to present to the server when connections
6884 are forwarded in full transparent proxy mode (see <addr2> above).
6885 The default value of zero means the system will select a free
6886 port.
6887
Willy Tarreaubce70882009-09-07 11:51:47 +02006888 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
6889 This is the name of a comma-separated header list which can
6890 contain multiple IP addresses. By default, the last occurrence is
6891 used. This is designed to work with the X-Forwarded-For header
Baptiste Assmannea3e73b2013-02-02 23:47:49 +01006892 and to automatically bind to the client's IP address as seen
Willy Tarreaubce70882009-09-07 11:51:47 +02006893 by previous proxy, typically Stunnel. In order to use another
6894 occurrence from the last one, please see the <occ> parameter
6895 below. When the header (or occurrence) is not found, no binding
6896 is performed so that the proxy's default IP address is used. Also
6897 keep in mind that the header name is case insensitive, as for any
6898 HTTP header.
6899
6900 <occ> is the occurrence number of a value to be used in a multi-value
6901 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006902 in order to specify which occurrence to use for the source IP
Willy Tarreaubce70882009-09-07 11:51:47 +02006903 address. Positive values indicate a position from the first
6904 occurrence, 1 being the first one. Negative values indicate
6905 positions relative to the last one, -1 being the last one. This
6906 is helpful for situations where an X-Forwarded-For header is set
6907 at the entry point of an infrastructure and must be used several
6908 proxy layers away. When this value is not specified, -1 is
6909 assumed. Passing a zero here disables the feature.
6910
Willy Tarreaud53f96b2009-02-04 18:46:54 +01006911 <name> is an optional interface name to which to bind to for outgoing
6912 traffic. On systems supporting this features (currently, only
6913 Linux), this allows one to bind all traffic to the server to
6914 this interface even if it is not the one the system would select
6915 based on routing tables. This should be used with extreme care.
6916 Note that using this option requires root privileges.
6917
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006918 The "source" keyword is useful in complex environments where a specific
6919 address only is allowed to connect to the servers. It may be needed when a
6920 private address must be used through a public gateway for instance, and it is
6921 known that the system cannot determine the adequate source address by itself.
6922
6923 An extension which is available on certain patched Linux kernels may be used
6924 through the "usesrc" optional keyword. It makes it possible to connect to the
6925 servers with an IP address which does not belong to the system itself. This
6926 is called "full transparent proxy mode". For this to work, the destination
6927 servers have to route their traffic back to this address through the machine
6928 running HAProxy, and IP forwarding must generally be enabled on this machine.
6929
6930 In this "full transparent proxy" mode, it is possible to force a specific IP
6931 address to be presented to the servers. This is not much used in fact. A more
6932 common use is to tell HAProxy to present the client's IP address. For this,
6933 there are two methods :
6934
6935 - present the client's IP and port addresses. This is the most transparent
6936 mode, but it can cause problems when IP connection tracking is enabled on
6937 the machine, because a same connection may be seen twice with different
6938 states. However, this solution presents the huge advantage of not
6939 limiting the system to the 64k outgoing address+port couples, because all
6940 of the client ranges may be used.
6941
6942 - present only the client's IP address and select a spare port. This
6943 solution is still quite elegant but slightly less transparent (downstream
6944 firewalls logs will not match upstream's). It also presents the downside
6945 of limiting the number of concurrent connections to the usual 64k ports.
6946 However, since the upstream and downstream ports are different, local IP
6947 connection tracking on the machine will not be upset by the reuse of the
6948 same session.
6949
6950 Note that depending on the transparent proxy technology used, it may be
6951 required to force the source address. In fact, cttproxy version 2 requires an
6952 IP address in <addr> above, and does not support setting of "0.0.0.0" as the
6953 IP address because it creates NAT entries which much match the exact outgoing
6954 address. Tproxy version 4 and some other kernel patches which work in pure
6955 forwarding mode generally will not have this limitation.
6956
6957 This option sets the default source for all servers in the backend. It may
6958 also be specified in a "defaults" section. Finer source address specification
6959 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006960 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006961
Baptiste Assmann91bd3372015-07-17 21:59:42 +02006962 In order to work, "usesrc" requires root privileges.
6963
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006964 Examples :
6965 backend private
6966 # Connect to the servers using our 192.168.1.200 source address
6967 source 192.168.1.200
6968
6969 backend transparent_ssl1
6970 # Connect to the SSL farm from the client's source address
6971 source 192.168.1.200 usesrc clientip
6972
6973 backend transparent_ssl2
6974 # Connect to the SSL farm from the client's source address and port
6975 # not recommended if IP conntrack is present on the local machine.
6976 source 192.168.1.200 usesrc client
6977
6978 backend transparent_ssl3
6979 # Connect to the SSL farm from the client's source address. It
6980 # is more conntrack-friendly.
6981 source 192.168.1.200 usesrc clientip
6982
6983 backend transparent_smtp
6984 # Connect to the SMTP farm from the client's source address/port
6985 # with Tproxy version 4.
6986 source 0.0.0.0 usesrc clientip
6987
Willy Tarreaubce70882009-09-07 11:51:47 +02006988 backend transparent_http
6989 # Connect to the servers using the client's IP as seen by previous
6990 # proxy.
6991 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
6992
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006993 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006994 the Linux kernel on www.balabit.com, the "bind" keyword.
6995
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01006996
Willy Tarreau844e3c52008-01-11 16:28:18 +01006997srvtimeout <timeout> (deprecated)
6998 Set the maximum inactivity time on the server side.
6999 May be used in sections : defaults | frontend | listen | backend
7000 yes | no | yes | yes
7001 Arguments :
7002 <timeout> is the timeout value specified in milliseconds by default, but
7003 can be in any other unit if the number is suffixed by the unit,
7004 as explained at the top of this document.
7005
7006 The inactivity timeout applies when the server is expected to acknowledge or
7007 send data. In HTTP mode, this timeout is particularly important to consider
7008 during the first phase of the server's response, when it has to send the
7009 headers, as it directly represents the server's processing time for the
7010 request. To find out what value to put there, it's often good to start with
7011 what would be considered as unacceptable response times, then check the logs
7012 to observe the response time distribution, and adjust the value accordingly.
7013
7014 The value is specified in milliseconds by default, but can be in any other
7015 unit if the number is suffixed by the unit, as specified at the top of this
7016 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
7017 recommended that the client timeout remains equal to the server timeout in
7018 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01007019 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01007020 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreaud72758d2010-01-12 10:42:19 +01007021 seconds (eg: 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01007022
7023 This parameter is specific to backends, but can be specified once for all in
7024 "defaults" sections. This is in fact one of the easiest solutions not to
7025 forget about it. An unspecified timeout results in an infinite timeout, which
7026 is not recommended. Such a usage is accepted and works but reports a warning
7027 during startup because it may results in accumulation of expired sessions in
7028 the system if the system's timeouts are not configured either.
7029
7030 This parameter is provided for compatibility but is currently deprecated.
7031 Please use "timeout server" instead.
7032
Willy Tarreauce887fd2012-05-12 12:50:00 +02007033 See also : "timeout server", "timeout tunnel", "timeout client" and
7034 "clitimeout".
Willy Tarreau844e3c52008-01-11 16:28:18 +01007035
7036
Cyril Bonté66c327d2010-10-12 00:14:37 +02007037stats admin { if | unless } <cond>
7038 Enable statistics admin level if/unless a condition is matched
7039 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02007040 no | yes | yes | yes
Cyril Bonté66c327d2010-10-12 00:14:37 +02007041
7042 This statement enables the statistics admin level if/unless a condition is
7043 matched.
7044
7045 The admin level allows to enable/disable servers from the web interface. By
7046 default, statistics page is read-only for security reasons.
7047
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01007048 Note : Consider not using this feature in multi-process mode (nbproc > 1)
7049 unless you know what you do : memory is not shared between the
7050 processes, which can result in random behaviours.
7051
Cyril Bonté23b39d92011-02-10 22:54:44 +01007052 Currently, the POST request is limited to the buffer size minus the reserved
7053 buffer space, which means that if the list of servers is too long, the
7054 request won't be processed. It is recommended to alter few servers at a
7055 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02007056
7057 Example :
7058 # statistics admin level only for localhost
7059 backend stats_localhost
7060 stats enable
7061 stats admin if LOCALHOST
7062
7063 Example :
7064 # statistics admin level always enabled because of the authentication
7065 backend stats_auth
7066 stats enable
7067 stats auth admin:AdMiN123
7068 stats admin if TRUE
7069
7070 Example :
7071 # statistics admin level depends on the authenticated user
7072 userlist stats-auth
7073 group admin users admin
7074 user admin insecure-password AdMiN123
7075 group readonly users haproxy
7076 user haproxy insecure-password haproxy
7077
7078 backend stats_auth
7079 stats enable
7080 acl AUTH http_auth(stats-auth)
7081 acl AUTH_ADMIN http_auth_group(stats-auth) admin
7082 stats http-request auth unless AUTH
7083 stats admin if AUTH_ADMIN
7084
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01007085 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
7086 "bind-process", section 3.4 about userlists and section 7 about
7087 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02007088
7089
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007090stats auth <user>:<passwd>
7091 Enable statistics with authentication and grant access to an account
7092 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02007093 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007094 Arguments :
7095 <user> is a user name to grant access to
7096
7097 <passwd> is the cleartext password associated to this user
7098
7099 This statement enables statistics with default settings, and restricts access
7100 to declared users only. It may be repeated as many times as necessary to
7101 allow as many users as desired. When a user tries to access the statistics
7102 without a valid account, a "401 Forbidden" response will be returned so that
7103 the browser asks the user to provide a valid user and password. The real
7104 which will be returned to the browser is configurable using "stats realm".
7105
7106 Since the authentication method is HTTP Basic Authentication, the passwords
7107 circulate in cleartext on the network. Thus, it was decided that the
7108 configuration file would also use cleartext passwords to remind the users
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02007109 that those ones should not be sensitive and not shared with any other account.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007110
7111 It is also possible to reduce the scope of the proxies which appear in the
7112 report using "stats scope".
7113
7114 Though this statement alone is enough to enable statistics reporting, it is
7115 recommended to set all other settings in order to avoid relying on default
7116 unobvious parameters.
7117
7118 Example :
7119 # public access (limited to this backend only)
7120 backend public_www
7121 server srv1 192.168.0.1:80
7122 stats enable
7123 stats hide-version
7124 stats scope .
7125 stats uri /admin?stats
7126 stats realm Haproxy\ Statistics
7127 stats auth admin1:AdMiN123
7128 stats auth admin2:AdMiN321
7129
7130 # internal monitoring access (unlimited)
7131 backend private_monitoring
7132 stats enable
7133 stats uri /admin?stats
7134 stats refresh 5s
7135
7136 See also : "stats enable", "stats realm", "stats scope", "stats uri"
7137
7138
7139stats enable
7140 Enable statistics reporting with default settings
7141 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02007142 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007143 Arguments : none
7144
7145 This statement enables statistics reporting with default settings defined
7146 at build time. Unless stated otherwise, these settings are used :
7147 - stats uri : /haproxy?stats
7148 - stats realm : "HAProxy Statistics"
7149 - stats auth : no authentication
7150 - stats scope : no restriction
7151
7152 Though this statement alone is enough to enable statistics reporting, it is
7153 recommended to set all other settings in order to avoid relying on default
7154 unobvious parameters.
7155
7156 Example :
7157 # public access (limited to this backend only)
7158 backend public_www
7159 server srv1 192.168.0.1:80
7160 stats enable
7161 stats hide-version
7162 stats scope .
7163 stats uri /admin?stats
7164 stats realm Haproxy\ Statistics
7165 stats auth admin1:AdMiN123
7166 stats auth admin2:AdMiN321
7167
7168 # internal monitoring access (unlimited)
7169 backend private_monitoring
7170 stats enable
7171 stats uri /admin?stats
7172 stats refresh 5s
7173
7174 See also : "stats auth", "stats realm", "stats uri"
7175
7176
Willy Tarreaud63335a2010-02-26 12:56:52 +01007177stats hide-version
7178 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02007179 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02007180 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01007181 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02007182
Willy Tarreaud63335a2010-02-26 12:56:52 +01007183 By default, the stats page reports some useful status information along with
7184 the statistics. Among them is HAProxy's version. However, it is generally
7185 considered dangerous to report precise version to anyone, as it can help them
7186 target known weaknesses with specific attacks. The "stats hide-version"
7187 statement removes the version from the statistics report. This is recommended
7188 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02007189
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02007190 Though this statement alone is enough to enable statistics reporting, it is
7191 recommended to set all other settings in order to avoid relying on default
7192 unobvious parameters.
7193
Willy Tarreaud63335a2010-02-26 12:56:52 +01007194 Example :
7195 # public access (limited to this backend only)
7196 backend public_www
7197 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02007198 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01007199 stats hide-version
7200 stats scope .
7201 stats uri /admin?stats
7202 stats realm Haproxy\ Statistics
7203 stats auth admin1:AdMiN123
7204 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02007205
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02007206 # internal monitoring access (unlimited)
7207 backend private_monitoring
7208 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01007209 stats uri /admin?stats
7210 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01007211
Willy Tarreaud63335a2010-02-26 12:56:52 +01007212 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02007213
Willy Tarreau983e01e2010-01-11 18:42:06 +01007214
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02007215stats http-request { allow | deny | auth [realm <realm>] }
7216 [ { if | unless } <condition> ]
7217 Access control for statistics
7218
7219 May be used in sections: defaults | frontend | listen | backend
7220 no | no | yes | yes
7221
7222 As "http-request", these set of options allow to fine control access to
7223 statistics. Each option may be followed by if/unless and acl.
7224 First option with matched condition (or option without condition) is final.
7225 For "deny" a 403 error will be returned, for "allow" normal processing is
7226 performed, for "auth" a 401/407 error code is returned so the client
7227 should be asked to enter a username and password.
7228
7229 There is no fixed limit to the number of http-request statements per
7230 instance.
7231
7232 See also : "http-request", section 3.4 about userlists and section 7
7233 about ACL usage.
7234
7235
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007236stats realm <realm>
7237 Enable statistics and set authentication realm
7238 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02007239 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007240 Arguments :
7241 <realm> is the name of the HTTP Basic Authentication realm reported to
7242 the browser. The browser uses it to display it in the pop-up
7243 inviting the user to enter a valid username and password.
7244
7245 The realm is read as a single word, so any spaces in it should be escaped
7246 using a backslash ('\').
7247
7248 This statement is useful only in conjunction with "stats auth" since it is
7249 only related to authentication.
7250
7251 Though this statement alone is enough to enable statistics reporting, it is
7252 recommended to set all other settings in order to avoid relying on default
7253 unobvious parameters.
7254
7255 Example :
7256 # public access (limited to this backend only)
7257 backend public_www
7258 server srv1 192.168.0.1:80
7259 stats enable
7260 stats hide-version
7261 stats scope .
7262 stats uri /admin?stats
7263 stats realm Haproxy\ Statistics
7264 stats auth admin1:AdMiN123
7265 stats auth admin2:AdMiN321
7266
7267 # internal monitoring access (unlimited)
7268 backend private_monitoring
7269 stats enable
7270 stats uri /admin?stats
7271 stats refresh 5s
7272
7273 See also : "stats auth", "stats enable", "stats uri"
7274
7275
7276stats refresh <delay>
7277 Enable statistics with automatic refresh
7278 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02007279 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007280 Arguments :
7281 <delay> is the suggested refresh delay, specified in seconds, which will
7282 be returned to the browser consulting the report page. While the
7283 browser is free to apply any delay, it will generally respect it
7284 and refresh the page this every seconds. The refresh interval may
7285 be specified in any other non-default time unit, by suffixing the
7286 unit after the value, as explained at the top of this document.
7287
7288 This statement is useful on monitoring displays with a permanent page
7289 reporting the load balancer's activity. When set, the HTML report page will
7290 include a link "refresh"/"stop refresh" so that the user can select whether
7291 he wants automatic refresh of the page or not.
7292
7293 Though this statement alone is enough to enable statistics reporting, it is
7294 recommended to set all other settings in order to avoid relying on default
7295 unobvious parameters.
7296
7297 Example :
7298 # public access (limited to this backend only)
7299 backend public_www
7300 server srv1 192.168.0.1:80
7301 stats enable
7302 stats hide-version
7303 stats scope .
7304 stats uri /admin?stats
7305 stats realm Haproxy\ Statistics
7306 stats auth admin1:AdMiN123
7307 stats auth admin2:AdMiN321
7308
7309 # internal monitoring access (unlimited)
7310 backend private_monitoring
7311 stats enable
7312 stats uri /admin?stats
7313 stats refresh 5s
7314
7315 See also : "stats auth", "stats enable", "stats realm", "stats uri"
7316
7317
7318stats scope { <name> | "." }
7319 Enable statistics and limit access scope
7320 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02007321 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007322 Arguments :
7323 <name> is the name of a listen, frontend or backend section to be
7324 reported. The special name "." (a single dot) designates the
7325 section in which the statement appears.
7326
7327 When this statement is specified, only the sections enumerated with this
7328 statement will appear in the report. All other ones will be hidden. This
7329 statement may appear as many times as needed if multiple sections need to be
7330 reported. Please note that the name checking is performed as simple string
7331 comparisons, and that it is never checked that a give section name really
7332 exists.
7333
7334 Though this statement alone is enough to enable statistics reporting, it is
7335 recommended to set all other settings in order to avoid relying on default
7336 unobvious parameters.
7337
7338 Example :
7339 # public access (limited to this backend only)
7340 backend public_www
7341 server srv1 192.168.0.1:80
7342 stats enable
7343 stats hide-version
7344 stats scope .
7345 stats uri /admin?stats
7346 stats realm Haproxy\ Statistics
7347 stats auth admin1:AdMiN123
7348 stats auth admin2:AdMiN321
7349
7350 # internal monitoring access (unlimited)
7351 backend private_monitoring
7352 stats enable
7353 stats uri /admin?stats
7354 stats refresh 5s
7355
7356 See also : "stats auth", "stats enable", "stats realm", "stats uri"
7357
Willy Tarreaud63335a2010-02-26 12:56:52 +01007358
Willy Tarreauc9705a12010-07-27 20:05:50 +02007359stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01007360 Enable reporting of a description on the statistics page.
7361 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02007362 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01007363
Willy Tarreauc9705a12010-07-27 20:05:50 +02007364 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01007365 description from global section is automatically used instead.
7366
7367 This statement is useful for users that offer shared services to their
7368 customers, where node or description should be different for each customer.
7369
7370 Though this statement alone is enough to enable statistics reporting, it is
7371 recommended to set all other settings in order to avoid relying on default
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04007372 unobvious parameters. By default description is not shown.
Willy Tarreaud63335a2010-02-26 12:56:52 +01007373
7374 Example :
7375 # internal monitoring access (unlimited)
7376 backend private_monitoring
7377 stats enable
7378 stats show-desc Master node for Europe, Asia, Africa
7379 stats uri /admin?stats
7380 stats refresh 5s
7381
7382 See also: "show-node", "stats enable", "stats uri" and "description" in
7383 global section.
7384
7385
7386stats show-legends
Willy Tarreaued2119c2014-04-24 22:10:39 +02007387 Enable reporting additional information on the statistics page
7388 May be used in sections : defaults | frontend | listen | backend
7389 yes | yes | yes | yes
7390 Arguments : none
7391
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007392 Enable reporting additional information on the statistics page :
Willy Tarreaud63335a2010-02-26 12:56:52 +01007393 - cap: capabilities (proxy)
7394 - mode: one of tcp, http or health (proxy)
7395 - id: SNMP ID (proxy, socket, server)
7396 - IP (socket, server)
7397 - cookie (backend, server)
7398
7399 Though this statement alone is enough to enable statistics reporting, it is
7400 recommended to set all other settings in order to avoid relying on default
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04007401 unobvious parameters. Default behaviour is not to show this information.
Willy Tarreaud63335a2010-02-26 12:56:52 +01007402
7403 See also: "stats enable", "stats uri".
7404
7405
7406stats show-node [ <name> ]
7407 Enable reporting of a host name on the statistics page.
7408 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02007409 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01007410 Arguments:
7411 <name> is an optional name to be reported. If unspecified, the
7412 node name from global section is automatically used instead.
7413
7414 This statement is useful for users that offer shared services to their
7415 customers, where node or description might be different on a stats page
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04007416 provided for each customer. Default behaviour is not to show host name.
Willy Tarreaud63335a2010-02-26 12:56:52 +01007417
7418 Though this statement alone is enough to enable statistics reporting, it is
7419 recommended to set all other settings in order to avoid relying on default
7420 unobvious parameters.
7421
7422 Example:
7423 # internal monitoring access (unlimited)
7424 backend private_monitoring
7425 stats enable
7426 stats show-node Europe-1
7427 stats uri /admin?stats
7428 stats refresh 5s
7429
7430 See also: "show-desc", "stats enable", "stats uri", and "node" in global
7431 section.
7432
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007433
7434stats uri <prefix>
7435 Enable statistics and define the URI prefix to access them
7436 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02007437 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007438 Arguments :
7439 <prefix> is the prefix of any URI which will be redirected to stats. This
7440 prefix may contain a question mark ('?') to indicate part of a
7441 query string.
7442
7443 The statistics URI is intercepted on the relayed traffic, so it appears as a
7444 page within the normal application. It is strongly advised to ensure that the
7445 selected URI will never appear in the application, otherwise it will never be
7446 possible to reach it in the application.
7447
7448 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007449 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007450 It is generally a good idea to include a question mark in the URI so that
7451 intermediate proxies refrain from caching the results. Also, since any string
7452 beginning with the prefix will be accepted as a stats request, the question
7453 mark helps ensuring that no valid URI will begin with the same words.
7454
7455 It is sometimes very convenient to use "/" as the URI prefix, and put that
7456 statement in a "listen" instance of its own. That makes it easy to dedicate
7457 an address or a port to statistics only.
7458
7459 Though this statement alone is enough to enable statistics reporting, it is
7460 recommended to set all other settings in order to avoid relying on default
7461 unobvious parameters.
7462
7463 Example :
7464 # public access (limited to this backend only)
7465 backend public_www
7466 server srv1 192.168.0.1:80
7467 stats enable
7468 stats hide-version
7469 stats scope .
7470 stats uri /admin?stats
7471 stats realm Haproxy\ Statistics
7472 stats auth admin1:AdMiN123
7473 stats auth admin2:AdMiN321
7474
7475 # internal monitoring access (unlimited)
7476 backend private_monitoring
7477 stats enable
7478 stats uri /admin?stats
7479 stats refresh 5s
7480
7481 See also : "stats auth", "stats enable", "stats realm"
7482
7483
Willy Tarreaud63335a2010-02-26 12:56:52 +01007484stick match <pattern> [table <table>] [{if | unless} <cond>]
7485 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007486 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +01007487 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007488
7489 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02007490 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007491 describes what elements of the incoming request or connection
7492 will be analysed in the hope to find a matching entry in a
7493 stickiness table. This rule is mandatory.
7494
7495 <table> is an optional stickiness table name. If unspecified, the same
7496 backend's table is used. A stickiness table is declared using
7497 the "stick-table" statement.
7498
7499 <cond> is an optional matching condition. It makes it possible to match
7500 on a certain criterion only when other conditions are met (or
7501 not met). For instance, it could be used to match on a source IP
7502 address except when a request passes through a known proxy, in
7503 which case we'd match on a header containing that IP address.
7504
7505 Some protocols or applications require complex stickiness rules and cannot
7506 always simply rely on cookies nor hashing. The "stick match" statement
7507 describes a rule to extract the stickiness criterion from an incoming request
7508 or connection. See section 7 for a complete list of possible patterns and
7509 transformation rules.
7510
7511 The table has to be declared using the "stick-table" statement. It must be of
7512 a type compatible with the pattern. By default it is the one which is present
7513 in the same backend. It is possible to share a table with other backends by
7514 referencing it using the "table" keyword. If another table is referenced,
7515 the server's ID inside the backends are used. By default, all server IDs
7516 start at 1 in each backend, so the server ordering is enough. But in case of
7517 doubt, it is highly recommended to force server IDs using their "id" setting.
7518
7519 It is possible to restrict the conditions where a "stick match" statement
7520 will apply, using "if" or "unless" followed by a condition. See section 7 for
7521 ACL based conditions.
7522
7523 There is no limit on the number of "stick match" statements. The first that
7524 applies and matches will cause the request to be directed to the same server
7525 as was used for the request which created the entry. That way, multiple
7526 matches can be used as fallbacks.
7527
7528 The stick rules are checked after the persistence cookies, so they will not
7529 affect stickiness if a cookie has already been used to select a server. That
7530 way, it becomes very easy to insert cookies and match on IP addresses in
7531 order to maintain stickiness between HTTP and HTTPS.
7532
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01007533 Note : Consider not using this feature in multi-process mode (nbproc > 1)
7534 unless you know what you do : memory is not shared between the
7535 processes, which can result in random behaviours.
7536
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007537 Example :
7538 # forward SMTP users to the same server they just used for POP in the
7539 # last 30 minutes
7540 backend pop
7541 mode tcp
7542 balance roundrobin
7543 stick store-request src
7544 stick-table type ip size 200k expire 30m
7545 server s1 192.168.1.1:110
7546 server s2 192.168.1.1:110
7547
7548 backend smtp
7549 mode tcp
7550 balance roundrobin
7551 stick match src table pop
7552 server s1 192.168.1.1:25
7553 server s2 192.168.1.1:25
7554
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01007555 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +02007556 about ACLs and samples fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007557
7558
7559stick on <pattern> [table <table>] [{if | unless} <condition>]
7560 Define a request pattern to associate a user to a server
7561 May be used in sections : defaults | frontend | listen | backend
7562 no | no | yes | yes
7563
7564 Note : This form is exactly equivalent to "stick match" followed by
7565 "stick store-request", all with the same arguments. Please refer
7566 to both keywords for details. It is only provided as a convenience
7567 for writing more maintainable configurations.
7568
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01007569 Note : Consider not using this feature in multi-process mode (nbproc > 1)
7570 unless you know what you do : memory is not shared between the
7571 processes, which can result in random behaviours.
7572
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007573 Examples :
7574 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +01007575 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007576
7577 # ...is strictly equivalent to this one :
7578 stick match src table pop if !localhost
7579 stick store-request src table pop if !localhost
7580
7581
7582 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
7583 # well as HTTP without cookie. Share the same table between both accesses.
7584 backend http
7585 mode http
7586 balance roundrobin
7587 stick on src table https
7588 cookie SRV insert indirect nocache
7589 server s1 192.168.1.1:80 cookie s1
7590 server s2 192.168.1.1:80 cookie s2
7591
7592 backend https
7593 mode tcp
7594 balance roundrobin
7595 stick-table type ip size 200k expire 30m
7596 stick on src
7597 server s1 192.168.1.1:443
7598 server s2 192.168.1.1:443
7599
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01007600 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007601
7602
7603stick store-request <pattern> [table <table>] [{if | unless} <condition>]
7604 Define a request pattern used to create an entry in a stickiness table
7605 May be used in sections : defaults | frontend | listen | backend
7606 no | no | yes | yes
7607
7608 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02007609 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007610 describes what elements of the incoming request or connection
7611 will be analysed, extracted and stored in the table once a
7612 server is selected.
7613
7614 <table> is an optional stickiness table name. If unspecified, the same
7615 backend's table is used. A stickiness table is declared using
7616 the "stick-table" statement.
7617
7618 <cond> is an optional storage condition. It makes it possible to store
7619 certain criteria only when some conditions are met (or not met).
7620 For instance, it could be used to store the source IP address
7621 except when the request passes through a known proxy, in which
7622 case we'd store a converted form of a header containing that IP
7623 address.
7624
7625 Some protocols or applications require complex stickiness rules and cannot
7626 always simply rely on cookies nor hashing. The "stick store-request" statement
7627 describes a rule to decide what to extract from the request and when to do
7628 it, in order to store it into a stickiness table for further requests to
7629 match it using the "stick match" statement. Obviously the extracted part must
7630 make sense and have a chance to be matched in a further request. Storing a
7631 client's IP address for instance often makes sense. Storing an ID found in a
7632 URL parameter also makes sense. Storing a source port will almost never make
7633 any sense because it will be randomly matched. See section 7 for a complete
7634 list of possible patterns and transformation rules.
7635
7636 The table has to be declared using the "stick-table" statement. It must be of
7637 a type compatible with the pattern. By default it is the one which is present
7638 in the same backend. It is possible to share a table with other backends by
7639 referencing it using the "table" keyword. If another table is referenced,
7640 the server's ID inside the backends are used. By default, all server IDs
7641 start at 1 in each backend, so the server ordering is enough. But in case of
7642 doubt, it is highly recommended to force server IDs using their "id" setting.
7643
7644 It is possible to restrict the conditions where a "stick store-request"
7645 statement will apply, using "if" or "unless" followed by a condition. This
7646 condition will be evaluated while parsing the request, so any criteria can be
7647 used. See section 7 for ACL based conditions.
7648
7649 There is no limit on the number of "stick store-request" statements, but
7650 there is a limit of 8 simultaneous stores per request or response. This
7651 makes it possible to store up to 8 criteria, all extracted from either the
7652 request or the response, regardless of the number of rules. Only the 8 first
7653 ones which match will be kept. Using this, it is possible to feed multiple
7654 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +01007655 another protocol or access method. Using multiple store-request rules with
7656 the same table is possible and may be used to find the best criterion to rely
7657 on, by arranging the rules by decreasing preference order. Only the first
7658 extracted criterion for a given table will be stored. All subsequent store-
7659 request rules referencing the same table will be skipped and their ACLs will
7660 not be evaluated.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007661
7662 The "store-request" rules are evaluated once the server connection has been
7663 established, so that the table will contain the real server that processed
7664 the request.
7665
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01007666 Note : Consider not using this feature in multi-process mode (nbproc > 1)
7667 unless you know what you do : memory is not shared between the
7668 processes, which can result in random behaviours.
7669
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007670 Example :
7671 # forward SMTP users to the same server they just used for POP in the
7672 # last 30 minutes
7673 backend pop
7674 mode tcp
7675 balance roundrobin
7676 stick store-request src
7677 stick-table type ip size 200k expire 30m
7678 server s1 192.168.1.1:110
7679 server s2 192.168.1.1:110
7680
7681 backend smtp
7682 mode tcp
7683 balance roundrobin
7684 stick match src table pop
7685 server s1 192.168.1.1:25
7686 server s2 192.168.1.1:25
7687
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01007688 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +02007689 about ACLs and sample fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007690
7691
Emeric Brun7c6b82e2010-09-24 16:34:28 +02007692stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +02007693 size <size> [expire <expire>] [nopurge] [peers <peersect>]
7694 [store <data_type>]*
Godbach64cef792013-12-04 16:08:22 +08007695 Configure the stickiness table for the current section
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007696 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +02007697 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007698
7699 Arguments :
7700 ip a table declared with "type ip" will only store IPv4 addresses.
7701 This form is very compact (about 50 bytes per entry) and allows
7702 very fast entry lookup and stores with almost no overhead. This
7703 is mainly used to store client source IP addresses.
7704
David du Colombier9a6d3c92011-03-17 10:40:24 +01007705 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
7706 This form is very compact (about 60 bytes per entry) and allows
7707 very fast entry lookup and stores with almost no overhead. This
7708 is mainly used to store client source IP addresses.
7709
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007710 integer a table declared with "type integer" will store 32bit integers
7711 which can represent a client identifier found in a request for
7712 instance.
7713
7714 string a table declared with "type string" will store substrings of up
7715 to <len> characters. If the string provided by the pattern
7716 extractor is larger than <len>, it will be truncated before
7717 being stored. During matching, at most <len> characters will be
7718 compared between the string in the table and the extracted
7719 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +02007720 to 32 characters.
7721
7722 binary a table declared with "type binary" will store binary blocks
7723 of <len> bytes. If the block provided by the pattern
7724 extractor is larger than <len>, it will be truncated before
Willy Tarreaube722a22014-06-13 16:31:59 +02007725 being stored. If the block provided by the sample expression
Emeric Brun7c6b82e2010-09-24 16:34:28 +02007726 is shorter than <len>, it will be padded by 0. When not
7727 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007728
7729 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +02007730 "string" type table (See type "string" above). Or the number
7731 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007732 changing this parameter as memory usage will proportionally
7733 increase.
7734
7735 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +01007736 value directly impacts memory usage. Count approximately
7737 50 bytes per entry, plus the size of a string if any. The size
7738 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007739
7740 [nopurge] indicates that we refuse to purge older entries when the table
7741 is full. When not specified and the table is full when haproxy
7742 wants to store an entry in it, it will flush a few of the oldest
7743 entries in order to release some space for the new ones. This is
7744 most often the desired behaviour. In some specific cases, it
7745 be desirable to refuse new entries instead of purging the older
7746 ones. That may be the case when the amount of data to store is
7747 far above the hardware limits and we prefer not to offer access
7748 to new clients than to reject the ones already connected. When
7749 using this parameter, be sure to properly set the "expire"
7750 parameter (see below).
7751
Emeric Brunf099e792010-09-27 12:05:28 +02007752 <peersect> is the name of the peers section to use for replication. Entries
7753 which associate keys to server IDs are kept synchronized with
7754 the remote peers declared in this section. All entries are also
7755 automatically learned from the local peer (old process) during a
7756 soft restart.
7757
Willy Tarreau1abc6732015-05-01 19:21:02 +02007758 NOTE : each peers section may be referenced only by tables
7759 belonging to the same unique process.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01007760
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007761 <expire> defines the maximum duration of an entry in the table since it
7762 was last created, refreshed or matched. The expiration delay is
7763 defined using the standard time format, similarly as the various
7764 timeouts. The maximum duration is slightly above 24 days. See
7765 section 2.2 for more information. If this delay is not specified,
Cyril Bontédc4d9032012-04-08 21:57:39 +02007766 the session won't automatically expire, but older entries will
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007767 be removed once full. Be sure not to use the "nopurge" parameter
7768 if not expiration delay is specified.
7769
Willy Tarreau08d5f982010-06-06 13:34:54 +02007770 <data_type> is used to store additional information in the stick-table. This
7771 may be used by ACLs in order to control various criteria related
7772 to the activity of the client matching the stick-table. For each
7773 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +02007774 that the additional data can fit. Several data types may be
7775 stored with an entry. Multiple data types may be specified after
7776 the "store" keyword, as a comma-separated list. Alternatively,
7777 it is possible to repeat the "store" keyword followed by one or
7778 several data types. Except for the "server_id" type which is
7779 automatically detected and enabled, all data types must be
7780 explicitly declared to be stored. If an ACL references a data
7781 type which is not stored, the ACL will simply not match. Some
7782 data types require an argument which must be passed just after
7783 the type between parenthesis. See below for the supported data
7784 types and their arguments.
7785
7786 The data types that can be stored with an entry are the following :
7787 - server_id : this is an integer which holds the numeric ID of the server a
7788 request was assigned to. It is used by the "stick match", "stick store",
7789 and "stick on" rules. It is automatically enabled when referenced.
7790
7791 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
7792 integer which may be used for anything. Most of the time it will be used
7793 to put a special tag on some entries, for instance to note that a
7794 specific behaviour was detected and must be known for future matches.
7795
Willy Tarreauba2ffd12013-05-29 15:54:14 +02007796 - gpc0_rate(<period>) : increment rate of the first General Purpose Counter
7797 over a period. It is a positive 32-bit integer integer which may be used
7798 for anything. Just like <gpc0>, it counts events, but instead of keeping
7799 a cumulative count, it maintains the rate at which the counter is
7800 incremented. Most of the time it will be used to measure the frequency of
7801 occurrence of certain events (eg: requests to a specific URL).
7802
Willy Tarreauc9705a12010-07-27 20:05:50 +02007803 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
7804 the absolute number of connections received from clients which matched
7805 this entry. It does not mean the connections were accepted, just that
7806 they were received.
7807
7808 - conn_cur : Current Connections. It is a positive 32-bit integer which
7809 stores the concurrent connection counts for the entry. It is incremented
7810 once an incoming connection matches the entry, and decremented once the
7811 connection leaves. That way it is possible to know at any time the exact
7812 number of concurrent connections for an entry.
7813
7814 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
7815 integer parameter <period> which indicates in milliseconds the length
7816 of the period over which the average is measured. It reports the average
7817 incoming connection rate over that period, in connections per period. The
7818 result is an integer which can be matched using ACLs.
7819
7820 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
7821 the absolute number of sessions received from clients which matched this
7822 entry. A session is a connection that was accepted by the layer 4 rules.
7823
7824 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
7825 integer parameter <period> which indicates in milliseconds the length
7826 of the period over which the average is measured. It reports the average
7827 incoming session rate over that period, in sessions per period. The
7828 result is an integer which can be matched using ACLs.
7829
7830 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
7831 counts the absolute number of HTTP requests received from clients which
7832 matched this entry. It does not matter whether they are valid requests or
7833 not. Note that this is different from sessions when keep-alive is used on
7834 the client side.
7835
7836 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
7837 integer parameter <period> which indicates in milliseconds the length
7838 of the period over which the average is measured. It reports the average
7839 HTTP request rate over that period, in requests per period. The result is
7840 an integer which can be matched using ACLs. It does not matter whether
7841 they are valid requests or not. Note that this is different from sessions
7842 when keep-alive is used on the client side.
7843
7844 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
7845 counts the absolute number of HTTP requests errors induced by clients
7846 which matched this entry. Errors are counted on invalid and truncated
7847 requests, as well as on denied or tarpitted requests, and on failed
7848 authentications. If the server responds with 4xx, then the request is
7849 also counted as an error since it's an error triggered by the client
7850 (eg: vulnerability scan).
7851
7852 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
7853 integer parameter <period> which indicates in milliseconds the length
7854 of the period over which the average is measured. It reports the average
7855 HTTP request error rate over that period, in requests per period (see
7856 http_err_cnt above for what is accounted as an error). The result is an
7857 integer which can be matched using ACLs.
7858
7859 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
7860 integer which counts the cumulated amount of bytes received from clients
7861 which matched this entry. Headers are included in the count. This may be
7862 used to limit abuse of upload features on photo or video servers.
7863
7864 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
7865 integer parameter <period> which indicates in milliseconds the length
7866 of the period over which the average is measured. It reports the average
7867 incoming bytes rate over that period, in bytes per period. It may be used
7868 to detect users which upload too much and too fast. Warning: with large
7869 uploads, it is possible that the amount of uploaded data will be counted
7870 once upon termination, thus causing spikes in the average transfer speed
7871 instead of having a smooth one. This may partially be smoothed with
7872 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
7873 recommended for better fairness.
7874
7875 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
7876 integer which counts the cumulated amount of bytes sent to clients which
7877 matched this entry. Headers are included in the count. This may be used
7878 to limit abuse of bots sucking the whole site.
7879
7880 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
7881 an integer parameter <period> which indicates in milliseconds the length
7882 of the period over which the average is measured. It reports the average
7883 outgoing bytes rate over that period, in bytes per period. It may be used
7884 to detect users which download too much and too fast. Warning: with large
7885 transfers, it is possible that the amount of transferred data will be
7886 counted once upon termination, thus causing spikes in the average
7887 transfer speed instead of having a smooth one. This may partially be
7888 smoothed with "option contstats" though this is not perfect yet. Use of
7889 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +02007890
Willy Tarreauc00cdc22010-06-06 16:48:26 +02007891 There is only one stick-table per proxy. At the moment of writing this doc,
7892 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007893 to be required, simply create a dummy backend with a stick-table in it and
7894 reference it.
7895
7896 It is important to understand that stickiness based on learning information
7897 has some limitations, including the fact that all learned associations are
7898 lost upon restart. In general it can be good as a complement but not always
7899 as an exclusive stickiness.
7900
Willy Tarreauc9705a12010-07-27 20:05:50 +02007901 Last, memory requirements may be important when storing many data types.
7902 Indeed, storing all indicators above at once in each entry requires 116 bytes
7903 per entry, or 116 MB for a 1-million entries table. This is definitely not
7904 something that can be ignored.
7905
7906 Example:
7907 # Keep track of counters of up to 1 million IP addresses over 5 minutes
7908 # and store a general purpose counter and the average connection rate
7909 # computed over a sliding window of 30 seconds.
7910 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
7911
7912 See also : "stick match", "stick on", "stick store-request", section 2.2
David du Colombiera13d1b92011-03-17 10:40:22 +01007913 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01007914
7915
Emeric Brun6a1cefa2010-09-24 18:15:17 +02007916stick store-response <pattern> [table <table>] [{if | unless} <condition>]
7917 Define a request pattern used to create an entry in a stickiness table
7918 May be used in sections : defaults | frontend | listen | backend
7919 no | no | yes | yes
7920
7921 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02007922 <pattern> is a sample expression rule as described in section 7.3. It
Emeric Brun6a1cefa2010-09-24 18:15:17 +02007923 describes what elements of the response or connection will
7924 be analysed, extracted and stored in the table once a
7925 server is selected.
7926
7927 <table> is an optional stickiness table name. If unspecified, the same
7928 backend's table is used. A stickiness table is declared using
7929 the "stick-table" statement.
7930
7931 <cond> is an optional storage condition. It makes it possible to store
7932 certain criteria only when some conditions are met (or not met).
7933 For instance, it could be used to store the SSL session ID only
7934 when the response is a SSL server hello.
7935
7936 Some protocols or applications require complex stickiness rules and cannot
7937 always simply rely on cookies nor hashing. The "stick store-response"
7938 statement describes a rule to decide what to extract from the response and
7939 when to do it, in order to store it into a stickiness table for further
7940 requests to match it using the "stick match" statement. Obviously the
7941 extracted part must make sense and have a chance to be matched in a further
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007942 request. Storing an ID found in a header of a response makes sense.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02007943 See section 7 for a complete list of possible patterns and transformation
7944 rules.
7945
7946 The table has to be declared using the "stick-table" statement. It must be of
7947 a type compatible with the pattern. By default it is the one which is present
7948 in the same backend. It is possible to share a table with other backends by
7949 referencing it using the "table" keyword. If another table is referenced,
7950 the server's ID inside the backends are used. By default, all server IDs
7951 start at 1 in each backend, so the server ordering is enough. But in case of
7952 doubt, it is highly recommended to force server IDs using their "id" setting.
7953
7954 It is possible to restrict the conditions where a "stick store-response"
7955 statement will apply, using "if" or "unless" followed by a condition. This
7956 condition will be evaluated while parsing the response, so any criteria can
7957 be used. See section 7 for ACL based conditions.
7958
7959 There is no limit on the number of "stick store-response" statements, but
7960 there is a limit of 8 simultaneous stores per request or response. This
7961 makes it possible to store up to 8 criteria, all extracted from either the
7962 request or the response, regardless of the number of rules. Only the 8 first
7963 ones which match will be kept. Using this, it is possible to feed multiple
7964 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +01007965 another protocol or access method. Using multiple store-response rules with
7966 the same table is possible and may be used to find the best criterion to rely
7967 on, by arranging the rules by decreasing preference order. Only the first
7968 extracted criterion for a given table will be stored. All subsequent store-
7969 response rules referencing the same table will be skipped and their ACLs will
7970 not be evaluated. However, even if a store-request rule references a table, a
7971 store-response rule may also use the same table. This means that each table
7972 may learn exactly one element from the request and one element from the
7973 response at once.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02007974
7975 The table will contain the real server that processed the request.
7976
7977 Example :
7978 # Learn SSL session ID from both request and response and create affinity.
7979 backend https
7980 mode tcp
7981 balance roundrobin
Cyril Bontédc4d9032012-04-08 21:57:39 +02007982 # maximum SSL session ID length is 32 bytes.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02007983 stick-table type binary len 32 size 30k expire 30m
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007984
Emeric Brun6a1cefa2010-09-24 18:15:17 +02007985 acl clienthello req_ssl_hello_type 1
7986 acl serverhello rep_ssl_hello_type 2
7987
7988 # use tcp content accepts to detects ssl client and server hello.
7989 tcp-request inspect-delay 5s
7990 tcp-request content accept if clienthello
7991
7992 # no timeout on response inspect delay by default.
7993 tcp-response content accept if serverhello
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007994
Emeric Brun6a1cefa2010-09-24 18:15:17 +02007995 # SSL session ID (SSLID) may be present on a client or server hello.
7996 # Its length is coded on 1 byte at offset 43 and its value starts
7997 # at offset 44.
7998
7999 # Match and learn on request if client hello.
8000 stick on payload_lv(43,1) if clienthello
8001
8002 # Learn on response if server hello.
8003 stick store-response payload_lv(43,1) if serverhello
Cyril Bontédc4d9032012-04-08 21:57:39 +02008004
Emeric Brun6a1cefa2010-09-24 18:15:17 +02008005 server s1 192.168.1.1:443
8006 server s2 192.168.1.1:443
8007
8008 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
8009 extraction.
8010
8011
Willy Tarreau938c7fe2014-04-25 14:21:39 +02008012tcp-check connect [params*]
8013 Opens a new connection
8014 May be used in sections: defaults | frontend | listen | backend
8015 no | no | yes | yes
8016
8017 When an application lies on more than a single TCP port or when HAProxy
8018 load-balance many services in a single backend, it makes sense to probe all
8019 the services individually before considering a server as operational.
8020
8021 When there are no TCP port configured on the server line neither server port
8022 directive, then the 'tcp-check connect port <port>' must be the first step
8023 of the sequence.
8024
8025 In a tcp-check ruleset a 'connect' is required, it is also mandatory to start
8026 the ruleset with a 'connect' rule. Purpose is to ensure admin know what they
8027 do.
8028
8029 Parameters :
8030 They are optional and can be used to describe how HAProxy should open and
8031 use the TCP connection.
8032
8033 port if not set, check port or server port is used.
8034 It tells HAProxy where to open the connection to.
8035 <port> must be a valid TCP port source integer, from 1 to 65535.
8036
8037 send-proxy send a PROXY protocol string
8038
8039 ssl opens a ciphered connection
8040
8041 Examples:
8042 # check HTTP and HTTPs services on a server.
8043 # first open port 80 thanks to server line port directive, then
8044 # tcp-check opens port 443, ciphered and run a request on it:
8045 option tcp-check
8046 tcp-check connect
8047 tcp-check send GET\ /\ HTTP/1.0\r\n
8048 tcp-check send Host:\ haproxy.1wt.eu\r\n
8049 tcp-check send \r\n
8050 tcp-check expect rstring (2..|3..)
8051 tcp-check connect port 443 ssl
8052 tcp-check send GET\ /\ HTTP/1.0\r\n
8053 tcp-check send Host:\ haproxy.1wt.eu\r\n
8054 tcp-check send \r\n
8055 tcp-check expect rstring (2..|3..)
8056 server www 10.0.0.1 check port 80
8057
8058 # check both POP and IMAP from a single server:
8059 option tcp-check
8060 tcp-check connect port 110
8061 tcp-check expect string +OK\ POP3\ ready
8062 tcp-check connect port 143
8063 tcp-check expect string *\ OK\ IMAP4\ ready
8064 server mail 10.0.0.1 check
8065
8066 See also : "option tcp-check", "tcp-check send", "tcp-check expect"
8067
8068
8069tcp-check expect [!] <match> <pattern>
8070 Specify data to be collected and analysed during a generic health check
8071 May be used in sections: defaults | frontend | listen | backend
8072 no | no | yes | yes
8073
8074 Arguments :
8075 <match> is a keyword indicating how to look for a specific pattern in the
8076 response. The keyword may be one of "string", "rstring" or
8077 binary.
8078 The keyword may be preceded by an exclamation mark ("!") to negate
8079 the match. Spaces are allowed between the exclamation mark and the
8080 keyword. See below for more details on the supported keywords.
8081
8082 <pattern> is the pattern to look for. It may be a string or a regular
8083 expression. If the pattern contains spaces, they must be escaped
8084 with the usual backslash ('\').
8085 If the match is set to binary, then the pattern must be passed as
8086 a serie of hexadecimal digits in an even number. Each sequence of
8087 two digits will represent a byte. The hexadecimal digits may be
8088 used upper or lower case.
8089
8090
8091 The available matches are intentionally similar to their http-check cousins :
8092
8093 string <string> : test the exact string matches in the response buffer.
8094 A health check response will be considered valid if the
8095 response's buffer contains this exact string. If the
8096 "string" keyword is prefixed with "!", then the response
8097 will be considered invalid if the body contains this
8098 string. This can be used to look for a mandatory pattern
8099 in a protocol response, or to detect a failure when a
8100 specific error appears in a protocol banner.
8101
8102 rstring <regex> : test a regular expression on the response buffer.
8103 A health check response will be considered valid if the
8104 response's buffer matches this expression. If the
8105 "rstring" keyword is prefixed with "!", then the response
8106 will be considered invalid if the body matches the
8107 expression.
8108
8109 binary <hexstring> : test the exact string in its hexadecimal form matches
8110 in the response buffer. A health check response will
8111 be considered valid if the response's buffer contains
8112 this exact hexadecimal string.
8113 Purpose is to match data on binary protocols.
8114
8115 It is important to note that the responses will be limited to a certain size
8116 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
8117 Thus, too large responses may not contain the mandatory pattern when using
8118 "string", "rstring" or binary. If a large response is absolutely required, it
8119 is possible to change the default max size by setting the global variable.
8120 However, it is worth keeping in mind that parsing very large responses can
8121 waste some CPU cycles, especially when regular expressions are used, and that
8122 it is always better to focus the checks on smaller resources. Also, in its
8123 current state, the check will not find any string nor regex past a null
8124 character in the response. Similarly it is not possible to request matching
8125 the null character.
8126
8127 Examples :
8128 # perform a POP check
8129 option tcp-check
8130 tcp-check expect string +OK\ POP3\ ready
8131
8132 # perform an IMAP check
8133 option tcp-check
8134 tcp-check expect string *\ OK\ IMAP4\ ready
8135
8136 # look for the redis master server
8137 option tcp-check
8138 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +02008139 tcp-check expect string +PONG
Willy Tarreau938c7fe2014-04-25 14:21:39 +02008140 tcp-check send info\ replication\r\n
8141 tcp-check expect string role:master
8142 tcp-check send QUIT\r\n
8143 tcp-check expect string +OK
8144
8145
8146 See also : "option tcp-check", "tcp-check connect", "tcp-check send",
8147 "tcp-check send-binary", "http-check expect", tune.chksize
8148
8149
8150tcp-check send <data>
8151 Specify a string to be sent as a question during a generic health check
8152 May be used in sections: defaults | frontend | listen | backend
8153 no | no | yes | yes
8154
8155 <data> : the data to be sent as a question during a generic health check
8156 session. For now, <data> must be a string.
8157
8158 Examples :
8159 # look for the redis master server
8160 option tcp-check
8161 tcp-check send info\ replication\r\n
8162 tcp-check expect string role:master
8163
8164 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
8165 "tcp-check send-binary", tune.chksize
8166
8167
8168tcp-check send-binary <hexastring>
8169 Specify an hexa digits string to be sent as a binary question during a raw
8170 tcp health check
8171 May be used in sections: defaults | frontend | listen | backend
8172 no | no | yes | yes
8173
8174 <data> : the data to be sent as a question during a generic health check
8175 session. For now, <data> must be a string.
8176 <hexastring> : test the exact string in its hexadecimal form matches in the
8177 response buffer. A health check response will be considered
8178 valid if the response's buffer contains this exact
8179 hexadecimal string.
8180 Purpose is to send binary data to ask on binary protocols.
8181
8182 Examples :
8183 # redis check in binary
8184 option tcp-check
8185 tcp-check send-binary 50494e470d0a # PING\r\n
8186 tcp-check expect binary 2b504F4e47 # +PONG
8187
8188
8189 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
8190 "tcp-check send", tune.chksize
8191
8192
Willy Tarreaue9656522010-08-17 15:40:09 +02008193tcp-request connection <action> [{if | unless} <condition>]
8194 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +02008195 May be used in sections : defaults | frontend | listen | backend
8196 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +02008197 Arguments :
8198 <action> defines the action to perform if the condition applies. Valid
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02008199 actions include : "accept", "reject", "track-sc0", "track-sc1",
8200 "track-sc2", and "expect-proxy". See below for more details.
Willy Tarreau1a687942010-05-23 22:40:30 +02008201
Willy Tarreaue9656522010-08-17 15:40:09 +02008202 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008203
8204 Immediately after acceptance of a new incoming connection, it is possible to
8205 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +02008206 or dropped or have its counters tracked. Those conditions cannot make use of
8207 any data contents because the connection has not been read from yet, and the
8208 buffers are not yet allocated. This is used to selectively and very quickly
8209 accept or drop connections from various sources with a very low overhead. If
8210 some contents need to be inspected in order to take the decision, the
8211 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008212
Willy Tarreaue9656522010-08-17 15:40:09 +02008213 The "tcp-request connection" rules are evaluated in their exact declaration
8214 order. If no rule matches or if there is no rule, the default action is to
8215 accept the incoming connection. There is no specific limit to the number of
8216 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008217
Willy Tarreaua9083d02015-05-08 15:27:59 +02008218 Four types of actions are supported :
Willy Tarreaue9656522010-08-17 15:40:09 +02008219 - accept :
8220 accepts the connection if the condition is true (when used with "if")
8221 or false (when used with "unless"). The first such rule executed ends
8222 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008223
Willy Tarreaue9656522010-08-17 15:40:09 +02008224 - reject :
8225 rejects the connection if the condition is true (when used with "if")
8226 or false (when used with "unless"). The first such rule executed ends
8227 the rules evaluation. Rejected connections do not even become a
8228 session, which is why they are accounted separately for in the stats,
8229 as "denied connections". They are not considered for the session
8230 rate-limit and are not logged either. The reason is that these rules
8231 should only be used to filter extremely high connection rates such as
8232 the ones encountered during a massive DDoS attack. Under these extreme
8233 conditions, the simple action of logging each event would make the
8234 system collapse and would considerably lower the filtering capacity. If
8235 logging is absolutely desired, then "tcp-request content" rules should
8236 be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008237
Willy Tarreau4f0d9192013-06-11 20:40:55 +02008238 - expect-proxy layer4 :
8239 configures the client-facing connection to receive a PROXY protocol
8240 header before any byte is read from the socket. This is equivalent to
8241 having the "accept-proxy" keyword on the "bind" line, except that using
8242 the TCP rule allows the PROXY protocol to be accepted only for certain
8243 IP address ranges using an ACL. This is convenient when multiple layers
8244 of load balancers are passed through by traffic coming from public
8245 hosts.
8246
Willy Tarreau18bf01e2014-06-13 16:18:52 +02008247 - capture <sample> len <length> :
8248 This only applies to "tcp-request content" rules. It captures sample
8249 expression <sample> from the request buffer, and converts it to a
8250 string of at most <len> characters. The resulting string is stored into
8251 the next request "capture" slot, so it will possibly appear next to
8252 some captured HTTP headers. It will then automatically appear in the
8253 logs, and it will be possible to extract it using sample fetch rules to
8254 feed it into headers or anything. The length should be limited given
8255 that this size will be allocated for each capture during the whole
Willy Tarreaua9083d02015-05-08 15:27:59 +02008256 session life. Please check section 7.3 (Fetching samples) and "capture
8257 request header" for more information.
Willy Tarreau18bf01e2014-06-13 16:18:52 +02008258
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02008259 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] :
Willy Tarreaue9656522010-08-17 15:40:09 +02008260 enables tracking of sticky counters from current connection. These
Willy Tarreau09448f72014-06-25 18:12:15 +02008261 rules do not stop evaluation and do not change default action. 3 sets
Willy Tarreaue9656522010-08-17 15:40:09 +02008262 of counters may be simultaneously tracked by the same connection. The
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02008263 first "track-sc0" rule executed enables tracking of the counters of the
8264 specified table as the first set. The first "track-sc1" rule executed
Willy Tarreaue9656522010-08-17 15:40:09 +02008265 enables tracking of the counters of the specified table as the second
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02008266 set. The first "track-sc2" rule executed enables tracking of the
8267 counters of the specified table as the third set. It is a recommended
8268 practice to use the first set of counters for the per-frontend counters
8269 and the second set for the per-backend ones. But this is just a
8270 guideline, all may be used everywhere.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008271
Willy Tarreaue9656522010-08-17 15:40:09 +02008272 These actions take one or two arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02008273 <key> is mandatory, and is a sample expression rule as described
Willy Tarreau74ca5042013-06-11 23:12:07 +02008274 in section 7.3. It describes what elements of the incoming
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01008275 request or connection will be analysed, extracted, combined,
8276 and used to select which table entry to update the counters.
8277 Note that "tcp-request connection" cannot use content-based
8278 fetches.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008279
Willy Tarreaue9656522010-08-17 15:40:09 +02008280 <table> is an optional table to be used instead of the default one,
8281 which is the stick-table declared in the current proxy. All
8282 the counters for the matches and updates for the key will
8283 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008284
Willy Tarreaue9656522010-08-17 15:40:09 +02008285 Once a "track-sc*" rule is executed, the key is looked up in the table
8286 and if it is not found, an entry is allocated for it. Then a pointer to
8287 that entry is kept during all the session's life, and this entry's
8288 counters are updated as often as possible, every time the session's
8289 counters are updated, and also systematically when the session ends.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01008290 Counters are only updated for events that happen after the tracking has
8291 been started. For example, connection counters will not be updated when
8292 tracking layer 7 information, since the connection event happens before
8293 layer7 information is extracted.
8294
Willy Tarreaue9656522010-08-17 15:40:09 +02008295 If the entry tracks concurrent connection counters, one connection is
8296 counted for as long as the entry is tracked, and the entry will not
8297 expire during that time. Tracking counters also provides a performance
8298 advantage over just checking the keys, because only one table lookup is
8299 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008300
Willy Tarreaue9656522010-08-17 15:40:09 +02008301 Note that the "if/unless" condition is optional. If no condition is set on
8302 the action, it is simply performed unconditionally. That can be useful for
8303 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008304
Willy Tarreaue9656522010-08-17 15:40:09 +02008305 Example: accept all connections from white-listed hosts, reject too fast
8306 connection without counting them, and track accepted connections.
8307 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008308
Willy Tarreaue9656522010-08-17 15:40:09 +02008309 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008310 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02008311 tcp-request connection track-sc0 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008312
Willy Tarreaue9656522010-08-17 15:40:09 +02008313 Example: accept all connections from white-listed hosts, count all other
8314 connections and reject too fast ones. This results in abusive ones
8315 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008316
Willy Tarreaue9656522010-08-17 15:40:09 +02008317 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02008318 tcp-request connection track-sc0 src
8319 tcp-request connection reject if { sc0_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008320
Willy Tarreau4f0d9192013-06-11 20:40:55 +02008321 Example: enable the PROXY protocol for traffic coming from all known proxies.
8322
8323 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
8324
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008325 See section 7 about ACL usage.
8326
Willy Tarreaue9656522010-08-17 15:40:09 +02008327 See also : "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008328
8329
Willy Tarreaue9656522010-08-17 15:40:09 +02008330tcp-request content <action> [{if | unless} <condition>]
8331 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +02008332 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02008333 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +02008334 Arguments :
8335 <action> defines the action to perform if the condition applies. Valid
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02008336 actions include : "accept", "reject", "track-sc0", "track-sc1",
Thierry FOURNIER90da1912015-03-05 11:17:06 +01008337 "track-sc2", "capture" and "lua". See "tcp-request connection"
8338 above for their signification.
Willy Tarreau62644772008-07-16 18:36:06 +02008339
Willy Tarreaue9656522010-08-17 15:40:09 +02008340 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +02008341
Willy Tarreaue9656522010-08-17 15:40:09 +02008342 A request's contents can be analysed at an early stage of request processing
8343 called "TCP content inspection". During this stage, ACL-based rules are
8344 evaluated every time the request contents are updated, until either an
8345 "accept" or a "reject" rule matches, or the TCP request inspection delay
8346 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +02008347
Willy Tarreaue9656522010-08-17 15:40:09 +02008348 The first difference between these rules and "tcp-request connection" rules
8349 is that "tcp-request content" rules can make use of contents to take a
8350 decision. Most often, these decisions will consider a protocol recognition or
8351 validity. The second difference is that content-based rules can be used in
Willy Tarreauf3338342014-01-28 21:40:28 +01008352 both frontends and backends. In case of HTTP keep-alive with the client, all
8353 tcp-request content rules are evaluated again, so haproxy keeps a record of
8354 what sticky counters were assigned by a "tcp-request connection" versus a
8355 "tcp-request content" rule, and flushes all the content-related ones after
8356 processing an HTTP request, so that they may be evaluated again by the rules
8357 being evaluated again for the next request. This is of particular importance
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03008358 when the rule tracks some L7 information or when it is conditioned by an
Willy Tarreauf3338342014-01-28 21:40:28 +01008359 L7-based ACL, since tracking may change between requests.
Willy Tarreau62644772008-07-16 18:36:06 +02008360
Willy Tarreaue9656522010-08-17 15:40:09 +02008361 Content-based rules are evaluated in their exact declaration order. If no
8362 rule matches or if there is no rule, the default action is to accept the
8363 contents. There is no specific limit to the number of rules which may be
8364 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +02008365
Willy Tarreau18bf01e2014-06-13 16:18:52 +02008366 Four types of actions are supported :
8367 - accept : the request is accepted
8368 - reject : the request is rejected and the connection is closed
8369 - capture : the specified sample expression is captured
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02008370 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
Thierry FOURNIER69717b42015-06-04 12:23:41 +02008371 - lua <function>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02008372 - set-var(<var-name>) <expr>
Willy Tarreau62644772008-07-16 18:36:06 +02008373
Willy Tarreaue9656522010-08-17 15:40:09 +02008374 They have the same meaning as their counter-parts in "tcp-request connection"
8375 so please refer to that section for a complete description.
Willy Tarreau62644772008-07-16 18:36:06 +02008376
Willy Tarreauf3338342014-01-28 21:40:28 +01008377 While there is nothing mandatory about it, it is recommended to use the
8378 track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request
8379 content" rules in the frontend, and track-sc2 for "tcp-request content"
8380 rules in the backend, because that makes the configuration more readable
8381 and easier to troubleshoot, but this is just a guideline and all counters
8382 may be used everywhere.
Willy Tarreau62644772008-07-16 18:36:06 +02008383
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008384 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +02008385 the action, it is simply performed unconditionally. That can be useful for
8386 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +02008387
Willy Tarreaue9656522010-08-17 15:40:09 +02008388 It is perfectly possible to match layer 7 contents with "tcp-request content"
Willy Tarreauc0239e02012-04-16 14:42:55 +02008389 rules, since HTTP-specific ACL matches are able to preliminarily parse the
8390 contents of a buffer before extracting the required data. If the buffered
8391 contents do not parse as a valid HTTP message, then the ACL does not match.
8392 The parser which is involved there is exactly the same as for all other HTTP
Willy Tarreauf3338342014-01-28 21:40:28 +01008393 processing, so there is no risk of parsing something differently. In an HTTP
8394 backend connected to from an HTTP frontend, it is guaranteed that HTTP
8395 contents will always be immediately present when the rule is evaluated first.
Willy Tarreau62644772008-07-16 18:36:06 +02008396
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01008397 Tracking layer7 information is also possible provided that the information
Willy Tarreau4d54c7c2014-09-16 15:48:15 +02008398 are present when the rule is processed. The rule processing engine is able to
8399 wait until the inspect delay expires when the data to be tracked is not yet
8400 available.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01008401
Thierry FOURNIER90da1912015-03-05 11:17:06 +01008402 The "lua" keyword is followed by a Lua function name. It is used to run a Lua
8403 function if the action is executed. The single parameter is the name of the
8404 function to run. The prototype of the function is documented in the API
8405 documentation.
8406
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02008407 The "set-var" is used to set the content of a variable. The variable is
8408 declared inline.
8409
8410 <var-name> The name of the variable starts by an indication about its scope.
8411 The allowed scopes are:
8412 "sess" : the variable is shared with all the session,
8413 "txn" : the variable is shared with all the transaction
8414 (request and response)
8415 "req" : the variable is shared only during the request
8416 processing
8417 "res" : the variable is shared only during the response
8418 processing.
8419 This prefix is followed by a name. The separator is a '.'.
8420 The name may only contain characters 'a-z', 'A-Z', '0-9' and '_'.
8421
8422 <expr> Is a standard HAProxy expression formed by a sample-fetch
8423 followed by some converters.
8424
8425 Example:
8426
8427 tcp-request content set-var(sess.my_var) src
8428
Willy Tarreau62644772008-07-16 18:36:06 +02008429 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +02008430 # Accept HTTP requests containing a Host header saying "example.com"
8431 # and reject everything else.
8432 acl is_host_com hdr(Host) -i example.com
8433 tcp-request inspect-delay 30s
Willy Tarreauc0239e02012-04-16 14:42:55 +02008434 tcp-request content accept if is_host_com
Willy Tarreaue9656522010-08-17 15:40:09 +02008435 tcp-request content reject
8436
8437 Example:
Willy Tarreau62644772008-07-16 18:36:06 +02008438 # reject SMTP connection if client speaks first
8439 tcp-request inspect-delay 30s
8440 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008441 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +02008442
8443 # Forward HTTPS connection only if client speaks
8444 tcp-request inspect-delay 30s
8445 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02008446 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +02008447 tcp-request content reject
8448
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01008449 Example:
8450 # Track the last IP from X-Forwarded-For
8451 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +02008452 tcp-request content track-sc0 hdr(x-forwarded-for,-1)
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01008453
8454 Example:
8455 # track request counts per "base" (concatenation of Host+URL)
8456 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +02008457 tcp-request content track-sc0 base table req-rate
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01008458
Willy Tarreaue9656522010-08-17 15:40:09 +02008459 Example: track per-frontend and per-backend counters, block abusers at the
8460 frontend when the backend detects abuse.
8461
8462 frontend http
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02008463 # Use General Purpose Couter 0 in SC0 as a global abuse counter
Willy Tarreaue9656522010-08-17 15:40:09 +02008464 # protecting all our sites
8465 stick-table type ip size 1m expire 5m store gpc0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02008466 tcp-request connection track-sc0 src
8467 tcp-request connection reject if { sc0_get_gpc0 gt 0 }
Willy Tarreaue9656522010-08-17 15:40:09 +02008468 ...
8469 use_backend http_dynamic if { path_end .php }
8470
8471 backend http_dynamic
8472 # if a source makes too fast requests to this dynamic site (tracked
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02008473 # by SC1), block it globally in the frontend.
Willy Tarreaue9656522010-08-17 15:40:09 +02008474 stick-table type ip size 1m expire 5m store http_req_rate(10s)
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02008475 acl click_too_fast sc1_http_req_rate gt 10
8476 acl mark_as_abuser sc0_inc_gpc0 gt 0
8477 tcp-request content track-sc1 src
Willy Tarreaue9656522010-08-17 15:40:09 +02008478 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +02008479
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008480 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02008481
Willy Tarreaue9656522010-08-17 15:40:09 +02008482 See also : "tcp-request connection", "tcp-request inspect-delay"
Willy Tarreau62644772008-07-16 18:36:06 +02008483
8484
8485tcp-request inspect-delay <timeout>
8486 Set the maximum allowed time to wait for data during content inspection
8487 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02008488 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +02008489 Arguments :
8490 <timeout> is the timeout value specified in milliseconds by default, but
8491 can be in any other unit if the number is suffixed by the unit,
8492 as explained at the top of this document.
8493
8494 People using haproxy primarily as a TCP relay are often worried about the
8495 risk of passing any type of protocol to a server without any analysis. In
8496 order to be able to analyze the request contents, we must first withhold
8497 the data then analyze them. This statement simply enables withholding of
8498 data for at most the specified amount of time.
8499
Willy Tarreaufb356202010-08-03 14:02:05 +02008500 TCP content inspection applies very early when a connection reaches a
8501 frontend, then very early when the connection is forwarded to a backend. This
8502 means that a connection may experience a first delay in the frontend and a
8503 second delay in the backend if both have tcp-request rules.
8504
Willy Tarreau62644772008-07-16 18:36:06 +02008505 Note that when performing content inspection, haproxy will evaluate the whole
8506 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008507 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +02008508 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +01008509 contents are definitive. If no delay is set, haproxy will not wait at all
8510 and will immediately apply a verdict based on the available information.
8511 Obviously this is unlikely to be very useful and might even be racy, so such
8512 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +02008513
8514 As soon as a rule matches, the request is released and continues as usual. If
8515 the timeout is reached and no rule matches, the default policy will be to let
8516 it pass through unaffected.
8517
8518 For most protocols, it is enough to set it to a few seconds, as most clients
8519 send the full request immediately upon connection. Add 3 or more seconds to
8520 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +01008521 to use large values, for instance to ensure that the client never talks
Willy Tarreau62644772008-07-16 18:36:06 +02008522 before the server (eg: SMTP), or to wait for a client to talk before passing
8523 data to the server (eg: SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +02008524 least the inspection delay, otherwise it will expire first. If the client
8525 closes the connection or if the buffer is full, the delay immediately expires
8526 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +02008527
Willy Tarreau55165fe2009-05-10 12:02:55 +02008528 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +02008529 "timeout client".
8530
8531
Emeric Brun0a3b67f2010-09-24 15:34:53 +02008532tcp-response content <action> [{if | unless} <condition>]
8533 Perform an action on a session response depending on a layer 4-7 condition
8534 May be used in sections : defaults | frontend | listen | backend
8535 no | no | yes | yes
8536 Arguments :
8537 <action> defines the action to perform if the condition applies. Valid
Thierry FOURNIER90da1912015-03-05 11:17:06 +01008538 actions include : "accept", "close", "reject", "lua".
Emeric Brun0a3b67f2010-09-24 15:34:53 +02008539
8540 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
8541
8542 Response contents can be analysed at an early stage of response processing
8543 called "TCP content inspection". During this stage, ACL-based rules are
8544 evaluated every time the response contents are updated, until either an
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02008545 "accept", "close" or a "reject" rule matches, or a TCP response inspection
8546 delay is set and expires with no matching rule.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02008547
8548 Most often, these decisions will consider a protocol recognition or validity.
8549
8550 Content-based rules are evaluated in their exact declaration order. If no
8551 rule matches or if there is no rule, the default action is to accept the
8552 contents. There is no specific limit to the number of rules which may be
8553 inserted.
8554
8555 Two types of actions are supported :
8556 - accept :
8557 accepts the response if the condition is true (when used with "if")
8558 or false (when used with "unless"). The first such rule executed ends
8559 the rules evaluation.
8560
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02008561 - close :
8562 immediately closes the connection with the server if the condition is
8563 true (when used with "if"), or false (when used with "unless"). The
8564 first such rule executed ends the rules evaluation. The main purpose of
8565 this action is to force a connection to be finished between a client
8566 and a server after an exchange when the application protocol expects
8567 some long time outs to elapse first. The goal is to eliminate idle
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03008568 connections which take significant resources on servers with certain
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02008569 protocols.
8570
Emeric Brun0a3b67f2010-09-24 15:34:53 +02008571 - reject :
8572 rejects the response if the condition is true (when used with "if")
8573 or false (when used with "unless"). The first such rule executed ends
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008574 the rules evaluation. Rejected session are immediately closed.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02008575
Thierry FOURNIER69717b42015-06-04 12:23:41 +02008576 - lua <function>
8577 Executes Lua.
8578
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02008579 - set-var(<var-name>) <expr>
8580 Sets a variable.
8581
Emeric Brun0a3b67f2010-09-24 15:34:53 +02008582 Note that the "if/unless" condition is optional. If no condition is set on
8583 the action, it is simply performed unconditionally. That can be useful for
8584 for changing the default action to a reject.
8585
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008586 It is perfectly possible to match layer 7 contents with "tcp-response
8587 content" rules, but then it is important to ensure that a full response has
8588 been buffered, otherwise no contents will match. In order to achieve this,
8589 the best solution involves detecting the HTTP protocol during the inspection
Emeric Brun0a3b67f2010-09-24 15:34:53 +02008590 period.
8591
Thierry FOURNIER90da1912015-03-05 11:17:06 +01008592 The "lua" keyword is followed by a Lua function name. It is used to run a Lua
8593 function if the action is executed. The single parameter is the name of the
8594 function to run. The prototype of the function is documented in the API
8595 documentation.
8596
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02008597 The "set-var" is used to set the content of a variable. The variable is
8598 declared inline.
8599
8600 <var-name> The name of the variable starts by an indication about its scope.
8601 The allowed scopes are:
8602 "sess" : the variable is shared with all the session,
8603 "txn" : the variable is shared with all the transaction
8604 (request and response)
8605 "req" : the variable is shared only during the request
8606 processing
8607 "res" : the variable is shared only during the response
8608 processing.
8609 This prefix is followed by a name. The separator is a '.'.
8610 The name may only contain characters 'a-z', 'A-Z', '0-9' and '_'.
8611
8612 <expr> Is a standard HAProxy expression formed by a sample-fetch
8613 followed by some converters.
8614
8615 Example:
8616
8617 tcp-request content set-var(sess.my_var) src
8618
Emeric Brun0a3b67f2010-09-24 15:34:53 +02008619 See section 7 about ACL usage.
8620
8621 See also : "tcp-request content", "tcp-response inspect-delay"
8622
8623
8624tcp-response inspect-delay <timeout>
8625 Set the maximum allowed time to wait for a response during content inspection
8626 May be used in sections : defaults | frontend | listen | backend
8627 no | no | yes | yes
8628 Arguments :
8629 <timeout> is the timeout value specified in milliseconds by default, but
8630 can be in any other unit if the number is suffixed by the unit,
8631 as explained at the top of this document.
8632
8633 See also : "tcp-response content", "tcp-request inspect-delay".
8634
8635
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01008636timeout check <timeout>
8637 Set additional check timeout, but only after a connection has been already
8638 established.
8639
8640 May be used in sections: defaults | frontend | listen | backend
8641 yes | no | yes | yes
8642 Arguments:
8643 <timeout> is the timeout value specified in milliseconds by default, but
8644 can be in any other unit if the number is suffixed by the unit,
8645 as explained at the top of this document.
8646
8647 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
8648 for check and "timeout check" as an additional read timeout. The "min" is
8649 used so that people running with *very* long "timeout connect" (eg. those
8650 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +01008651 (Please also note that there is no valid reason to have such long connect
8652 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
8653 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01008654
8655 If "timeout check" is not set haproxy uses "inter" for complete check
8656 timeout (connect + read) exactly like all <1.3.15 version.
8657
8658 In most cases check request is much simpler and faster to handle than normal
8659 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +01008660 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01008661
8662 This parameter is specific to backends, but can be specified once for all in
8663 "defaults" sections. This is in fact one of the easiest solutions not to
8664 forget about it.
8665
Willy Tarreau41a340d2008-01-22 12:25:31 +01008666 See also: "timeout connect", "timeout queue", "timeout server",
8667 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01008668
8669
Willy Tarreau0ba27502007-12-24 16:55:16 +01008670timeout client <timeout>
8671timeout clitimeout <timeout> (deprecated)
8672 Set the maximum inactivity time on the client side.
8673 May be used in sections : defaults | frontend | listen | backend
8674 yes | yes | yes | no
8675 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01008676 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01008677 can be in any other unit if the number is suffixed by the unit,
8678 as explained at the top of this document.
8679
8680 The inactivity timeout applies when the client is expected to acknowledge or
8681 send data. In HTTP mode, this timeout is particularly important to consider
8682 during the first phase, when the client sends the request, and during the
8683 response while it is reading data sent by the server. The value is specified
8684 in milliseconds by default, but can be in any other unit if the number is
8685 suffixed by the unit, as specified at the top of this document. In TCP mode
8686 (and to a lesser extent, in HTTP mode), it is highly recommended that the
8687 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01008688 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01008689 losses by specifying timeouts that are slightly above multiples of 3 seconds
Willy Tarreauce887fd2012-05-12 12:50:00 +02008690 (eg: 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
8691 sessions (eg: WebSocket and HTTP), it's worth considering "timeout tunnel",
Willy Tarreau05cdd962014-05-10 14:30:07 +02008692 which overrides "timeout client" and "timeout server" for tunnels, as well as
8693 "timeout client-fin" for half-closed connections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01008694
8695 This parameter is specific to frontends, but can be specified once for all in
8696 "defaults" sections. This is in fact one of the easiest solutions not to
8697 forget about it. An unspecified timeout results in an infinite timeout, which
8698 is not recommended. Such a usage is accepted and works but reports a warning
8699 during startup because it may results in accumulation of expired sessions in
8700 the system if the system's timeouts are not configured either.
8701
8702 This parameter replaces the old, deprecated "clitimeout". It is recommended
8703 to use it to write new configurations. The form "timeout clitimeout" is
8704 provided only by backwards compatibility but its use is strongly discouraged.
8705
Willy Tarreauce887fd2012-05-12 12:50:00 +02008706 See also : "clitimeout", "timeout server", "timeout tunnel".
Willy Tarreau0ba27502007-12-24 16:55:16 +01008707
8708
Willy Tarreau05cdd962014-05-10 14:30:07 +02008709timeout client-fin <timeout>
8710 Set the inactivity timeout on the client side for half-closed connections.
8711 May be used in sections : defaults | frontend | listen | backend
8712 yes | yes | yes | no
8713 Arguments :
8714 <timeout> is the timeout value specified in milliseconds by default, but
8715 can be in any other unit if the number is suffixed by the unit,
8716 as explained at the top of this document.
8717
8718 The inactivity timeout applies when the client is expected to acknowledge or
8719 send data while one direction is already shut down. This timeout is different
8720 from "timeout client" in that it only applies to connections which are closed
8721 in one direction. This is particularly useful to avoid keeping connections in
8722 FIN_WAIT state for too long when clients do not disconnect cleanly. This
8723 problem is particularly common long connections such as RDP or WebSocket.
8724 Note that this timeout can override "timeout tunnel" when a connection shuts
8725 down in one direction.
8726
8727 This parameter is specific to frontends, but can be specified once for all in
8728 "defaults" sections. By default it is not set, so half-closed connections
8729 will use the other timeouts (timeout.client or timeout.tunnel).
8730
8731 See also : "timeout client", "timeout server-fin", and "timeout tunnel".
8732
8733
Willy Tarreau0ba27502007-12-24 16:55:16 +01008734timeout connect <timeout>
8735timeout contimeout <timeout> (deprecated)
8736 Set the maximum time to wait for a connection attempt to a server to succeed.
8737 May be used in sections : defaults | frontend | listen | backend
8738 yes | no | yes | yes
8739 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01008740 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01008741 can be in any other unit if the number is suffixed by the unit,
8742 as explained at the top of this document.
8743
8744 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01008745 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01008746 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01008747 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01008748 connect timeout also presets both queue and tarpit timeouts to the same value
8749 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +01008750
8751 This parameter is specific to backends, but can be specified once for all in
8752 "defaults" sections. This is in fact one of the easiest solutions not to
8753 forget about it. An unspecified timeout results in an infinite timeout, which
8754 is not recommended. Such a usage is accepted and works but reports a warning
8755 during startup because it may results in accumulation of failed sessions in
8756 the system if the system's timeouts are not configured either.
8757
8758 This parameter replaces the old, deprecated "contimeout". It is recommended
8759 to use it to write new configurations. The form "timeout contimeout" is
8760 provided only by backwards compatibility but its use is strongly discouraged.
8761
Willy Tarreau41a340d2008-01-22 12:25:31 +01008762 See also: "timeout check", "timeout queue", "timeout server", "contimeout",
8763 "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +01008764
8765
Willy Tarreaub16a5742010-01-10 14:46:16 +01008766timeout http-keep-alive <timeout>
8767 Set the maximum allowed time to wait for a new HTTP request to appear
8768 May be used in sections : defaults | frontend | listen | backend
8769 yes | yes | yes | yes
8770 Arguments :
8771 <timeout> is the timeout value specified in milliseconds by default, but
8772 can be in any other unit if the number is suffixed by the unit,
8773 as explained at the top of this document.
8774
8775 By default, the time to wait for a new request in case of keep-alive is set
8776 by "timeout http-request". However this is not always convenient because some
8777 people want very short keep-alive timeouts in order to release connections
8778 faster, and others prefer to have larger ones but still have short timeouts
8779 once the request has started to present itself.
8780
8781 The "http-keep-alive" timeout covers these needs. It will define how long to
8782 wait for a new HTTP request to start coming after a response was sent. Once
8783 the first byte of request has been seen, the "http-request" timeout is used
8784 to wait for the complete request to come. Note that empty lines prior to a
8785 new request do not refresh the timeout and are not counted as a new request.
8786
8787 There is also another difference between the two timeouts : when a connection
8788 expires during timeout http-keep-alive, no error is returned, the connection
8789 just closes. If the connection expires in "http-request" while waiting for a
8790 connection to complete, a HTTP 408 error is returned.
8791
8792 In general it is optimal to set this value to a few tens to hundreds of
8793 milliseconds, to allow users to fetch all objects of a page at once but
8794 without waiting for further clicks. Also, if set to a very small value (eg:
8795 1 millisecond) it will probably only accept pipelined requests but not the
8796 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +02008797 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +01008798
8799 If this parameter is not set, the "http-request" timeout applies, and if both
8800 are not set, "timeout client" still applies at the lower level. It should be
8801 set in the frontend to take effect, unless the frontend is in TCP mode, in
8802 which case the HTTP backend's timeout will be used.
8803
8804 See also : "timeout http-request", "timeout client".
8805
8806
Willy Tarreau036fae02008-01-06 13:24:40 +01008807timeout http-request <timeout>
8808 Set the maximum allowed time to wait for a complete HTTP request
8809 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +02008810 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +01008811 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01008812 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +01008813 can be in any other unit if the number is suffixed by the unit,
8814 as explained at the top of this document.
8815
8816 In order to offer DoS protection, it may be required to lower the maximum
8817 accepted time to receive a complete HTTP request without affecting the client
8818 timeout. This helps protecting against established connections on which
8819 nothing is sent. The client timeout cannot offer a good protection against
8820 this abuse because it is an inactivity timeout, which means that if the
8821 attacker sends one character every now and then, the timeout will not
8822 trigger. With the HTTP request timeout, no matter what speed the client
Willy Tarreau2705a612014-05-23 17:38:34 +02008823 types, the request will be aborted if it does not complete in time. When the
8824 timeout expires, an HTTP 408 response is sent to the client to inform it
8825 about the problem, and the connection is closed. The logs will report
8826 termination codes "cR". Some recent browsers are having problems with this
8827 standard, well-documented behaviour, so it might be needed to hide the 408
Willy Tarreau0f228a02015-05-01 15:37:53 +02008828 code using "option http-ignore-probes" or "errorfile 408 /dev/null". See
8829 more details in the explanations of the "cR" termination code in section 8.5.
Willy Tarreau036fae02008-01-06 13:24:40 +01008830
8831 Note that this timeout only applies to the header part of the request, and
8832 not to any data. As soon as the empty line is received, this timeout is not
Willy Tarreaub16a5742010-01-10 14:46:16 +01008833 used anymore. It is used again on keep-alive connections to wait for a second
8834 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +01008835
8836 Generally it is enough to set it to a few seconds, as most clients send the
8837 full request immediately upon connection. Add 3 or more seconds to cover TCP
8838 retransmits but that's all. Setting it to very low values (eg: 50 ms) will
8839 generally work on local networks as long as there are no packet losses. This
8840 will prevent people from sending bare HTTP requests using telnet.
8841
8842 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +02008843 chunk of the incoming request. It should be set in the frontend to take
8844 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
8845 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +01008846
Willy Tarreau0f228a02015-05-01 15:37:53 +02008847 See also : "errorfile", "http-ignore-probes", "timeout http-keep-alive", and
8848 "timeout client".
Willy Tarreau036fae02008-01-06 13:24:40 +01008849
Willy Tarreau844e3c52008-01-11 16:28:18 +01008850
8851timeout queue <timeout>
8852 Set the maximum time to wait in the queue for a connection slot to be free
8853 May be used in sections : defaults | frontend | listen | backend
8854 yes | no | yes | yes
8855 Arguments :
8856 <timeout> is the timeout value specified in milliseconds by default, but
8857 can be in any other unit if the number is suffixed by the unit,
8858 as explained at the top of this document.
8859
8860 When a server's maxconn is reached, connections are left pending in a queue
8861 which may be server-specific or global to the backend. In order not to wait
8862 indefinitely, a timeout is applied to requests pending in the queue. If the
8863 timeout is reached, it is considered that the request will almost never be
8864 served, so it is dropped and a 503 error is returned to the client.
8865
8866 The "timeout queue" statement allows to fix the maximum time for a request to
8867 be left pending in a queue. If unspecified, the same value as the backend's
8868 connection timeout ("timeout connect") is used, for backwards compatibility
8869 with older versions with no "timeout queue" parameter.
8870
8871 See also : "timeout connect", "contimeout".
8872
8873
8874timeout server <timeout>
8875timeout srvtimeout <timeout> (deprecated)
8876 Set the maximum inactivity time on the server side.
8877 May be used in sections : defaults | frontend | listen | backend
8878 yes | no | yes | yes
8879 Arguments :
8880 <timeout> is the timeout value specified in milliseconds by default, but
8881 can be in any other unit if the number is suffixed by the unit,
8882 as explained at the top of this document.
8883
8884 The inactivity timeout applies when the server is expected to acknowledge or
8885 send data. In HTTP mode, this timeout is particularly important to consider
8886 during the first phase of the server's response, when it has to send the
8887 headers, as it directly represents the server's processing time for the
8888 request. To find out what value to put there, it's often good to start with
8889 what would be considered as unacceptable response times, then check the logs
8890 to observe the response time distribution, and adjust the value accordingly.
8891
8892 The value is specified in milliseconds by default, but can be in any other
8893 unit if the number is suffixed by the unit, as specified at the top of this
8894 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
8895 recommended that the client timeout remains equal to the server timeout in
8896 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01008897 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01008898 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreauce887fd2012-05-12 12:50:00 +02008899 seconds (eg: 4 or 5 seconds minimum). If some long-lived sessions are mixed
8900 with short-lived sessions (eg: WebSocket and HTTP), it's worth considering
8901 "timeout tunnel", which overrides "timeout client" and "timeout server" for
8902 tunnels.
Willy Tarreau844e3c52008-01-11 16:28:18 +01008903
8904 This parameter is specific to backends, but can be specified once for all in
8905 "defaults" sections. This is in fact one of the easiest solutions not to
8906 forget about it. An unspecified timeout results in an infinite timeout, which
8907 is not recommended. Such a usage is accepted and works but reports a warning
8908 during startup because it may results in accumulation of expired sessions in
8909 the system if the system's timeouts are not configured either.
8910
8911 This parameter replaces the old, deprecated "srvtimeout". It is recommended
8912 to use it to write new configurations. The form "timeout srvtimeout" is
8913 provided only by backwards compatibility but its use is strongly discouraged.
8914
Willy Tarreauce887fd2012-05-12 12:50:00 +02008915 See also : "srvtimeout", "timeout client" and "timeout tunnel".
Willy Tarreau844e3c52008-01-11 16:28:18 +01008916
Willy Tarreau05cdd962014-05-10 14:30:07 +02008917
8918timeout server-fin <timeout>
8919 Set the inactivity timeout on the server side for half-closed connections.
8920 May be used in sections : defaults | frontend | listen | backend
8921 yes | no | yes | yes
8922 Arguments :
8923 <timeout> is the timeout value specified in milliseconds by default, but
8924 can be in any other unit if the number is suffixed by the unit,
8925 as explained at the top of this document.
8926
8927 The inactivity timeout applies when the server is expected to acknowledge or
8928 send data while one direction is already shut down. This timeout is different
8929 from "timeout server" in that it only applies to connections which are closed
8930 in one direction. This is particularly useful to avoid keeping connections in
8931 FIN_WAIT state for too long when a remote server does not disconnect cleanly.
8932 This problem is particularly common long connections such as RDP or WebSocket.
8933 Note that this timeout can override "timeout tunnel" when a connection shuts
8934 down in one direction. This setting was provided for completeness, but in most
8935 situations, it should not be needed.
8936
8937 This parameter is specific to backends, but can be specified once for all in
8938 "defaults" sections. By default it is not set, so half-closed connections
8939 will use the other timeouts (timeout.server or timeout.tunnel).
8940
8941 See also : "timeout client-fin", "timeout server", and "timeout tunnel".
8942
Willy Tarreau844e3c52008-01-11 16:28:18 +01008943
8944timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +01008945 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +01008946 May be used in sections : defaults | frontend | listen | backend
8947 yes | yes | yes | yes
8948 Arguments :
8949 <timeout> is the tarpit duration specified in milliseconds by default, but
8950 can be in any other unit if the number is suffixed by the unit,
8951 as explained at the top of this document.
8952
8953 When a connection is tarpitted using "reqtarpit", it is maintained open with
8954 no activity for a certain amount of time, then closed. "timeout tarpit"
8955 defines how long it will be maintained open.
8956
8957 The value is specified in milliseconds by default, but can be in any other
8958 unit if the number is suffixed by the unit, as specified at the top of this
8959 document. If unspecified, the same value as the backend's connection timeout
8960 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +01008961 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +01008962
8963 See also : "timeout connect", "contimeout".
8964
8965
Willy Tarreauce887fd2012-05-12 12:50:00 +02008966timeout tunnel <timeout>
8967 Set the maximum inactivity time on the client and server side for tunnels.
8968 May be used in sections : defaults | frontend | listen | backend
8969 yes | no | yes | yes
8970 Arguments :
8971 <timeout> is the timeout value specified in milliseconds by default, but
8972 can be in any other unit if the number is suffixed by the unit,
8973 as explained at the top of this document.
8974
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008975 The tunnel timeout applies when a bidirectional connection is established
Willy Tarreauce887fd2012-05-12 12:50:00 +02008976 between a client and a server, and the connection remains inactive in both
8977 directions. This timeout supersedes both the client and server timeouts once
8978 the connection becomes a tunnel. In TCP, this timeout is used as soon as no
8979 analyser remains attached to either connection (eg: tcp content rules are
8980 accepted). In HTTP, this timeout is used when a connection is upgraded (eg:
8981 when switching to the WebSocket protocol, or forwarding a CONNECT request
8982 to a proxy), or after the first response when no keepalive/close option is
8983 specified.
8984
Willy Tarreau05cdd962014-05-10 14:30:07 +02008985 Since this timeout is usually used in conjunction with long-lived connections,
8986 it usually is a good idea to also set "timeout client-fin" to handle the
8987 situation where a client suddenly disappears from the net and does not
8988 acknowledge a close, or sends a shutdown and does not acknowledge pending
8989 data anymore. This can happen in lossy networks where firewalls are present,
8990 and is detected by the presence of large amounts of sessions in a FIN_WAIT
8991 state.
8992
Willy Tarreauce887fd2012-05-12 12:50:00 +02008993 The value is specified in milliseconds by default, but can be in any other
8994 unit if the number is suffixed by the unit, as specified at the top of this
8995 document. Whatever the expected normal idle time, it is a good practice to
8996 cover at least one or several TCP packet losses by specifying timeouts that
8997 are slightly above multiples of 3 seconds (eg: 4 or 5 seconds minimum).
8998
8999 This parameter is specific to backends, but can be specified once for all in
9000 "defaults" sections. This is in fact one of the easiest solutions not to
9001 forget about it.
9002
9003 Example :
9004 defaults http
9005 option http-server-close
9006 timeout connect 5s
9007 timeout client 30s
Willy Tarreau05cdd962014-05-10 14:30:07 +02009008 timeout client-fin 30s
Willy Tarreauce887fd2012-05-12 12:50:00 +02009009 timeout server 30s
9010 timeout tunnel 1h # timeout to use with WebSocket and CONNECT
9011
Willy Tarreau05cdd962014-05-10 14:30:07 +02009012 See also : "timeout client", "timeout client-fin", "timeout server".
Willy Tarreauce887fd2012-05-12 12:50:00 +02009013
9014
Willy Tarreau844e3c52008-01-11 16:28:18 +01009015transparent (deprecated)
9016 Enable client-side transparent proxying
9017 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01009018 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01009019 Arguments : none
9020
9021 This keyword was introduced in order to provide layer 7 persistence to layer
9022 3 load balancers. The idea is to use the OS's ability to redirect an incoming
9023 connection for a remote address to a local process (here HAProxy), and let
9024 this process know what address was initially requested. When this option is
9025 used, sessions without cookies will be forwarded to the original destination
9026 IP address of the incoming request (which should match that of another
9027 equipment), while requests with cookies will still be forwarded to the
9028 appropriate server.
9029
9030 The "transparent" keyword is deprecated, use "option transparent" instead.
9031
9032 Note that contrary to a common belief, this option does NOT make HAProxy
9033 present the client's IP to the server when establishing the connection.
9034
Willy Tarreau844e3c52008-01-11 16:28:18 +01009035 See also: "option transparent"
9036
William Lallemanda73203e2012-03-12 12:48:57 +01009037unique-id-format <string>
9038 Generate a unique ID for each request.
9039 May be used in sections : defaults | frontend | listen | backend
9040 yes | yes | yes | no
9041 Arguments :
9042 <string> is a log-format string.
9043
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009044 This keyword creates a ID for each request using the custom log format. A
9045 unique ID is useful to trace a request passing through many components of
9046 a complex infrastructure. The newly created ID may also be logged using the
9047 %ID tag the log-format string.
William Lallemanda73203e2012-03-12 12:48:57 +01009048
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009049 The format should be composed from elements that are guaranteed to be
9050 unique when combined together. For instance, if multiple haproxy instances
9051 are involved, it might be important to include the node name. It is often
9052 needed to log the incoming connection's source and destination addresses
9053 and ports. Note that since multiple requests may be performed over the same
9054 connection, including a request counter may help differentiate them.
9055 Similarly, a timestamp may protect against a rollover of the counter.
9056 Logging the process ID will avoid collisions after a service restart.
William Lallemanda73203e2012-03-12 12:48:57 +01009057
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009058 It is recommended to use hexadecimal notation for many fields since it
9059 makes them more compact and saves space in logs.
William Lallemanda73203e2012-03-12 12:48:57 +01009060
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009061 Example:
William Lallemanda73203e2012-03-12 12:48:57 +01009062
Julien Vehentf21be322014-03-07 08:27:34 -05009063 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +01009064
9065 will generate:
9066
9067 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
9068
9069 See also: "unique-id-header"
9070
9071unique-id-header <name>
9072 Add a unique ID header in the HTTP request.
9073 May be used in sections : defaults | frontend | listen | backend
9074 yes | yes | yes | no
9075 Arguments :
9076 <name> is the name of the header.
9077
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009078 Add a unique-id header in the HTTP request sent to the server, using the
9079 unique-id-format. It can't work if the unique-id-format doesn't exist.
William Lallemanda73203e2012-03-12 12:48:57 +01009080
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009081 Example:
William Lallemanda73203e2012-03-12 12:48:57 +01009082
Julien Vehentf21be322014-03-07 08:27:34 -05009083 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +01009084 unique-id-header X-Unique-ID
9085
9086 will generate:
9087
9088 X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
9089
9090 See also: "unique-id-format"
Willy Tarreau844e3c52008-01-11 16:28:18 +01009091
Willy Tarreauf51658d2014-04-23 01:21:56 +02009092use_backend <backend> [{if | unless} <condition>]
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02009093 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +01009094 May be used in sections : defaults | frontend | listen | backend
9095 no | yes | yes | no
9096 Arguments :
Bertrand Jacquin702d44f2013-11-19 11:43:06 +01009097 <backend> is the name of a valid backend or "listen" section, or a
9098 "log-format" string resolving to a backend name.
Willy Tarreau844e3c52008-01-11 16:28:18 +01009099
Willy Tarreauf51658d2014-04-23 01:21:56 +02009100 <condition> is a condition composed of ACLs, as described in section 7. If
9101 it is omitted, the rule is unconditionally applied.
Willy Tarreau844e3c52008-01-11 16:28:18 +01009102
9103 When doing content-switching, connections arrive on a frontend and are then
9104 dispatched to various backends depending on a number of conditions. The
9105 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02009106 "use_backend" keyword. While it is normally used with HTTP processing, it can
9107 also be used in pure TCP, either without content using stateless ACLs (eg:
9108 source address validation) or combined with a "tcp-request" rule to wait for
9109 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +01009110
9111 There may be as many "use_backend" rules as desired. All of these rules are
9112 evaluated in their declaration order, and the first one which matches will
9113 assign the backend.
9114
9115 In the first form, the backend will be used if the condition is met. In the
9116 second form, the backend will be used if the condition is not met. If no
9117 condition is valid, the backend defined with "default_backend" will be used.
9118 If no default backend is defined, either the servers in the same section are
9119 used (in case of a "listen" section) or, in case of a frontend, no server is
9120 used and a 503 service unavailable response is returned.
9121
Willy Tarreau51aecc72009-07-12 09:47:04 +02009122 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009123 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +02009124 and backend processing will immediately follow, or the backend will wait for
9125 a complete HTTP request to get in. This feature is useful when a frontend
9126 must decode several protocols on a unique port, one of them being HTTP.
9127
Bertrand Jacquin702d44f2013-11-19 11:43:06 +01009128 When <backend> is a simple name, it is resolved at configuration time, and an
9129 error is reported if the specified backend does not exist. If <backend> is
9130 a log-format string instead, no check may be done at configuration time, so
9131 the backend name is resolved dynamically at run time. If the resulting
9132 backend name does not correspond to any valid backend, no other rule is
9133 evaluated, and the default_backend directive is applied instead. Note that
9134 when using dynamic backend names, it is highly recommended to use a prefix
9135 that no other backend uses in order to ensure that an unauthorized backend
9136 cannot be forced from the request.
9137
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009138 It is worth mentioning that "use_backend" rules with an explicit name are
Bertrand Jacquin702d44f2013-11-19 11:43:06 +01009139 used to detect the association between frontends and backends to compute the
9140 backend's "fullconn" setting. This cannot be done for dynamic names.
9141
9142 See also: "default_backend", "tcp-request", "fullconn", "log-format", and
9143 section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +01009144
Willy Tarreau036fae02008-01-06 13:24:40 +01009145
Willy Tarreau4a5cade2012-04-05 21:09:48 +02009146use-server <server> if <condition>
9147use-server <server> unless <condition>
9148 Only use a specific server if/unless an ACL-based condition is matched.
9149 May be used in sections : defaults | frontend | listen | backend
9150 no | no | yes | yes
9151 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009152 <server> is the name of a valid server in the same backend section.
Willy Tarreau4a5cade2012-04-05 21:09:48 +02009153
9154 <condition> is a condition composed of ACLs, as described in section 7.
9155
9156 By default, connections which arrive to a backend are load-balanced across
9157 the available servers according to the configured algorithm, unless a
9158 persistence mechanism such as a cookie is used and found in the request.
9159
9160 Sometimes it is desirable to forward a particular request to a specific
9161 server without having to declare a dedicated backend for this server. This
9162 can be achieved using the "use-server" rules. These rules are evaluated after
9163 the "redirect" rules and before evaluating cookies, and they have precedence
9164 on them. There may be as many "use-server" rules as desired. All of these
9165 rules are evaluated in their declaration order, and the first one which
9166 matches will assign the server.
9167
9168 If a rule designates a server which is down, and "option persist" is not used
9169 and no force-persist rule was validated, it is ignored and evaluation goes on
9170 with the next rules until one matches.
9171
9172 In the first form, the server will be used if the condition is met. In the
9173 second form, the server will be used if the condition is not met. If no
9174 condition is valid, the processing continues and the server will be assigned
9175 according to other persistence mechanisms.
9176
9177 Note that even if a rule is matched, cookie processing is still performed but
9178 does not assign the server. This allows prefixed cookies to have their prefix
9179 stripped.
9180
9181 The "use-server" statement works both in HTTP and TCP mode. This makes it
9182 suitable for use with content-based inspection. For instance, a server could
9183 be selected in a farm according to the TLS SNI field. And if these servers
9184 have their weight set to zero, they will not be used for other traffic.
9185
9186 Example :
9187 # intercept incoming TLS requests based on the SNI field
9188 use-server www if { req_ssl_sni -i www.example.com }
9189 server www 192.168.0.1:443 weight 0
9190 use-server mail if { req_ssl_sni -i mail.example.com }
9191 server mail 192.168.0.1:587 weight 0
9192 use-server imap if { req_ssl_sni -i imap.example.com }
9193 server mail 192.168.0.1:993 weight 0
9194 # all the rest is forwarded to this server
9195 server default 192.168.0.2:443 check
9196
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009197 See also: "use_backend", section 5 about server and section 7 about ACLs.
Willy Tarreau4a5cade2012-04-05 21:09:48 +02009198
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009199
92005. Bind and Server options
9201--------------------------
9202
9203The "bind", "server" and "default-server" keywords support a number of settings
9204depending on some build options and on the system HAProxy was built on. These
9205settings generally each consist in one word sometimes followed by a value,
9206written on the same line as the "bind" or "server" line. All these options are
9207described in this section.
9208
9209
92105.1. Bind options
9211-----------------
9212
9213The "bind" keyword supports a certain number of settings which are all passed
9214as arguments on the same line. The order in which those arguments appear makes
9215no importance, provided that they appear after the bind address. All of these
9216parameters are optional. Some of them consist in a single words (booleans),
9217while other ones expect a value after them. In this case, the value must be
9218provided immediately after the setting name.
9219
9220The currently supported settings are the following ones.
9221
9222accept-proxy
9223 Enforces the use of the PROXY protocol over any connection accepted by any of
Willy Tarreau77992672014-06-14 11:06:17 +02009224 the sockets declared on the same line. Versions 1 and 2 of the PROXY protocol
9225 are supported and correctly detected. The PROXY protocol dictates the layer
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009226 3/4 addresses of the incoming connection to be used everywhere an address is
9227 used, with the only exception of "tcp-request connection" rules which will
9228 only see the real connection address. Logs will reflect the addresses
9229 indicated in the protocol, unless it is violated, in which case the real
9230 address will still be used. This keyword combined with support from external
9231 components can be used as an efficient and reliable alternative to the
9232 X-Forwarded-For mechanism which is not always reliable and not even always
Willy Tarreau4f0d9192013-06-11 20:40:55 +02009233 usable. See also "tcp-request connection expect-proxy" for a finer-grained
9234 setting of which client is allowed to use the protocol.
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009235
Willy Tarreauab861d32013-04-02 02:30:41 +02009236alpn <protocols>
9237 This enables the TLS ALPN extension and advertises the specified protocol
9238 list as supported on top of ALPN. The protocol list consists in a comma-
9239 delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
9240 quotes). This requires that the SSL library is build with support for TLS
9241 extensions enabled (check with haproxy -vv). The ALPN extension replaces the
9242 initial NPN extension.
9243
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009244backlog <backlog>
9245 Sets the socket's backlog to this value. If unspecified, the frontend's
9246 backlog is used instead, which generally defaults to the maxconn value.
9247
Emeric Brun7fb34422012-09-28 15:26:15 +02009248ecdhe <named curve>
9249 This setting is only available when support for OpenSSL was built in. It sets
Emeric Brun6924ef82013-03-06 14:08:53 +01009250 the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default,
9251 used named curve is prime256v1.
Emeric Brun7fb34422012-09-28 15:26:15 +02009252
Emeric Brunfd33a262012-10-11 16:28:27 +02009253ca-file <cafile>
Emeric Brun1a073b42012-09-28 17:07:34 +02009254 This setting is only available when support for OpenSSL was built in. It
9255 designates a PEM file from which to load CA certificates used to verify
9256 client's certificate.
9257
Emeric Brunb6dc9342012-09-28 17:55:37 +02009258ca-ignore-err [all|<errorID>,...]
9259 This setting is only available when support for OpenSSL was built in.
9260 Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
9261 If set to 'all', all errors are ignored. SSL handshake is not aborted if an
9262 error is ignored.
9263
Christopher Faulet31af49d2015-06-09 17:29:50 +02009264ca-sign-file <cafile>
9265 This setting is only available when support for OpenSSL was built in. It
9266 designates a PEM file containing both the CA certificate and the CA private
9267 key used to create and sign server's certificates. This is a mandatory
9268 setting when the dynamic generation of certificates is enabled. See
9269 'generate-certificates' for details.
9270
9271ca-sign-passphrase <passphrase>
9272 This setting is only available when support for OpenSSL was built in. It is
9273 the CA private key passphrase. This setting is optional and used only when
9274 the dynamic generation of certificates is enabled. See
9275 'generate-certificates' for details.
9276
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009277ciphers <ciphers>
9278 This setting is only available when support for OpenSSL was built in. It sets
9279 the string describing the list of cipher algorithms ("cipher suite") that are
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009280 negotiated during the SSL/TLS handshake. The format of the string is defined
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009281 in "man 1 ciphers" from OpenSSL man pages, and can be for instance a string
9282 such as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes).
9283
Emeric Brunfd33a262012-10-11 16:28:27 +02009284crl-file <crlfile>
Emeric Brun1a073b42012-09-28 17:07:34 +02009285 This setting is only available when support for OpenSSL was built in. It
9286 designates a PEM file from which to load certificate revocation list used
9287 to verify client's certificate.
9288
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009289crt <cert>
Alex Davies0fbf0162013-03-02 16:04:50 +00009290 This setting is only available when support for OpenSSL was built in. It
9291 designates a PEM file containing both the required certificates and any
9292 associated private keys. This file can be built by concatenating multiple
9293 PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA
9294 requires an intermediate certificate, this can also be concatenated into this
9295 file.
9296
9297 If the OpenSSL used supports Diffie-Hellman, parameters present in this file
9298 are loaded.
9299
9300 If a directory name is used instead of a PEM file, then all files found in
Cyril Bonté3180f7b2015-01-25 00:16:08 +01009301 that directory will be loaded in alphabetic order unless their name ends with
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +01009302 '.issuer', '.ocsp' or '.sctl' (reserved extensions). This directive may be
9303 specified multiple times in order to load certificates from multiple files or
9304 directories. The certificates will be presented to clients who provide a
9305 valid TLS Server Name Indication field matching one of their CN or alt
9306 subjects. Wildcards are supported, where a wildcard character '*' is used
9307 instead of the first hostname component (eg: *.example.org matches
9308 www.example.org but not www.sub.example.org).
Alex Davies0fbf0162013-03-02 16:04:50 +00009309
9310 If no SNI is provided by the client or if the SSL library does not support
9311 TLS extensions, or if the client provides an SNI hostname which does not
9312 match any certificate, then the first loaded certificate will be presented.
9313 This means that when loading certificates from a directory, it is highly
Cyril Bonté3180f7b2015-01-25 00:16:08 +01009314 recommended to load the default one first as a file or to ensure that it will
9315 always be the first one in the directory.
Alex Davies0fbf0162013-03-02 16:04:50 +00009316
Emeric Brune032bfa2012-09-28 13:01:45 +02009317 Note that the same cert may be loaded multiple times without side effects.
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009318
Alex Davies0fbf0162013-03-02 16:04:50 +00009319 Some CAs (such as Godaddy) offer a drop down list of server types that do not
9320 include HAProxy when obtaining a certificate. If this happens be sure to
Godbach8bf60a12014-04-21 21:42:41 +08009321 choose a webserver that the CA believes requires an intermediate CA (for
Alex Davies0fbf0162013-03-02 16:04:50 +00009322 Godaddy, selection Apache Tomcat will get the correct bundle, but many
9323 others, e.g. nginx, result in a wrong bundle that will not work for some
9324 clients).
9325
Emeric Brun4147b2e2014-06-16 18:36:30 +02009326 For each PEM file, haproxy checks for the presence of file at the same path
9327 suffixed by ".ocsp". If such file is found, support for the TLS Certificate
9328 Status Request extension (also known as "OCSP stapling") is automatically
9329 enabled. The content of this file is optional. If not empty, it must contain
9330 a valid OCSP Response in DER format. In order to be valid an OCSP Response
9331 must comply with the following rules: it has to indicate a good status,
9332 it has to be a single response for the certificate of the PEM file, and it
9333 has to be valid at the moment of addition. If these rules are not respected
9334 the OCSP Response is ignored and a warning is emitted. In order to identify
9335 which certificate an OCSP Response applies to, the issuer's certificate is
9336 necessary. If the issuer's certificate is not found in the PEM file, it will
9337 be loaded from a file at the same path as the PEM file suffixed by ".issuer"
9338 if it exists otherwise it will fail with an error.
9339
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +01009340 For each PEM file, haproxy also checks for the presence of file at the same
9341 path suffixed by ".sctl". If such file is found, support for Certificate
9342 Transparency (RFC6962) TLS extension is enabled. The file must contain a
9343 valid Signed Certificate Timestamp List, as described in RFC. File is parsed
9344 to check basic syntax, but no signatures are verified.
9345
Emeric Brunb6dc9342012-09-28 17:55:37 +02009346crt-ignore-err <errors>
Alex Davies0fbf0162013-03-02 16:04:50 +00009347 This setting is only available when support for OpenSSL was built in. Sets a
9348 comma separated list of errorIDs to ignore during verify at depth == 0. If
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009349 set to 'all', all errors are ignored. SSL handshake is not aborted if an error
Alex Davies0fbf0162013-03-02 16:04:50 +00009350 is ignored.
Emeric Brunb6dc9342012-09-28 17:55:37 +02009351
Emmanuel Hocdetfe616562013-01-22 15:31:15 +01009352crt-list <file>
9353 This setting is only available when support for OpenSSL was built in. It
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +02009354 designates a list of PEM file with an optional list of SNI filter per
9355 certificate, with the following format for each line :
Emmanuel Hocdetfe616562013-01-22 15:31:15 +01009356
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +02009357 <crtfile> [[!]<snifilter> ...]
Emmanuel Hocdetfe616562013-01-22 15:31:15 +01009358
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +02009359 Wildcards are supported in the SNI filter. Negative filter are also supported,
9360 only useful in combination with a wildcard filter to exclude a particular SNI.
9361 The certificates will be presented to clients who provide a valid TLS Server
9362 Name Indication field matching one of the SNI filters. If no SNI filter is
9363 specified, the CN and alt subjects are used. This directive may be specified
9364 multiple times. See the "crt" option for more information. The default
9365 certificate is still needed to meet OpenSSL expectations. If it is not used,
9366 the 'strict-sni' option may be used.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +01009367
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009368defer-accept
9369 Is an optional keyword which is supported only on certain Linux kernels. It
9370 states that a connection will only be accepted once some data arrive on it,
9371 or at worst after the first retransmit. This should be used only on protocols
9372 for which the client talks first (eg: HTTP). It can slightly improve
9373 performance by ensuring that most of the request is already available when
9374 the connection is accepted. On the other hand, it will not be able to detect
9375 connections which don't talk. It is important to note that this option is
9376 broken in all kernels up to 2.6.31, as the connection is never accepted until
9377 the client talks. This can cause issues with front firewalls which would see
9378 an established connection while the proxy will only see it in SYN_RECV. This
9379 option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
9380
Emeric Brun2cb7ae52012-10-05 14:14:21 +02009381force-sslv3
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009382 This option enforces use of SSLv3 only on SSL connections instantiated from
Emeric Brun2cb7ae52012-10-05 14:14:21 +02009383 this listener. SSLv3 is generally less expensive than the TLS counterparts
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009384 for high connection rates. This option is also available on global statement
9385 "ssl-default-bind-options". See also "no-tlsv*" and "no-sslv3".
Emeric Brun2cb7ae52012-10-05 14:14:21 +02009386
9387force-tlsv10
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009388 This option enforces use of TLSv1.0 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009389 this listener. This option is also available on global statement
9390 "ssl-default-bind-options". See also "no-tlsv*" and "no-sslv3".
Emeric Brun2cb7ae52012-10-05 14:14:21 +02009391
9392force-tlsv11
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009393 This option enforces use of TLSv1.1 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009394 this listener. This option is also available on global statement
9395 "ssl-default-bind-options". See also "no-tlsv*", and "no-sslv3".
Emeric Brun2cb7ae52012-10-05 14:14:21 +02009396
9397force-tlsv12
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009398 This option enforces use of TLSv1.2 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009399 this listener. This option is also available on global statement
9400 "ssl-default-bind-options". See also "no-tlsv*", and "no-sslv3".
Emeric Brun2cb7ae52012-10-05 14:14:21 +02009401
Christopher Faulet31af49d2015-06-09 17:29:50 +02009402generate-certificates
9403 This setting is only available when support for OpenSSL was built in. It
9404 enables the dynamic SSL certificates generation. A CA certificate and its
9405 private key are necessary (see 'ca-sign-file'). When HAProxy is configured as
9406 a transparent forward proxy, SSL requests generate errors because of a common
9407 name mismatch on the certificate presented to the client. With this option
9408 enabled, HAProxy will try to forge a certificate using the SNI hostname
9409 indicated by the client. This is done only if no certificate matches the SNI
9410 hostname (see 'crt-list'). If an error occurs, the default certificate is
9411 used, else the 'strict-sni' option is set.
9412 It can also be used when HAProxy is configured as a reverse proxy to ease the
9413 deployment of an architecture with many backends.
9414
9415 Creating a SSL certificate is an expensive operation, so a LRU cache is used
9416 to store forged certificates (see 'tune.ssl.ssl-ctx-cache-size'). It
9417 increases the HAProxy's memroy footprint to reduce latency when the same
9418 certificate is used many times.
9419
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009420gid <gid>
9421 Sets the group of the UNIX sockets to the designated system gid. It can also
9422 be set by default in the global section's "unix-bind" statement. Note that
9423 some platforms simply ignore this. This setting is equivalent to the "group"
9424 setting except that the group ID is used instead of its name. This setting is
9425 ignored by non UNIX sockets.
9426
9427group <group>
9428 Sets the group of the UNIX sockets to the designated system group. It can
9429 also be set by default in the global section's "unix-bind" statement. Note
9430 that some platforms simply ignore this. This setting is equivalent to the
9431 "gid" setting except that the group name is used instead of its gid. This
9432 setting is ignored by non UNIX sockets.
9433
9434id <id>
9435 Fixes the socket ID. By default, socket IDs are automatically assigned, but
9436 sometimes it is more convenient to fix them to ease monitoring. This value
9437 must be strictly positive and unique within the listener/frontend. This
9438 option can only be used when defining only a single socket.
9439
9440interface <interface>
Lukas Tribusfce2e962013-02-12 22:13:19 +01009441 Restricts the socket to a specific interface. When specified, only packets
9442 received from that particular interface are processed by the socket. This is
9443 currently only supported on Linux. The interface must be a primary system
9444 interface, not an aliased interface. It is also possible to bind multiple
9445 frontends to the same address if they are bound to different interfaces. Note
9446 that binding to a network interface requires root privileges. This parameter
9447 is only compatible with TCPv4/TCPv6 sockets.
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009448
Willy Tarreauabb175f2012-09-24 12:43:26 +02009449level <level>
9450 This setting is used with the stats sockets only to restrict the nature of
9451 the commands that can be issued on the socket. It is ignored by other
9452 sockets. <level> can be one of :
9453 - "user" is the least privileged level ; only non-sensitive stats can be
9454 read, and no change is allowed. It would make sense on systems where it
9455 is not easy to restrict access to the socket.
9456 - "operator" is the default level and fits most common uses. All data can
9457 be read, and only non-sensitive changes are permitted (eg: clear max
9458 counters).
9459 - "admin" should be used with care, as everything is permitted (eg: clear
9460 all counters).
9461
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009462maxconn <maxconn>
9463 Limits the sockets to this number of concurrent connections. Extraneous
9464 connections will remain in the system's backlog until a connection is
9465 released. If unspecified, the limit will be the same as the frontend's
9466 maxconn. Note that in case of port ranges or multiple addresses, the same
9467 value will be applied to each socket. This setting enables different
9468 limitations on expensive sockets, for instance SSL entries which may easily
9469 eat all memory.
9470
9471mode <mode>
9472 Sets the octal mode used to define access permissions on the UNIX socket. It
9473 can also be set by default in the global section's "unix-bind" statement.
9474 Note that some platforms simply ignore this. This setting is ignored by non
9475 UNIX sockets.
9476
9477mss <maxseg>
9478 Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming
9479 connections. This can be used to force a lower MSS for certain specific
9480 ports, for instance for connections passing through a VPN. Note that this
9481 relies on a kernel feature which is theoretically supported under Linux but
9482 was buggy in all versions prior to 2.6.28. It may or may not work on other
9483 operating systems. It may also not change the advertised value but change the
9484 effective size of outgoing segments. The commonly advertised value for TCPv4
9485 over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is
9486 positive, it will be used as the advertised MSS. If it is negative, it will
9487 indicate by how much to reduce the incoming connection's advertised MSS for
9488 outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.
9489
9490name <name>
9491 Sets an optional name for these sockets, which will be reported on the stats
9492 page.
9493
9494nice <nice>
9495 Sets the 'niceness' of connections initiated from the socket. Value must be
9496 in the range -1024..1024 inclusive, and defaults to zero. Positive values
9497 means that such connections are more friendly to others and easily offer
9498 their place in the scheduler. On the opposite, negative values mean that
9499 connections want to run with a higher priority than others. The difference
9500 only happens under high loads when the system is close to saturation.
9501 Negative values are appropriate for low-latency or administration services,
9502 and high values are generally recommended for CPU intensive tasks such as SSL
9503 processing or bulk transfers which are less sensible to latency. For example,
9504 it may make sense to use a positive value for an SMTP socket and a negative
9505 one for an RDP socket.
9506
Emeric Brun9b3009b2012-10-05 11:55:06 +02009507no-sslv3
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009508 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009509 disables support for SSLv3 on any sockets instantiated from the listener when
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009510 SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009511 be enabled using any configuration option. This option is also available on
9512 global statement "ssl-default-bind-options". See also "force-tls*",
Emeric Brun2cb7ae52012-10-05 14:14:21 +02009513 and "force-sslv3".
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009514
Emeric Brun90ad8722012-10-02 14:00:59 +02009515no-tls-tickets
9516 This setting is only available when support for OpenSSL was built in. It
9517 disables the stateless session resumption (RFC 5077 TLS Ticket
9518 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009519 session resumption is more expensive in CPU usage. This option is also
9520 available on global statement "ssl-default-bind-options".
Emeric Brun90ad8722012-10-02 14:00:59 +02009521
Emeric Brun9b3009b2012-10-05 11:55:06 +02009522no-tlsv10
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009523 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009524 disables support for TLSv1.0 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +02009525 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009526 cannot be enabled using any configuration option. This option is also
9527 available on global statement "ssl-default-bind-options". See also
9528 "force-tlsv*", and "force-sslv3".
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009529
Emeric Brun9b3009b2012-10-05 11:55:06 +02009530no-tlsv11
Emeric Brunf5da4932012-09-28 19:42:54 +02009531 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009532 disables support for TLSv1.1 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +02009533 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009534 cannot be enabled using any configuration option. This option is also
9535 available on global statement "ssl-default-bind-options". See also
9536 "force-tlsv*", and "force-sslv3".
Emeric Brunf5da4932012-09-28 19:42:54 +02009537
Emeric Brun9b3009b2012-10-05 11:55:06 +02009538no-tlsv12
Emeric Brunf5da4932012-09-28 19:42:54 +02009539 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009540 disables support for TLSv1.2 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +02009541 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009542 cannot be enabled using any configuration option. This option is also
9543 available on global statement "ssl-default-bind-options". See also
9544 "force-tlsv*", and "force-sslv3".
Emeric Brunf5da4932012-09-28 19:42:54 +02009545
Willy Tarreau6c9a3d52012-10-18 18:57:14 +02009546npn <protocols>
9547 This enables the NPN TLS extension and advertises the specified protocol list
9548 as supported on top of NPN. The protocol list consists in a comma-delimited
9549 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
9550 This requires that the SSL library is build with support for TLS extensions
Willy Tarreauab861d32013-04-02 02:30:41 +02009551 enabled (check with haproxy -vv). Note that the NPN extension has been
9552 replaced with the ALPN extension (see the "alpn" keyword).
Willy Tarreau6c9a3d52012-10-18 18:57:14 +02009553
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02009554process [ all | odd | even | <number 1-64>[-<number 1-64>] ]
9555 This restricts the list of processes on which this listener is allowed to
9556 run. It does not enforce any process but eliminates those which do not match.
9557 If the frontend uses a "bind-process" setting, the intersection between the
9558 two is applied. If in the end the listener is not allowed to run on any
9559 remaining process, a warning is emitted, and the listener will either run on
9560 the first process of the listener if a single process was specified, or on
9561 all of its processes if multiple processes were specified. For the unlikely
Willy Tarreauae302532014-05-07 19:22:24 +02009562 case where several ranges are needed, this directive may be repeated. The
9563 main purpose of this directive is to be used with the stats sockets and have
9564 one different socket per process. The second purpose is to have multiple bind
9565 lines sharing the same IP:port but not the same process in a listener, so
9566 that the system can distribute the incoming connections into multiple queues
9567 and allow a smoother inter-process load balancing. Currently Linux 3.9 and
9568 above is known for supporting this. See also "bind-process" and "nbproc".
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02009569
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009570ssl
9571 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009572 enables SSL deciphering on connections instantiated from this listener. A
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009573 certificate is necessary (see "crt" above). All contents in the buffers will
9574 appear in clear text, so that ACLs and HTTP processing will only have access
9575 to deciphered contents.
9576
Emmanuel Hocdet65623372013-01-24 17:17:15 +01009577strict-sni
9578 This setting is only available when support for OpenSSL was built in. The
9579 SSL/TLS negotiation is allow only if the client provided an SNI which match
9580 a certificate. The default certificate is not used.
9581 See the "crt" option for more information.
9582
Willy Tarreau2af207a2015-02-04 00:45:58 +01009583tcp-ut <delay>
9584 Sets the TCP User Timeout for all incoming connections instanciated from this
9585 listening socket. This option is available on Linux since version 2.6.37. It
9586 allows haproxy to configure a timeout for sockets which contain data not
9587 receiving an acknoledgement for the configured delay. This is especially
9588 useful on long-lived connections experiencing long idle periods such as
9589 remote terminals or database connection pools, where the client and server
9590 timeouts must remain high to allow a long period of idle, but where it is
9591 important to detect that the client has disappeared in order to release all
9592 resources associated with its connection (and the server's session). The
9593 argument is a delay expressed in milliseconds by default. This only works
9594 for regular TCP connections, and is ignored for other protocols.
9595
Willy Tarreau1c862c52012-10-05 16:21:00 +02009596tfo
Lukas Tribus0defb902013-02-13 23:35:39 +01009597 Is an optional keyword which is supported only on Linux kernels >= 3.7. It
Willy Tarreau1c862c52012-10-05 16:21:00 +02009598 enables TCP Fast Open on the listening socket, which means that clients which
9599 support this feature will be able to send a request and receive a response
9600 during the 3-way handshake starting from second connection, thus saving one
9601 round-trip after the first connection. This only makes sense with protocols
9602 that use high connection rates and where each round trip matters. This can
9603 possibly cause issues with many firewalls which do not accept data on SYN
9604 packets, so this option should only be enabled once well tested. This option
Lukas Tribus0999f762013-04-02 16:43:24 +02009605 is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may
9606 need to build HAProxy with USE_TFO=1 if your libc doesn't define
9607 TCP_FASTOPEN.
Willy Tarreau1c862c52012-10-05 16:21:00 +02009608
Nenad Merdanovic188ad3e2015-02-27 19:56:50 +01009609tls-ticket-keys <keyfile>
9610 Sets the TLS ticket keys file to load the keys from. The keys need to be 48
9611 bytes long, encoded with base64 (ex. openssl rand -base64 48). Number of keys
9612 is specified by the TLS_TICKETS_NO build option (default 3) and at least as
9613 many keys need to be present in the file. Last TLS_TICKETS_NO keys will be
9614 used for decryption and the penultimate one for encryption. This enables easy
9615 key rotation by just appending new key to the file and reloading the process.
9616 Keys must be periodically rotated (ex. every 12h) or Perfect Forward Secrecy
9617 is compromised. It is also a good idea to keep the keys off any permanent
9618 storage such as hard drives (hint: use tmpfs and don't swap those files).
9619 Lifetime hint can be changed using tune.ssl.timeout.
9620
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009621transparent
9622 Is an optional keyword which is supported only on certain Linux kernels. It
9623 indicates that the addresses will be bound even if they do not belong to the
9624 local machine, and that packets targeting any of these addresses will be
9625 intercepted just as if the addresses were locally configured. This normally
9626 requires that IP forwarding is enabled. Caution! do not use this with the
9627 default address '*', as it would redirect any traffic for the specified port.
9628 This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1.
9629 This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on
9630 kernel version. Some distribution kernels include backports of the feature,
9631 so check for support with your vendor.
9632
Willy Tarreau77e3af92012-11-24 15:07:23 +01009633v4v6
9634 Is an optional keyword which is supported only on most recent systems
9635 including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4
9636 and IPv6 when it uses the default address. Doing so is sometimes necessary
9637 on systems which bind to IPv6 only by default. It has no effect on non-IPv6
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009638 sockets, and is overridden by the "v6only" option.
Willy Tarreau77e3af92012-11-24 15:07:23 +01009639
Willy Tarreau9b6700f2012-11-24 11:55:28 +01009640v6only
9641 Is an optional keyword which is supported only on most recent systems
9642 including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only
9643 when it uses the default address. Doing so is sometimes preferred to doing it
Willy Tarreau77e3af92012-11-24 15:07:23 +01009644 system-wide as it is per-listener. It has no effect on non-IPv6 sockets and
9645 has precedence over the "v4v6" option.
Willy Tarreau9b6700f2012-11-24 11:55:28 +01009646
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009647uid <uid>
9648 Sets the owner of the UNIX sockets to the designated system uid. It can also
9649 be set by default in the global section's "unix-bind" statement. Note that
9650 some platforms simply ignore this. This setting is equivalent to the "user"
9651 setting except that the user numeric ID is used instead of its name. This
9652 setting is ignored by non UNIX sockets.
9653
9654user <user>
9655 Sets the owner of the UNIX sockets to the designated system user. It can also
9656 be set by default in the global section's "unix-bind" statement. Note that
9657 some platforms simply ignore this. This setting is equivalent to the "uid"
9658 setting except that the user name is used instead of its uid. This setting is
9659 ignored by non UNIX sockets.
9660
Emeric Brun1a073b42012-09-28 17:07:34 +02009661verify [none|optional|required]
9662 This setting is only available when support for OpenSSL was built in. If set
9663 to 'none', client certificate is not requested. This is the default. In other
9664 cases, a client certificate is requested. If the client does not provide a
9665 certificate after the request and if 'verify' is set to 'required', then the
9666 handshake is aborted, while it would have succeeded if set to 'optional'. The
Emeric Brunfd33a262012-10-11 16:28:27 +02009667 certificate provided by the client is always verified using CAs from
9668 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
9669 is aborted, regardless of the 'verify' option, unless the error code exactly
9670 matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.
Willy Tarreau4a5cade2012-04-05 21:09:48 +02009671
Willy Tarreaub6205fd2012-09-24 12:27:33 +020096725.2. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +01009673------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02009674
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01009675The "server" and "default-server" keywords support a certain number of settings
9676which are all passed as arguments on the server line. The order in which those
9677arguments appear does not count, and they are all optional. Some of those
9678settings are single words (booleans) while others expect one or several values
9679after them. In this case, the values must immediately follow the setting name.
9680Except default-server, all those settings must be specified after the server's
9681address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +02009682
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009683 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01009684 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +02009685
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009686The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +01009687
Willy Tarreauceb4ac92012-04-28 00:41:46 +02009688addr <ipv4|ipv6>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009689 Using the "addr" parameter, it becomes possible to use a different IP address
9690 to send health-checks. On some servers, it may be desirable to dedicate an IP
9691 address to specific component able to perform complex tests which are more
9692 suitable to health-checks than the application. This parameter is ignored if
9693 the "check" parameter is not set. See also the "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009694
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009695 Supported in default-server: No
9696
Simon Hormand60d6912013-11-25 10:46:36 +09009697agent-check
9698 Enable an auxiliary agent check which is run independently of a regular
Willy Tarreau81f5d942013-12-09 20:51:51 +01009699 health check. An agent health check is performed by making a TCP connection
9700 to the port set by the "agent-port" parameter and reading an ASCII string.
9701 The string is made of a series of words delimited by spaces, tabs or commas
9702 in any order, optionally terminated by '\r' and/or '\n', each consisting of :
Simon Hormand60d6912013-11-25 10:46:36 +09009703
Willy Tarreau81f5d942013-12-09 20:51:51 +01009704 - An ASCII representation of a positive integer percentage, e.g. "75%".
Simon Hormand60d6912013-11-25 10:46:36 +09009705 Values in this format will set the weight proportional to the initial
Willy Tarreauc5af3a62014-10-07 15:27:33 +02009706 weight of a server as configured when haproxy starts. Note that a zero
9707 weight is reported on the stats page as "DRAIN" since it has the same
9708 effect on the server (it's removed from the LB farm).
Simon Hormand60d6912013-11-25 10:46:36 +09009709
Willy Tarreau81f5d942013-12-09 20:51:51 +01009710 - The word "ready". This will turn the server's administrative state to the
9711 READY mode, thus cancelling any DRAIN or MAINT state
Simon Hormand60d6912013-11-25 10:46:36 +09009712
Willy Tarreau81f5d942013-12-09 20:51:51 +01009713 - The word "drain". This will turn the server's administrative state to the
9714 DRAIN mode, thus it will not accept any new connections other than those
9715 that are accepted via persistence.
Simon Hormand60d6912013-11-25 10:46:36 +09009716
Willy Tarreau81f5d942013-12-09 20:51:51 +01009717 - The word "maint". This will turn the server's administrative state to the
9718 MAINT mode, thus it will not accept any new connections at all, and health
9719 checks will be stopped.
Simon Hormand60d6912013-11-25 10:46:36 +09009720
Willy Tarreau81f5d942013-12-09 20:51:51 +01009721 - The words "down", "failed", or "stopped", optionally followed by a
9722 description string after a sharp ('#'). All of these mark the server's
9723 operating state as DOWN, but since the word itself is reported on the stats
9724 page, the difference allows an administrator to know if the situation was
9725 expected or not : the service may intentionally be stopped, may appear up
9726 but fail some validity tests, or may be seen as down (eg: missing process,
9727 or port not responding).
Simon Hormand60d6912013-11-25 10:46:36 +09009728
Willy Tarreau81f5d942013-12-09 20:51:51 +01009729 - The word "up" sets back the server's operating state as UP if health checks
9730 also report that the service is accessible.
Simon Hormand60d6912013-11-25 10:46:36 +09009731
Willy Tarreau81f5d942013-12-09 20:51:51 +01009732 Parameters which are not advertised by the agent are not changed. For
9733 example, an agent might be designed to monitor CPU usage and only report a
9734 relative weight and never interact with the operating status. Similarly, an
9735 agent could be designed as an end-user interface with 3 radio buttons
9736 allowing an administrator to change only the administrative state. However,
9737 it is important to consider that only the agent may revert its own actions,
9738 so if a server is set to DRAIN mode or to DOWN state using the agent, the
9739 agent must implement the other equivalent actions to bring the service into
9740 operations again.
Simon Hormand60d6912013-11-25 10:46:36 +09009741
Simon Horman2f1f9552013-11-25 10:46:37 +09009742 Failure to connect to the agent is not considered an error as connectivity
9743 is tested by the regular health check which is enabled by the "check"
Willy Tarreau81f5d942013-12-09 20:51:51 +01009744 parameter. Warning though, it is not a good idea to stop an agent after it
9745 reports "down", since only an agent reporting "up" will be able to turn the
9746 server up again. Note that the CLI on the Unix stats socket is also able to
9747 force an agent's result in order to workaround a bogus agent if needed.
Simon Horman2f1f9552013-11-25 10:46:37 +09009748
Willy Tarreau81f5d942013-12-09 20:51:51 +01009749 Requires the "agent-port" parameter to be set. See also the "agent-inter"
9750 parameter.
Simon Hormand60d6912013-11-25 10:46:36 +09009751
9752 Supported in default-server: No
9753
9754agent-inter <delay>
9755 The "agent-inter" parameter sets the interval between two agent checks
9756 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
9757
9758 Just as with every other time-based parameter, it may be entered in any
9759 other explicit unit among { us, ms, s, m, h, d }. The "agent-inter"
9760 parameter also serves as a timeout for agent checks "timeout check" is
9761 not set. In order to reduce "resonance" effects when multiple servers are
9762 hosted on the same hardware, the agent and health checks of all servers
9763 are started with a small time offset between them. It is also possible to
9764 add some random noise in the agent and health checks interval using the
9765 global "spread-checks" keyword. This makes sense for instance when a lot
9766 of backends use the same servers.
9767
9768 See also the "agent-check" and "agent-port" parameters.
9769
9770 Supported in default-server: Yes
9771
9772agent-port <port>
9773 The "agent-port" parameter sets the TCP port used for agent checks.
9774
9775 See also the "agent-check" and "agent-inter" parameters.
9776
9777 Supported in default-server: Yes
9778
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009779backup
9780 When "backup" is present on a server line, the server is only used in load
9781 balancing when all other non-backup servers are unavailable. Requests coming
9782 with a persistence cookie referencing the server will always be served
9783 though. By default, only the first operational backup server is used, unless
9784 the "allbackups" option is set in the backend. See also the "allbackups"
9785 option.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009786
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009787 Supported in default-server: No
9788
Emeric Brunef42d922012-10-11 16:11:36 +02009789ca-file <cafile>
9790 This setting is only available when support for OpenSSL was built in. It
9791 designates a PEM file from which to load CA certificates used to verify
9792 server's certificate.
9793
9794 Supported in default-server: No
9795
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009796check
9797 This option enables health checks on the server. By default, a server is
Patrick Mézardb7aeec62012-01-22 16:01:22 +01009798 always considered available. If "check" is set, the server is available when
9799 accepting periodic TCP connections, to ensure that it is really able to serve
9800 requests. The default address and port to send the tests to are those of the
9801 server, and the default source is the same as the one defined in the
9802 backend. It is possible to change the address using the "addr" parameter, the
9803 port using the "port" parameter, the source address using the "source"
9804 address, and the interval and timers using the "inter", "rise" and "fall"
Simon Hormanafc47ee2013-11-25 10:46:35 +09009805 parameters. The request method is define in the backend using the "httpchk",
9806 "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please
9807 refer to those options and parameters for more information.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009808
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009809 Supported in default-server: No
9810
Willy Tarreau6c16adc2012-10-05 00:04:16 +02009811check-send-proxy
9812 This option forces emission of a PROXY protocol line with outgoing health
9813 checks, regardless of whether the server uses send-proxy or not for the
9814 normal traffic. By default, the PROXY protocol is enabled for health checks
9815 if it is already enabled for normal traffic and if no "port" nor "addr"
9816 directive is present. However, if such a directive is present, the
9817 "check-send-proxy" option needs to be used to force the use of the
9818 protocol. See also the "send-proxy" option for more information.
9819
9820 Supported in default-server: No
9821
Willy Tarreau763a95b2012-10-04 23:15:39 +02009822check-ssl
9823 This option forces encryption of all health checks over SSL, regardless of
9824 whether the server uses SSL or not for the normal traffic. This is generally
9825 used when an explicit "port" or "addr" directive is specified and SSL health
9826 checks are not inherited. It is important to understand that this option
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009827 inserts an SSL transport layer below the checks, so that a simple TCP connect
Willy Tarreau763a95b2012-10-04 23:15:39 +02009828 check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
9829 common use is to send HTTPS checks by combining "httpchk" with SSL checks.
9830 All SSL settings are common to health checks and traffic (eg: ciphers).
9831 See the "ssl" option for more information.
9832
9833 Supported in default-server: No
9834
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02009835ciphers <ciphers>
9836 This option sets the string describing the list of cipher algorithms that is
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009837 is negotiated during the SSL/TLS handshake with the server. The format of the
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02009838 string is defined in "man 1 ciphers". When SSL is used to communicate with
9839 servers on the local network, it is common to see a weaker set of algorithms
9840 than what is used over the internet. Doing so reduces CPU usage on both the
9841 server and haproxy while still keeping it compatible with deployed software.
9842 Some algorithms such as RC4-SHA1 are reasonably cheap. If no security at all
9843 is needed and just connectivity, using DES can be appropriate.
9844
Willy Tarreau763a95b2012-10-04 23:15:39 +02009845 Supported in default-server: No
9846
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009847cookie <value>
9848 The "cookie" parameter sets the cookie value assigned to the server to
9849 <value>. This value will be checked in incoming requests, and the first
9850 operational server possessing the same value will be selected. In return, in
9851 cookie insertion or rewrite modes, this value will be assigned to the cookie
9852 sent to the client. There is nothing wrong in having several servers sharing
9853 the same cookie value, and it is in fact somewhat common between normal and
9854 backup servers. See also the "cookie" keyword in backend section.
9855
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009856 Supported in default-server: No
9857
Emeric Brunef42d922012-10-11 16:11:36 +02009858crl-file <crlfile>
9859 This setting is only available when support for OpenSSL was built in. It
9860 designates a PEM file from which to load certificate revocation list used
9861 to verify server's certificate.
9862
9863 Supported in default-server: No
9864
Emeric Bruna7aa3092012-10-26 12:58:00 +02009865crt <cert>
9866 This setting is only available when support for OpenSSL was built in.
9867 It designates a PEM file from which to load both a certificate and the
9868 associated private key. This file can be built by concatenating both PEM
9869 files into one. This certificate will be sent if the server send a client
9870 certificate request.
9871
9872 Supported in default-server: No
9873
Willy Tarreau96839092010-03-29 10:02:24 +02009874disabled
9875 The "disabled" keyword starts the server in the "disabled" state. That means
9876 that it is marked down in maintenance mode, and no connection other than the
9877 ones allowed by persist mode will reach it. It is very well suited to setup
9878 new servers, because normal traffic will never reach them, while it is still
9879 possible to test the service by making use of the force-persist mechanism.
9880
9881 Supported in default-server: No
9882
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009883error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +01009884 If health observing is enabled, the "error-limit" parameter specifies the
9885 number of consecutive errors that triggers event selected by the "on-error"
9886 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01009887
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009888 Supported in default-server: Yes
9889
9890 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01009891
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009892fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009893 The "fall" parameter states that a server will be considered as dead after
9894 <count> consecutive unsuccessful health checks. This value defaults to 3 if
9895 unspecified. See also the "check", "inter" and "rise" parameters.
9896
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009897 Supported in default-server: Yes
9898
Emeric Brun8694b9a2012-10-05 14:39:07 +02009899force-sslv3
9900 This option enforces use of SSLv3 only when SSL is used to communicate with
9901 the server. SSLv3 is generally less expensive than the TLS counterparts for
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009902 high connection rates. This option is also available on global statement
9903 "ssl-default-server-options". See also "no-tlsv*", "no-sslv3".
Emeric Brun8694b9a2012-10-05 14:39:07 +02009904
9905 Supported in default-server: No
9906
9907force-tlsv10
9908 This option enforces use of TLSv1.0 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009909 the server. This option is also available on global statement
9910 "ssl-default-server-options". See also "no-tlsv*", "no-sslv3".
Emeric Brun8694b9a2012-10-05 14:39:07 +02009911
9912 Supported in default-server: No
9913
9914force-tlsv11
9915 This option enforces use of TLSv1.1 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009916 the server. This option is also available on global statement
9917 "ssl-default-server-options". See also "no-tlsv*", "no-sslv3".
Emeric Brun8694b9a2012-10-05 14:39:07 +02009918
9919 Supported in default-server: No
9920
9921force-tlsv12
9922 This option enforces use of TLSv1.2 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +01009923 the server. This option is also available on global statement
9924 "ssl-default-server-options". See also "no-tlsv*", "no-sslv3".
Emeric Brun8694b9a2012-10-05 14:39:07 +02009925
9926 Supported in default-server: No
9927
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009928id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02009929 Set a persistent ID for the server. This ID must be positive and unique for
9930 the proxy. An unused ID will automatically be assigned if unset. The first
9931 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009932
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009933 Supported in default-server: No
9934
9935inter <delay>
9936fastinter <delay>
9937downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009938 The "inter" parameter sets the interval between two consecutive health checks
9939 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
9940 It is also possible to use "fastinter" and "downinter" to optimize delays
9941 between checks depending on the server state :
9942
9943 Server state | Interval used
9944 ---------------------------------+-----------------------------------------
9945 UP 100% (non-transitional) | "inter"
9946 ---------------------------------+-----------------------------------------
9947 Transitionally UP (going down), |
9948 Transitionally DOWN (going up), | "fastinter" if set, "inter" otherwise.
9949 or yet unchecked. |
9950 ---------------------------------+-----------------------------------------
9951 DOWN 100% (non-transitional) | "downinter" if set, "inter" otherwise.
9952 ---------------------------------+-----------------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +01009953
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009954 Just as with every other time-based parameter, they can be entered in any
9955 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
9956 serves as a timeout for health checks sent to servers if "timeout check" is
9957 not set. In order to reduce "resonance" effects when multiple servers are
Simon Hormand60d6912013-11-25 10:46:36 +09009958 hosted on the same hardware, the agent and health checks of all servers
9959 are started with a small time offset between them. It is also possible to
9960 add some random noise in the agent and health checks interval using the
9961 global "spread-checks" keyword. This makes sense for instance when a lot
9962 of backends use the same servers.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009963
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009964 Supported in default-server: Yes
9965
9966maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009967 The "maxconn" parameter specifies the maximal number of concurrent
9968 connections that will be sent to this server. If the number of incoming
9969 concurrent requests goes higher than this value, they will be queued, waiting
9970 for a connection to be released. This parameter is very important as it can
9971 save fragile servers from going down under extreme loads. If a "minconn"
9972 parameter is specified, the limit becomes dynamic. The default value is "0"
9973 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
9974 the backend's "fullconn" keyword.
9975
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009976 Supported in default-server: Yes
9977
9978maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009979 The "maxqueue" parameter specifies the maximal number of connections which
9980 will wait in the queue for this server. If this limit is reached, next
9981 requests will be redispatched to other servers instead of indefinitely
9982 waiting to be served. This will break persistence but may allow people to
9983 quickly re-log in when the server they try to connect to is dying. The
9984 default value is "0" which means the queue is unlimited. See also the
9985 "maxconn" and "minconn" parameters.
9986
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009987 Supported in default-server: Yes
9988
9989minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009990 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
9991 limit following the backend's load. The server will always accept at least
9992 <minconn> connections, never more than <maxconn>, and the limit will be on
9993 the ramp between both values when the backend has less than <fullconn>
9994 concurrent connections. This makes it possible to limit the load on the
9995 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009996 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009997 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01009998
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01009999 Supported in default-server: Yes
10000
Willy Tarreau2a3fb1c2015-02-05 16:47:07 +010010001no-ssl-reuse
10002 This option disables SSL session reuse when SSL is used to communicate with
10003 the server. It will force the server to perform a full handshake for every
10004 new connection. It's probably only useful for benchmarking, troubleshooting,
10005 and for paranoid users.
10006
10007 Supported in default-server: No
10008
Emeric Brun9b3009b2012-10-05 11:55:06 +020010009no-sslv3
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020010010 This option disables support for SSLv3 when SSL is used to communicate with
10011 the server. Note that SSLv2 is disabled in the code and cannot be enabled
Emeric Brun8694b9a2012-10-05 14:39:07 +020010012 using any configuration option. See also "force-sslv3", "force-tlsv*".
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020010013
Willy Tarreau763a95b2012-10-04 23:15:39 +020010014 Supported in default-server: No
10015
Emeric Brunf9c5c472012-10-11 15:28:34 +020010016no-tls-tickets
10017 This setting is only available when support for OpenSSL was built in. It
10018 disables the stateless session resumption (RFC 5077 TLS Ticket
10019 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010020 session resumption is more expensive in CPU usage for servers. This option
10021 is also available on global statement "ssl-default-server-options".
Emeric Brunf9c5c472012-10-11 15:28:34 +020010022
10023 Supported in default-server: No
10024
Emeric Brun9b3009b2012-10-05 11:55:06 +020010025no-tlsv10
Emeric Brun8694b9a2012-10-05 14:39:07 +020010026 This option disables support for TLSv1.0 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020010027 the server. Note that SSLv2 is disabled in the code and cannot be enabled
10028 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010029 often makes sense to disable it when communicating with local servers. This
10030 option is also available on global statement "ssl-default-server-options".
10031 See also "force-sslv3", "force-tlsv*".
Emeric Brunf5da4932012-09-28 19:42:54 +020010032
Willy Tarreau763a95b2012-10-04 23:15:39 +020010033 Supported in default-server: No
10034
Emeric Brun9b3009b2012-10-05 11:55:06 +020010035no-tlsv11
Emeric Brun8694b9a2012-10-05 14:39:07 +020010036 This option disables support for TLSv1.1 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020010037 the server. Note that SSLv2 is disabled in the code and cannot be enabled
10038 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010039 often makes sense to disable it when communicating with local servers. This
10040 option is also available on global statement "ssl-default-server-options".
10041 See also "force-sslv3", "force-tlsv*".
Emeric Brunf5da4932012-09-28 19:42:54 +020010042
Willy Tarreau763a95b2012-10-04 23:15:39 +020010043 Supported in default-server: No
10044
Emeric Brun9b3009b2012-10-05 11:55:06 +020010045no-tlsv12
Emeric Brun8694b9a2012-10-05 14:39:07 +020010046 This option disables support for TLSv1.2 when SSL is used to communicate with
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020010047 the server. Note that SSLv2 is disabled in the code and cannot be enabled
10048 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010010049 often makes sense to disable it when communicating with local servers. This
10050 option is also available on global statement "ssl-default-server-options".
10051 See also "force-sslv3", "force-tlsv*".
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020010052
Willy Tarreau763a95b2012-10-04 23:15:39 +020010053 Supported in default-server: No
10054
Simon Hormanfa461682011-06-25 09:39:49 +090010055non-stick
10056 Never add connections allocated to this sever to a stick-table.
10057 This may be used in conjunction with backup to ensure that
10058 stick-table persistence is disabled for backup servers.
10059
Willy Tarreau763a95b2012-10-04 23:15:39 +020010060 Supported in default-server: No
10061
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010010062observe <mode>
10063 This option enables health adjusting based on observing communication with
10064 the server. By default this functionality is disabled and enabling it also
10065 requires to enable health checks. There are two supported modes: "layer4" and
10066 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
10067 significant. In layer7, which is only allowed for http proxies, responses
10068 received from server are verified, like valid/wrong http code, unparsable
Willy Tarreau150d1462012-03-10 08:19:02 +010010069 headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010010070
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010071 Supported in default-server: No
10072
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010010073 See also the "check", "on-error" and "error-limit".
10074
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010075on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010010076 Select what should happen when enough consecutive errors are detected.
10077 Currently, four modes are available:
10078 - fastinter: force fastinter
10079 - fail-check: simulate a failed check, also forces fastinter (default)
10080 - sudden-death: simulate a pre-fatal failed health check, one more failed
10081 check will mark a server down, forces fastinter
10082 - mark-down: mark the server immediately down and force fastinter
10083
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010084 Supported in default-server: Yes
10085
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010010086 See also the "check", "observe" and "error-limit".
10087
Simon Hormane0d1bfb2011-06-21 14:34:58 +090010088on-marked-down <action>
10089 Modify what occurs when a server is marked down.
10090 Currently one action is available:
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070010091 - shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
10092 all connections to the server are immediately terminated when the server
10093 goes down. It might be used if the health check detects more complex cases
10094 than a simple connection status, and long timeouts would cause the service
10095 to remain unresponsive for too long a time. For instance, a health check
10096 might detect that a database is stuck and that there's no chance to reuse
10097 existing connections anymore. Connections killed this way are logged with
10098 a 'D' termination code (for "Down").
Simon Hormane0d1bfb2011-06-21 14:34:58 +090010099
10100 Actions are disabled by default
10101
10102 Supported in default-server: Yes
10103
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070010104on-marked-up <action>
10105 Modify what occurs when a server is marked up.
10106 Currently one action is available:
10107 - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
10108 done only if the server is not in backup state and if it is not disabled
10109 (it must have an effective weight > 0). This can be used sometimes to force
10110 an active server to take all the traffic back after recovery when dealing
10111 with long sessions (eg: LDAP, SQL, ...). Doing this can cause more trouble
10112 than it tries to solve (eg: incomplete transactions), so use this feature
10113 with extreme care. Sessions killed because a server comes up are logged
10114 with an 'U' termination code (for "Up").
10115
10116 Actions are disabled by default
10117
10118 Supported in default-server: Yes
10119
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010120port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010121 Using the "port" parameter, it becomes possible to use a different port to
10122 send health-checks. On some servers, it may be desirable to dedicate a port
10123 to a specific component able to perform complex tests which are more suitable
10124 to health-checks than the application. It is common to run a simple script in
10125 inetd for instance. This parameter is ignored if the "check" parameter is not
10126 set. See also the "addr" parameter.
10127
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010128 Supported in default-server: Yes
10129
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010130redir <prefix>
10131 The "redir" parameter enables the redirection mode for all GET and HEAD
10132 requests addressing this server. This means that instead of having HAProxy
10133 forward the request to the server, it will send an "HTTP 302" response with
10134 the "Location" header composed of this prefix immediately followed by the
10135 requested URI beginning at the leading '/' of the path component. That means
10136 that no trailing slash should be used after <prefix>. All invalid requests
10137 will be rejected, and all non-GET or HEAD requests will be normally served by
10138 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010139 mangling nor cookie insertion is possible in the response. However, cookies in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010140 requests are still analysed, making this solution completely usable to direct
10141 users to a remote location in case of local disaster. Main use consists in
10142 increasing bandwidth for static servers by having the clients directly
10143 connect to them. Note: never use a relative location here, it would cause a
10144 loop between the client and HAProxy!
10145
10146 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
10147
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010148 Supported in default-server: No
10149
10150rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010151 The "rise" parameter states that a server will be considered as operational
10152 after <count> consecutive successful health checks. This value defaults to 2
10153 if unspecified. See also the "check", "inter" and "fall" parameters.
10154
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010155 Supported in default-server: Yes
10156
Baptiste Assmann1fa66662015-04-14 00:28:47 +020010157resolve-prefer <family>
10158 When DNS resolution is enabled for a server and multiple IP addresses from
10159 different families are returned, HAProxy will prefer using an IP address
10160 from the family mentioned in the "resolve-prefer" parameter.
10161 Available families: "ipv4" and "ipv6"
10162
Baptiste Assmannc4aabae2015-08-04 22:43:06 +020010163 Default value: ipv6
10164
10165 Supported in default-server: Yes
Baptiste Assmann1fa66662015-04-14 00:28:47 +020010166
10167 Example: server s1 app1.domain.com:80 resolvers mydns resolve-prefer ipv6
10168
10169resolvers <id>
10170 Points to an existing "resolvers" section to resolve current server's
10171 hostname.
10172
10173 Example: server s1 app1.domain.com:80 resolvers mydns
10174
10175 See also chapter 5.3
10176
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010010177send-proxy
10178 The "send-proxy" parameter enforces use of the PROXY protocol over any
10179 connection established to this server. The PROXY protocol informs the other
10180 end about the layer 3/4 addresses of the incoming connection, so that it can
10181 know the client's address or the public address it accessed to, whatever the
10182 upper layer protocol. For connections accepted by an "accept-proxy" listener,
10183 the advertised address will be used. Only TCPv4 and TCPv6 address families
10184 are supported. Other families such as Unix sockets, will report an UNKNOWN
10185 family. Servers using this option can fully be chained to another instance of
10186 haproxy listening with an "accept-proxy" setting. This setting must not be
Willy Tarreau6c16adc2012-10-05 00:04:16 +020010187 used if the server isn't aware of the protocol. When health checks are sent
10188 to the server, the PROXY protocol is automatically used when this option is
10189 set, unless there is an explicit "port" or "addr" directive, in which case an
10190 explicit "check-send-proxy" directive would also be needed to use the PROXY
10191 protocol. See also the "accept-proxy" option of the "bind" keyword.
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010010192
10193 Supported in default-server: No
10194
David Safb76832014-05-08 23:42:08 -040010195send-proxy-v2
10196 The "send-proxy-v2" parameter enforces use of the PROXY protocol version 2
10197 over any connection established to this server. The PROXY protocol informs
10198 the other end about the layer 3/4 addresses of the incoming connection, so
10199 that it can know the client's address or the public address it accessed to,
10200 whatever the upper layer protocol. This setting must not be used if the
10201 server isn't aware of this version of the protocol. See also the "send-proxy"
10202 option of the "bind" keyword.
10203
10204 Supported in default-server: No
10205
10206send-proxy-v2-ssl
10207 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
10208 2 over any connection established to this server. The PROXY protocol informs
10209 the other end about the layer 3/4 addresses of the incoming connection, so
10210 that it can know the client's address or the public address it accessed to,
10211 whatever the upper layer protocol. In addition, the SSL information extension
10212 of the PROXY protocol is added to the PROXY protocol header. This setting
10213 must not be used if the server isn't aware of this version of the protocol.
10214 See also the "send-proxy-v2" option of the "bind" keyword.
10215
10216 Supported in default-server: No
10217
10218send-proxy-v2-ssl-cn
10219 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
10220 2 over any connection established to this server. The PROXY protocol informs
10221 the other end about the layer 3/4 addresses of the incoming connection, so
10222 that it can know the client's address or the public address it accessed to,
10223 whatever the upper layer protocol. In addition, the SSL information extension
10224 of the PROXY protocol, along along with the Common Name from the subject of
10225 the client certificate (if any), is added to the PROXY protocol header. This
10226 setting must not be used if the server isn't aware of this version of the
10227 protocol. See also the "send-proxy-v2" option of the "bind" keyword.
10228
10229 Supported in default-server: No
10230
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010231slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010232 The "slowstart" parameter for a server accepts a value in milliseconds which
10233 indicates after how long a server which has just come back up will run at
10234 full speed. Just as with every other time-based parameter, it can be entered
10235 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
10236 linearly from 0 to 100% during this time. The limitation applies to two
10237 parameters :
10238
10239 - maxconn: the number of connections accepted by the server will grow from 1
10240 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
10241
10242 - weight: when the backend uses a dynamic weighted algorithm, the weight
10243 grows linearly from 1 to 100%. In this case, the weight is updated at every
10244 health-check. For this reason, it is important that the "inter" parameter
10245 is smaller than the "slowstart", in order to maximize the number of steps.
10246
10247 The slowstart never applies when haproxy starts, otherwise it would cause
10248 trouble to running servers. It only applies when a server has been previously
10249 seen as failed.
10250
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010251 Supported in default-server: Yes
10252
Willy Tarreau732eac42015-07-09 11:40:25 +020010253sni <expression>
10254 The "sni" parameter evaluates the sample fetch expression, converts it to a
10255 string and uses the result as the host name sent in the SNI TLS extension to
10256 the server. A typical use case is to send the SNI received from the client in
10257 a bridged HTTPS scenario, using the "ssl_fc_sni" sample fetch for the
10258 expression, though alternatives such as req.hdr(host) can also make sense.
10259
10260 Supported in default-server: no
10261
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020010262source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +020010263source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020010264source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010265 The "source" parameter sets the source address which will be used when
10266 connecting to the server. It follows the exact same parameters and principle
10267 as the backend "source" keyword, except that it only applies to the server
10268 referencing it. Please consult the "source" keyword for details.
10269
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020010270 Additionally, the "source" statement on a server line allows one to specify a
10271 source port range by indicating the lower and higher bounds delimited by a
10272 dash ('-'). Some operating systems might require a valid IP address when a
10273 source port range is specified. It is permitted to have the same IP/range for
10274 several servers. Doing so makes it possible to bypass the maximum of 64k
10275 total concurrent connections. The limit will then reach 64k connections per
10276 server.
10277
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010278 Supported in default-server: No
10279
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020010280ssl
Willy Tarreau44f65392013-06-25 07:56:20 +020010281 This option enables SSL ciphering on outgoing connections to the server. It
10282 is critical to verify server certificates using "verify" when using SSL to
10283 connect to servers, otherwise the communication is prone to trivial man in
10284 the-middle attacks rendering SSL useless. When this option is used, health
10285 checks are automatically sent in SSL too unless there is a "port" or an
10286 "addr" directive indicating the check should be sent to a different location.
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010287 See the "check-ssl" option to force SSL health checks.
Willy Tarreau763a95b2012-10-04 23:15:39 +020010288
10289 Supported in default-server: No
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020010290
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010291track [<proxy>/]<server>
Willy Tarreau32091232014-05-16 13:52:00 +020010292 This option enables ability to set the current state of the server by tracking
10293 another one. It is possible to track a server which itself tracks another
10294 server, provided that at the end of the chain, a server has health checks
10295 enabled. If <proxy> is omitted the current one is used. If disable-on-404 is
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010296 used, it has to be enabled on both proxies.
10297
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010298 Supported in default-server: No
10299
Emeric Brunef42d922012-10-11 16:11:36 +020010300verify [none|required]
10301 This setting is only available when support for OpenSSL was built in. If set
Emeric Brun850efd52014-01-29 12:24:34 +010010302 to 'none', server certificate is not verified. In the other case, The
10303 certificate provided by the server is verified using CAs from 'ca-file'
10304 and optional CRLs from 'crl-file'. If 'ssl_server_verify' is not specified
10305 in global section, this is the default. On verify failure the handshake
Willy Tarreau44f65392013-06-25 07:56:20 +020010306 is aborted. It is critically important to verify server certificates when
10307 using SSL to connect to servers, otherwise the communication is prone to
10308 trivial man-in-the-middle attacks rendering SSL totally useless.
Emeric Brunef42d922012-10-11 16:11:36 +020010309
10310 Supported in default-server: No
10311
Evan Broderbe554312013-06-27 00:05:25 -070010312verifyhost <hostname>
10313 This setting is only available when support for OpenSSL was built in, and
10314 only takes effect if 'verify required' is also specified. When set, the
10315 hostnames in the subject and subjectAlternateNames of the certificate
10316 provided by the server are checked. If none of the hostnames in the
10317 certificate match the specified hostname, the handshake is aborted. The
10318 hostnames in the server-provided certificate may include wildcards.
10319
10320 Supported in default-server: No
10321
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010322weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010323 The "weight" parameter is used to adjust the server's weight relative to
10324 other servers. All servers will receive a load proportional to their weight
10325 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +020010326 load. The default weight is 1, and the maximal value is 256. A value of 0
10327 means the server will not participate in load-balancing but will still accept
10328 persistent connections. If this parameter is used to distribute the load
10329 according to server's capacity, it is recommended to start with values which
10330 can both grow and shrink, for instance between 10 and 100 to leave enough
10331 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010332
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010010333 Supported in default-server: Yes
10334
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010335
Cyril Bonté46175dd2015-07-02 22:45:32 +0200103365.3. Server IP address resolution using DNS
10337-------------------------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020010338
10339HAProxy allows using a host name to be resolved to find out what is the server
10340IP address. By default, HAProxy resolves the name when parsing the
10341configuration, at startup.
10342This is not sufficient in some cases, such as in Amazon where a server's IP
10343can change after a reboot or an ELB Virtual IP can change based on current
10344workload.
10345This chapter describes how HAProxy can be configured to process server's name
10346resolution at run time.
10347Whether run time server name resolution has been enable or not, HAProxy will
10348carry on doing the first resolution when parsing the configuration.
10349
10350
Cyril Bonté46175dd2015-07-02 22:45:32 +0200103515.3.1. Global overview
10352----------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020010353
10354As we've seen in introduction, name resolution in HAProxy occurs at two
10355different steps of the process life:
10356
10357 1. when starting up, HAProxy parses the server line definition and matches a
10358 host name. It uses libc functions to get the host name resolved. This
10359 resolution relies on /etc/resolv.conf file.
10360
10361 2. at run time, when HAProxy gets prepared to run a health check on a server,
10362 it verifies if the current name resolution is still considered as valid.
10363 If not, it processes a new resolution, in parallel of the health check.
10364
10365A few other events can trigger a name resolution at run time:
10366 - when a server's health check ends up in a connection timeout: this may be
10367 because the server has a new IP address. So we need to trigger a name
10368 resolution to know this new IP.
10369
10370A few things important to notice:
10371 - all the name servers are queried in the mean time. HAProxy will process the
10372 first valid response.
10373
10374 - a resolution is considered as invalid (NX, timeout, refused), when all the
10375 servers return an error.
10376
10377
Cyril Bonté46175dd2015-07-02 22:45:32 +0200103785.3.2. The resolvers section
10379----------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020010380
10381This section is dedicated to host information related to name resolution in
10382HAProxy.
10383There can be as many as resolvers section as needed. Each section can contain
10384many name servers.
10385
10386resolvers <resolvers id>
10387 Creates a new name server list labelled <resolvers id>
10388
10389A resolvers section accept the following parameters:
10390
10391nameserver <id> <ip>:<port>
10392 DNS server description:
10393 <id> : label of the server, should be unique
10394 <ip> : IP address of the server
10395 <port> : port where the DNS service actually runs
10396
10397hold <status> <period>
10398 Defines <period> during which the last name resolution should be kept based
10399 on last resolution <status>
10400 <status> : last name resolution status. Only "valid" is accepted for now.
10401 <period> : interval between two successive name resolution when the last
10402 answer was in <status>. It follows the HAProxy time format.
10403 <period> is in milliseconds by default.
10404
10405 Default value is 10s for "valid".
10406
10407 Note: since the name resolution is triggered by the health checks, a new
10408 resolution is triggered after <period> modulo the <inter> parameter of
10409 the healch check.
10410
10411resolve_retries <nb>
10412 Defines the number <nb> of queries to send to resolve a server name before
10413 giving up.
10414 Default value: 3
10415
10416timeout <event> <time>
10417 Defines timeouts related to name resolution
10418 <event> : the event on which the <time> timeout period applies to.
10419 events available are:
10420 - retry: time between two DNS queries, when no response have
10421 been received.
10422 Default value: 1s
10423 <time> : time related to the event. It follows the HAProxy time format.
10424 <time> is expressed in milliseconds.
10425
10426Example of a resolvers section (with default values):
10427
10428 resolvers mydns
10429 nameserver dns1 10.0.0.1:53
10430 nameserver dns2 10.0.0.2:53
10431 resolve_retries 3
10432 timeout retry 1s
10433 hold valid 10s
10434
10435
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200104366. HTTP header manipulation
10437---------------------------
10438
10439In HTTP mode, it is possible to rewrite, add or delete some of the request and
10440response headers based on regular expressions. It is also possible to block a
10441request or a response if a particular header matches a regular expression,
10442which is enough to stop most elementary protocol attacks, and to protect
Willy Tarreau70dffda2014-01-30 03:07:23 +010010443against information leak from the internal network.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010444
Willy Tarreau70dffda2014-01-30 03:07:23 +010010445If HAProxy encounters an "Informational Response" (status code 1xx), it is able
10446to process all rsp* rules which can allow, deny, rewrite or delete a header,
10447but it will refuse to add a header to any such messages as this is not
10448HTTP-compliant. The reason for still processing headers in such responses is to
10449stop and/or fix any possible information leak which may happen, for instance
10450because another downstream equipment would unconditionally add a header, or if
10451a server name appears there. When such messages are seen, normal processing
10452still occurs on the next non-informational messages.
Willy Tarreau816b9792009-09-15 21:25:21 +020010453
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010454This section covers common usage of the following keywords, described in detail
10455in section 4.2 :
10456
10457 - reqadd <string>
10458 - reqallow <search>
10459 - reqiallow <search>
10460 - reqdel <search>
10461 - reqidel <search>
10462 - reqdeny <search>
10463 - reqideny <search>
10464 - reqpass <search>
10465 - reqipass <search>
10466 - reqrep <search> <replace>
10467 - reqirep <search> <replace>
10468 - reqtarpit <search>
10469 - reqitarpit <search>
10470 - rspadd <string>
10471 - rspdel <search>
10472 - rspidel <search>
10473 - rspdeny <search>
10474 - rspideny <search>
10475 - rsprep <search> <replace>
10476 - rspirep <search> <replace>
10477
10478With all these keywords, the same conventions are used. The <search> parameter
10479is a POSIX extended regular expression (regex) which supports grouping through
10480parenthesis (without the backslash). Spaces and other delimiters must be
10481prefixed with a backslash ('\') to avoid confusion with a field delimiter.
10482Other characters may be prefixed with a backslash to change their meaning :
10483
10484 \t for a tab
10485 \r for a carriage return (CR)
10486 \n for a new line (LF)
10487 \ to mark a space and differentiate it from a delimiter
10488 \# to mark a sharp and differentiate it from a comment
10489 \\ to use a backslash in a regex
10490 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
10491 \xXX to write the ASCII hex code XX as in the C language
10492
10493The <replace> parameter contains the string to be used to replace the largest
10494portion of text matching the regex. It can make use of the special characters
10495above, and can reference a substring which is delimited by parenthesis in the
10496regex, by writing a backslash ('\') immediately followed by one digit from 0 to
104979 indicating the group position (0 designating the entire line). This practice
10498is very common to users of the "sed" program.
10499
10500The <string> parameter represents the string which will systematically be added
10501after the last header line. It can also use special character sequences above.
10502
10503Notes related to these keywords :
10504---------------------------------
10505 - these keywords are not always convenient to allow/deny based on header
10506 contents. It is strongly recommended to use ACLs with the "block" keyword
10507 instead, resulting in far more flexible and manageable rules.
10508
10509 - lines are always considered as a whole. It is not possible to reference
10510 a header name only or a value only. This is important because of the way
10511 headers are written (notably the number of spaces after the colon).
10512
10513 - the first line is always considered as a header, which makes it possible to
10514 rewrite or filter HTTP requests URIs or response codes, but in turn makes
10515 it harder to distinguish between headers and request line. The regex prefix
10516 ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix
10517 ^[^ \t:]*: matches any header name followed by a colon.
10518
10519 - for performances reasons, the number of characters added to a request or to
10520 a response is limited at build time to values between 1 and 4 kB. This
10521 should normally be far more than enough for most usages. If it is too short
10522 on occasional usages, it is possible to gain some space by removing some
10523 useless headers before adding new ones.
10524
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010525 - keywords beginning with "reqi" and "rspi" are the same as their counterpart
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010526 without the 'i' letter except that they ignore case when matching patterns.
10527
10528 - when a request passes through a frontend then a backend, all req* rules
10529 from the frontend will be evaluated, then all req* rules from the backend
10530 will be evaluated. The reverse path is applied to responses.
10531
10532 - req* statements are applied after "block" statements, so that "block" is
10533 always the first one, but before "use_backend" in order to permit rewriting
Willy Tarreaud72758d2010-01-12 10:42:19 +010010534 before switching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010535
10536
Willy Tarreau74ca5042013-06-11 23:12:07 +0200105377. Using ACLs and fetching samples
10538----------------------------------
10539
10540Haproxy is capable of extracting data from request or response streams, from
10541client or server information, from tables, environmental information etc...
10542The action of extracting such data is called fetching a sample. Once retrieved,
10543these samples may be used for various purposes such as a key to a stick-table,
10544but most common usages consist in matching them against predefined constant
10545data called patterns.
10546
10547
105487.1. ACL basics
10549---------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010550
10551The use of Access Control Lists (ACL) provides a flexible solution to perform
10552content switching and generally to take decisions based on content extracted
10553from the request, the response or any environmental status. The principle is
10554simple :
10555
Willy Tarreau74ca5042013-06-11 23:12:07 +020010556 - extract a data sample from a stream, table or the environment
Willy Tarreaue6b11e42013-11-26 19:02:32 +010010557 - optionally apply some format conversion to the extracted sample
Willy Tarreau74ca5042013-06-11 23:12:07 +020010558 - apply one or multiple pattern matching methods on this sample
10559 - perform actions only when a pattern matches the sample
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010560
Willy Tarreau74ca5042013-06-11 23:12:07 +020010561The actions generally consist in blocking a request, selecting a backend, or
10562adding a header.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010563
10564In order to define a test, the "acl" keyword is used. The syntax is :
10565
Willy Tarreau74ca5042013-06-11 23:12:07 +020010566 acl <aclname> <criterion> [flags] [operator] [<value>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010567
10568This creates a new ACL <aclname> or completes an existing one with new tests.
10569Those tests apply to the portion of request/response specified in <criterion>
10570and may be adjusted with optional flags [flags]. Some criteria also support
Willy Tarreaue6b11e42013-11-26 19:02:32 +010010571an operator which may be specified before the set of values. Optionally some
10572conversion operators may be applied to the sample, and they will be specified
10573as a comma-delimited list of keywords just after the first keyword. The values
10574are of the type supported by the criterion, and are separated by spaces.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010575
10576ACL names must be formed from upper and lower case letters, digits, '-' (dash),
10577'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
10578which means that "my_acl" and "My_Acl" are two different ACLs.
10579
10580There is no enforced limit to the number of ACLs. The unused ones do not affect
10581performance, they just consume a small amount of memory.
10582
Willy Tarreau74ca5042013-06-11 23:12:07 +020010583The criterion generally is the name of a sample fetch method, or one of its ACL
10584specific declinations. The default test method is implied by the output type of
10585this sample fetch method. The ACL declinations can describe alternate matching
Willy Tarreaue6b11e42013-11-26 19:02:32 +010010586methods of a same sample fetch method. The sample fetch methods are the only
10587ones supporting a conversion.
Willy Tarreau74ca5042013-06-11 23:12:07 +020010588
10589Sample fetch methods return data which can be of the following types :
10590 - boolean
10591 - integer (signed or unsigned)
10592 - IPv4 or IPv6 address
10593 - string
10594 - data block
10595
Willy Tarreaue6b11e42013-11-26 19:02:32 +010010596Converters transform any of these data into any of these. For example, some
10597converters might convert a string to a lower-case string while other ones
10598would turn a string to an IPv4 address, or apply a netmask to an IP address.
10599The resulting sample is of the type of the last converter applied to the list,
10600which defaults to the type of the sample fetch method.
10601
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020010602Each sample or converter returns data of a specific type, specified with its
10603keyword in this documentation. When an ACL is declared using a standard sample
10604fetch method, certain types automatically involved a default matching method
10605which are summarized in the table below :
10606
10607 +---------------------+-----------------+
10608 | Sample or converter | Default |
10609 | output type | matching method |
10610 +---------------------+-----------------+
10611 | boolean | bool |
10612 +---------------------+-----------------+
10613 | integer | int |
10614 +---------------------+-----------------+
10615 | ip | ip |
10616 +---------------------+-----------------+
10617 | string | str |
10618 +---------------------+-----------------+
10619 | binary | none, use "-m" |
10620 +---------------------+-----------------+
10621
10622Note that in order to match a binary samples, it is mandatory to specify a
10623matching method, see below.
10624
Willy Tarreau74ca5042013-06-11 23:12:07 +020010625The ACL engine can match these types against patterns of the following types :
10626 - boolean
10627 - integer or integer range
10628 - IP address / network
10629 - string (exact, substring, suffix, prefix, subdir, domain)
10630 - regular expression
10631 - hex block
10632
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010633The following ACL flags are currently supported :
10634
Willy Tarreau2b5285d2010-05-09 23:45:24 +020010635 -i : ignore case during matching of all subsequent patterns.
10636 -f : load patterns from a file.
Willy Tarreau74ca5042013-06-11 23:12:07 +020010637 -m : use a specific pattern matching method
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010010638 -n : forbid the DNS resolutions
Thierry FOURNIER9860c412014-01-29 14:23:29 +010010639 -M : load the file pointed by -f like a map file.
Thierry FOURNIER3534d882014-01-20 17:01:44 +010010640 -u : force the unique id of the ACL
Willy Tarreau6a06a402007-07-15 20:15:28 +020010641 -- : force end of flags. Useful when a string looks like one of the flags.
10642
Willy Tarreau74ca5042013-06-11 23:12:07 +020010643The "-f" flag is followed by the name of a file from which all lines will be
10644read as individual values. It is even possible to pass multiple "-f" arguments
10645if the patterns are to be loaded from multiple files. Empty lines as well as
10646lines beginning with a sharp ('#') will be ignored. All leading spaces and tabs
10647will be stripped. If it is absolutely necessary to insert a valid pattern
10648beginning with a sharp, just prefix it with a space so that it is not taken for
10649a comment. Depending on the data type and match method, haproxy may load the
10650lines into a binary tree, allowing very fast lookups. This is true for IPv4 and
10651exact string matching. In this case, duplicates will automatically be removed.
10652
Thierry FOURNIER9860c412014-01-29 14:23:29 +010010653The "-M" flag allows an ACL to use a map file. If this flag is set, the file is
10654parsed as two column file. The first column contains the patterns used by the
10655ACL, and the second column contain the samples. The sample can be used later by
10656a map. This can be useful in some rare cases where an ACL would just be used to
10657check for the existence of a pattern in a map before a mapping is applied.
10658
Thierry FOURNIER3534d882014-01-20 17:01:44 +010010659The "-u" flag forces the unique id of the ACL. This unique id is used with the
10660socket interface to identify ACL and dynamically change its values. Note that a
10661file is always identified by its name even if an id is set.
10662
Willy Tarreau74ca5042013-06-11 23:12:07 +020010663Also, note that the "-i" flag applies to subsequent entries and not to entries
10664loaded from files preceding it. For instance :
10665
10666 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
10667
10668In this example, each line of "exact-ua.lst" will be exactly matched against
10669the "user-agent" header of the request. Then each line of "generic-ua" will be
10670case-insensitively matched. Then the word "test" will be insensitively matched
10671as well.
10672
10673The "-m" flag is used to select a specific pattern matching method on the input
10674sample. All ACL-specific criteria imply a pattern matching method and generally
10675do not need this flag. However, this flag is useful with generic sample fetch
10676methods to describe how they're going to be matched against the patterns. This
10677is required for sample fetches which return data type for which there is no
10678obvious matching method (eg: string or binary). When "-m" is specified and
10679followed by a pattern matching method name, this method is used instead of the
10680default one for the criterion. This makes it possible to match contents in ways
10681that were not initially planned, or with sample fetch methods which return a
10682string. The matching method also affects the way the patterns are parsed.
10683
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010010684The "-n" flag forbids the dns resolutions. It is used with the load of ip files.
10685By default, if the parser cannot parse ip address it considers that the parsed
10686string is maybe a domain name and try dns resolution. The flag "-n" disable this
10687resolution. It is useful for detecting malformed ip lists. Note that if the DNS
10688server is not reachable, the haproxy configuration parsing may last many minutes
10689waiting fir the timeout. During this time no error messages are displayed. The
10690flag "-n" disable this behavior. Note also that during the runtime, this
10691function is disabled for the dynamic acl modifications.
10692
Willy Tarreau74ca5042013-06-11 23:12:07 +020010693There are some restrictions however. Not all methods can be used with all
10694sample fetch methods. Also, if "-m" is used in conjunction with "-f", it must
10695be placed first. The pattern matching method must be one of the following :
Willy Tarreau5adeda12013-03-31 22:13:34 +020010696
10697 - "found" : only check if the requested sample could be found in the stream,
10698 but do not compare it against any pattern. It is recommended not
Willy Tarreau74ca5042013-06-11 23:12:07 +020010699 to pass any pattern to avoid confusion. This matching method is
10700 particularly useful to detect presence of certain contents such
10701 as headers, cookies, etc... even if they are empty and without
10702 comparing them to anything nor counting them.
Willy Tarreau5adeda12013-03-31 22:13:34 +020010703
10704 - "bool" : check the value as a boolean. It can only be applied to fetches
10705 which return a boolean or integer value, and takes no pattern.
Willy Tarreau74ca5042013-06-11 23:12:07 +020010706 Value zero or false does not match, all other values do match.
Willy Tarreau5adeda12013-03-31 22:13:34 +020010707
10708 - "int" : match the value as an integer. It can be used with integer and
Willy Tarreau74ca5042013-06-11 23:12:07 +020010709 boolean samples. Boolean false is integer 0, true is integer 1.
Willy Tarreau5adeda12013-03-31 22:13:34 +020010710
10711 - "ip" : match the value as an IPv4 or IPv6 address. It is compatible
Willy Tarreau74ca5042013-06-11 23:12:07 +020010712 with IP address samples only, so it is implied and never needed.
Willy Tarreau5adeda12013-03-31 22:13:34 +020010713
10714 - "bin" : match the contents against an hexadecimal string representing a
10715 binary sequence. This may be used with binary or string samples.
10716
10717 - "len" : match the sample's length as an integer. This may be used with
10718 binary or string samples.
10719
Willy Tarreau74ca5042013-06-11 23:12:07 +020010720 - "str" : exact match : match the contents against a string. This may be
10721 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020010722
Willy Tarreau74ca5042013-06-11 23:12:07 +020010723 - "sub" : substring match : check that the contents contain at least one of
10724 the provided string patterns. This may be used with binary or
10725 string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020010726
Willy Tarreau74ca5042013-06-11 23:12:07 +020010727 - "reg" : regex match : match the contents against a list of regular
10728 expressions. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020010729
Willy Tarreau74ca5042013-06-11 23:12:07 +020010730 - "beg" : prefix match : check that the contents begin like the provided
10731 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020010732
Willy Tarreau74ca5042013-06-11 23:12:07 +020010733 - "end" : suffix match : check that the contents end like the provided
10734 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020010735
Willy Tarreau74ca5042013-06-11 23:12:07 +020010736 - "dir" : subdir match : check that a slash-delimited portion of the
10737 contents exactly matches one of the provided string patterns.
Willy Tarreau5adeda12013-03-31 22:13:34 +020010738 This may be used with binary or string samples.
10739
Willy Tarreau74ca5042013-06-11 23:12:07 +020010740 - "dom" : domain match : check that a dot-delimited portion of the contents
10741 exactly match one of the provided string patterns. This may be
10742 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020010743
10744For example, to quickly detect the presence of cookie "JSESSIONID" in an HTTP
10745request, it is possible to do :
10746
10747 acl jsess_present cook(JSESSIONID) -m found
10748
10749In order to apply a regular expression on the 500 first bytes of data in the
10750buffer, one would use the following acl :
10751
10752 acl script_tag payload(0,500) -m reg -i <script>
10753
Willy Tarreaue6b11e42013-11-26 19:02:32 +010010754On systems where the regex library is much slower when using "-i", it is
10755possible to convert the sample to lowercase before matching, like this :
10756
10757 acl script_tag payload(0,500),lower -m reg <script>
10758
Willy Tarreau74ca5042013-06-11 23:12:07 +020010759All ACL-specific criteria imply a default matching method. Most often, these
10760criteria are composed by concatenating the name of the original sample fetch
10761method and the matching method. For example, "hdr_beg" applies the "beg" match
10762to samples retrieved using the "hdr" fetch method. Since all ACL-specific
10763criteria rely on a sample fetch method, it is always possible instead to use
10764the original sample fetch method and the explicit matching method using "-m".
Willy Tarreau2b5285d2010-05-09 23:45:24 +020010765
Willy Tarreau74ca5042013-06-11 23:12:07 +020010766If an alternate match is specified using "-m" on an ACL-specific criterion,
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010767the matching method is simply applied to the underlying sample fetch method.
10768For example, all ACLs below are exact equivalent :
Willy Tarreau2b5285d2010-05-09 23:45:24 +020010769
Willy Tarreau74ca5042013-06-11 23:12:07 +020010770 acl short_form hdr_beg(host) www.
10771 acl alternate1 hdr_beg(host) -m beg www.
10772 acl alternate2 hdr_dom(host) -m beg www.
10773 acl alternate3 hdr(host) -m beg www.
Willy Tarreau2b5285d2010-05-09 23:45:24 +020010774
Willy Tarreau2b5285d2010-05-09 23:45:24 +020010775
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020010776The table below summarizes the compatibility matrix between sample or converter
10777types and the pattern types to fetch against. It indicates for each compatible
10778combination the name of the matching method to be used, surrounded with angle
10779brackets ">" and "<" when the method is the default one and will work by
10780default without "-m".
Willy Tarreau0ba27502007-12-24 16:55:16 +010010781
Willy Tarreau74ca5042013-06-11 23:12:07 +020010782 +-------------------------------------------------+
10783 | Input sample type |
10784 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020010785 | pattern type | boolean | integer | ip | string | binary |
Willy Tarreau74ca5042013-06-11 23:12:07 +020010786 +----------------------+---------+---------+---------+---------+---------+
10787 | none (presence only) | found | found | found | found | found |
10788 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020010789 | none (boolean value) |> bool <| bool | | bool | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020010790 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020010791 | integer (value) | int |> int <| int | int | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020010792 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010010793 | integer (length) | len | len | len | len | len |
Willy Tarreau74ca5042013-06-11 23:12:07 +020010794 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020010795 | IP address | | |> ip <| ip | ip |
Willy Tarreau74ca5042013-06-11 23:12:07 +020010796 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020010797 | exact string | str | str | str |> str <| str |
Willy Tarreau74ca5042013-06-11 23:12:07 +020010798 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010010799 | prefix | beg | beg | beg | beg | beg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020010800 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010010801 | suffix | end | end | end | end | end |
Willy Tarreau74ca5042013-06-11 23:12:07 +020010802 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010010803 | substring | sub | sub | sub | sub | sub |
Willy Tarreau74ca5042013-06-11 23:12:07 +020010804 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010010805 | subdir | dir | dir | dir | dir | dir |
Willy Tarreau74ca5042013-06-11 23:12:07 +020010806 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010010807 | domain | dom | dom | dom | dom | dom |
Willy Tarreau74ca5042013-06-11 23:12:07 +020010808 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010010809 | regex | reg | reg | reg | reg | reg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020010810 +----------------------+---------+---------+---------+---------+---------+
10811 | hex block | | | | bin | bin |
10812 +----------------------+---------+---------+---------+---------+---------+
Willy Tarreau6a06a402007-07-15 20:15:28 +020010813
10814
Willy Tarreau74ca5042013-06-11 23:12:07 +0200108157.1.1. Matching booleans
10816------------------------
10817
10818In order to match a boolean, no value is needed and all values are ignored.
10819Boolean matching is used by default for all fetch methods of type "boolean".
10820When boolean matching is used, the fetched value is returned as-is, which means
10821that a boolean "true" will always match and a boolean "false" will never match.
10822
10823Boolean matching may also be enforced using "-m bool" on fetch methods which
10824return an integer value. Then, integer value 0 is converted to the boolean
10825"false" and all other values are converted to "true".
10826
Willy Tarreau6a06a402007-07-15 20:15:28 +020010827
Willy Tarreau74ca5042013-06-11 23:12:07 +0200108287.1.2. Matching integers
10829------------------------
10830
10831Integer matching applies by default to integer fetch methods. It can also be
10832enforced on boolean fetches using "-m int". In this case, "false" is converted
10833to the integer 0, and "true" is converted to the integer 1.
10834
10835Integer matching also supports integer ranges and operators. Note that integer
10836matching only applies to positive values. A range is a value expressed with a
10837lower and an upper bound separated with a colon, both of which may be omitted.
Willy Tarreau6a06a402007-07-15 20:15:28 +020010838
10839For instance, "1024:65535" is a valid range to represent a range of
10840unprivileged ports, and "1024:" would also work. "0:1023" is a valid
10841representation of privileged ports, and ":1023" would also work.
10842
Willy Tarreau62644772008-07-16 18:36:06 +020010843As a special case, some ACL functions support decimal numbers which are in fact
10844two integers separated by a dot. This is used with some version checks for
10845instance. All integer properties apply to those decimal numbers, including
10846ranges and operators.
10847
Willy Tarreau6a06a402007-07-15 20:15:28 +020010848For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +010010849operators with ranges does not make much sense and is strongly discouraged.
10850Similarly, it does not make much sense to perform order comparisons with a set
10851of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +020010852
Willy Tarreau0ba27502007-12-24 16:55:16 +010010853Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +020010854
10855 eq : true if the tested value equals at least one value
10856 ge : true if the tested value is greater than or equal to at least one value
10857 gt : true if the tested value is greater than at least one value
10858 le : true if the tested value is less than or equal to at least one value
10859 lt : true if the tested value is less than at least one value
10860
Willy Tarreau0ba27502007-12-24 16:55:16 +010010861For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +020010862
10863 acl negative-length hdr_val(content-length) lt 0
10864
Willy Tarreau62644772008-07-16 18:36:06 +020010865This one matches SSL versions between 3.0 and 3.1 (inclusive) :
10866
10867 acl sslv3 req_ssl_ver 3:3.1
10868
Willy Tarreau6a06a402007-07-15 20:15:28 +020010869
Willy Tarreau74ca5042013-06-11 23:12:07 +0200108707.1.3. Matching strings
10871-----------------------
10872
10873String matching applies to string or binary fetch methods, and exists in 6
10874different forms :
10875
10876 - exact match (-m str) : the extracted string must exactly match the
10877 patterns ;
10878
10879 - substring match (-m sub) : the patterns are looked up inside the
10880 extracted string, and the ACL matches if any of them is found inside ;
10881
10882 - prefix match (-m beg) : the patterns are compared with the beginning of
10883 the extracted string, and the ACL matches if any of them matches.
10884
10885 - suffix match (-m end) : the patterns are compared with the end of the
10886 extracted string, and the ACL matches if any of them matches.
10887
10888 - subdir match (-m sub) : the patterns are looked up inside the extracted
10889 string, delimited with slashes ("/"), and the ACL matches if any of them
10890 matches.
10891
10892 - domain match (-m dom) : the patterns are looked up inside the extracted
10893 string, delimited with dots ("."), and the ACL matches if any of them
10894 matches.
Willy Tarreau6a06a402007-07-15 20:15:28 +020010895
10896String matching applies to verbatim strings as they are passed, with the
10897exception of the backslash ("\") which makes it possible to escape some
10898characters such as the space. If the "-i" flag is passed before the first
10899string, then the matching will be performed ignoring the case. In order
10900to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +010010901before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020010902
10903
Willy Tarreau74ca5042013-06-11 23:12:07 +0200109047.1.4. Matching regular expressions (regexes)
10905---------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020010906
10907Just like with string matching, regex matching applies to verbatim strings as
10908they are passed, with the exception of the backslash ("\") which makes it
10909possible to escape some characters such as the space. If the "-i" flag is
10910passed before the first regex, then the matching will be performed ignoring
10911the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +010010912the "--" flag before the first string. Same principle applies of course to
10913match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020010914
10915
Willy Tarreau74ca5042013-06-11 23:12:07 +0200109167.1.5. Matching arbitrary data blocks
10917-------------------------------------
10918
10919It is possible to match some extracted samples against a binary block which may
10920not safely be represented as a string. For this, the patterns must be passed as
10921a series of hexadecimal digits in an even number, when the match method is set
10922to binary. Each sequence of two digits will represent a byte. The hexadecimal
10923digits may be used upper or lower case.
10924
10925Example :
10926 # match "Hello\n" in the input stream (\x48 \x65 \x6c \x6c \x6f \x0a)
10927 acl hello payload(0,6) -m bin 48656c6c6f0a
10928
10929
109307.1.6. Matching IPv4 and IPv6 addresses
10931---------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020010932
10933IPv4 addresses values can be specified either as plain addresses or with a
10934netmask appended, in which case the IPv4 address matches whenever it is
10935within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010010936host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +010010937difficult to read and debug configurations. If hostnames are used, you should
10938at least ensure that they are present in /etc/hosts so that the configuration
10939does not depend on any random DNS match at the moment the configuration is
10940parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +020010941
Willy Tarreauceb4ac92012-04-28 00:41:46 +020010942IPv6 may be entered in their usual form, with or without a netmask appended.
10943Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of
10944trouble with randomly resolved IP addresses, host names are never allowed in
10945IPv6 patterns.
10946
10947HAProxy is also able to match IPv4 addresses with IPv6 addresses in the
10948following situations :
10949 - tested address is IPv4, pattern address is IPv4, the match applies
10950 in IPv4 using the supplied mask if any.
10951 - tested address is IPv6, pattern address is IPv6, the match applies
10952 in IPv6 using the supplied mask if any.
10953 - tested address is IPv6, pattern address is IPv4, the match applies in IPv4
10954 using the pattern's mask if the IPv6 address matches with 2002:IPV4::,
10955 ::IPV4 or ::ffff:IPV4, otherwise it fails.
10956 - tested address is IPv4, pattern address is IPv6, the IPv4 address is first
10957 converted to IPv6 by prefixing ::ffff: in front of it, then the match is
10958 applied in IPv6 using the supplied IPv6 mask.
10959
Willy Tarreau74ca5042013-06-11 23:12:07 +020010960
109617.2. Using ACLs to form conditions
10962----------------------------------
10963
10964Some actions are only performed upon a valid condition. A condition is a
10965combination of ACLs with operators. 3 operators are supported :
10966
10967 - AND (implicit)
10968 - OR (explicit with the "or" keyword or the "||" operator)
10969 - Negation with the exclamation mark ("!")
Willy Tarreau6a06a402007-07-15 20:15:28 +020010970
Willy Tarreau74ca5042013-06-11 23:12:07 +020010971A condition is formed as a disjunctive form:
Willy Tarreau6a06a402007-07-15 20:15:28 +020010972
Willy Tarreau74ca5042013-06-11 23:12:07 +020010973 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreaubef91e72013-03-31 23:14:46 +020010974
Willy Tarreau74ca5042013-06-11 23:12:07 +020010975Such conditions are generally used after an "if" or "unless" statement,
10976indicating when the condition will trigger the action.
Willy Tarreaubef91e72013-03-31 23:14:46 +020010977
Willy Tarreau74ca5042013-06-11 23:12:07 +020010978For instance, to block HTTP requests to the "*" URL with methods other than
10979"OPTIONS", as well as POST requests without content-length, and GET or HEAD
10980requests with a content-length greater than 0, and finally every request which
10981is not either GET/HEAD/POST/OPTIONS !
10982
10983 acl missing_cl hdr_cnt(Content-length) eq 0
10984 block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
10985 block if METH_GET HTTP_CONTENT
10986 block unless METH_GET or METH_POST or METH_OPTIONS
10987
10988To select a different backend for requests to static contents on the "www" site
10989and to every request on the "img", "video", "download" and "ftp" hosts :
10990
10991 acl url_static path_beg /static /images /img /css
10992 acl url_static path_end .gif .png .jpg .css .js
10993 acl host_www hdr_beg(host) -i www
10994 acl host_static hdr_beg(host) -i img. video. download. ftp.
10995
10996 # now use backend "static" for all static-only hosts, and for static urls
10997 # of host "www". Use backend "www" for the rest.
10998 use_backend static if host_static or host_www url_static
10999 use_backend www if host_www
11000
11001It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
11002expressions that are built on the fly without needing to be declared. They must
11003be enclosed between braces, with a space before and after each brace (because
11004the braces must be seen as independent words). Example :
11005
11006 The following rule :
11007
11008 acl missing_cl hdr_cnt(Content-length) eq 0
11009 block if METH_POST missing_cl
11010
11011 Can also be written that way :
11012
11013 block if METH_POST { hdr_cnt(Content-length) eq 0 }
11014
11015It is generally not recommended to use this construct because it's a lot easier
11016to leave errors in the configuration when written that way. However, for very
11017simple rules matching only one source IP address for instance, it can make more
11018sense to use them than to declare ACLs with random names. Another example of
11019good use is the following :
11020
11021 With named ACLs :
11022
11023 acl site_dead nbsrv(dynamic) lt 2
11024 acl site_dead nbsrv(static) lt 2
11025 monitor fail if site_dead
11026
11027 With anonymous ACLs :
11028
11029 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
11030
11031See section 4.2 for detailed help on the "block" and "use_backend" keywords.
11032
11033
110347.3. Fetching samples
11035---------------------
11036
11037Historically, sample fetch methods were only used to retrieve data to match
11038against patterns using ACLs. With the arrival of stick-tables, a new class of
11039sample fetch methods was created, most often sharing the same syntax as their
11040ACL counterpart. These sample fetch methods are also known as "fetches". As
11041of now, ACLs and fetches have converged. All ACL fetch methods have been made
11042available as fetch methods, and ACLs may use any sample fetch method as well.
11043
11044This section details all available sample fetch methods and their output type.
11045Some sample fetch methods have deprecated aliases that are used to maintain
11046compatibility with existing configurations. They are then explicitly marked as
11047deprecated and should not be used in new setups.
11048
11049The ACL derivatives are also indicated when available, with their respective
11050matching methods. These ones all have a well defined default pattern matching
11051method, so it is never necessary (though allowed) to pass the "-m" option to
11052indicate how the sample will be matched using ACLs.
11053
11054As indicated in the sample type versus matching compatibility matrix above,
11055when using a generic sample fetch method in an ACL, the "-m" option is
11056mandatory unless the sample type is one of boolean, integer, IPv4 or IPv6. When
11057the same keyword exists as an ACL keyword and as a standard fetch method, the
11058ACL engine will automatically pick the ACL-only one by default.
11059
11060Some of these keywords support one or multiple mandatory arguments, and one or
11061multiple optional arguments. These arguments are strongly typed and are checked
11062when the configuration is parsed so that there is no risk of running with an
11063incorrect argument (eg: an unresolved backend name). Fetch function arguments
11064are passed between parenthesis and are delimited by commas. When an argument
11065is optional, it will be indicated below between square brackets ('[ ]'). When
11066all arguments are optional, the parenthesis may be omitted.
11067
11068Thus, the syntax of a standard sample fetch method is one of the following :
11069 - name
11070 - name(arg1)
11071 - name(arg1,arg2)
11072
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011073
110747.3.1. Converters
11075-----------------
11076
Willy Tarreaue6b11e42013-11-26 19:02:32 +010011077Sample fetch methods may be combined with transformations to be applied on top
11078of the fetched sample (also called "converters"). These combinations form what
11079is called "sample expressions" and the result is a "sample". Initially this
11080was only supported by "stick on" and "stick store-request" directives but this
11081has now be extended to all places where samples may be used (acls, log-format,
11082unique-id-format, add-header, ...).
11083
11084These transformations are enumerated as a series of specific keywords after the
11085sample fetch method. These keywords may equally be appended immediately after
11086the fetch keyword's argument, delimited by a comma. These keywords can also
11087support some arguments (eg: a netmask) which must be passed in parenthesis.
Willy Tarreau0ba27502007-12-24 16:55:16 +010011088
Willy Tarreau97707872015-01-27 15:12:13 +010011089A certain category of converters are bitwise and arithmetic operators which
11090support performing basic operations on integers. Some bitwise operations are
11091supported (and, or, xor, cpl) and some arithmetic operations are supported
11092(add, sub, mul, div, mod, neg). Some comparators are provided (odd, even, not,
11093bool) which make it possible to report a match without having to write an ACL.
11094
Willy Tarreau74ca5042013-06-11 23:12:07 +020011095The currently available list of transformation keywords include :
Willy Tarreau0ba27502007-12-24 16:55:16 +010011096
Willy Tarreau97707872015-01-27 15:12:13 +010011097add(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011098 Adds <value> to the input value of type signed integer, and returns the
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020011099 result as a signed integer. <value> can be a numeric value or a variable
11100 name. The name of the variable starts by an indication about its scope. The
11101 allowed scopes are:
11102 "sess" : the variable is shared with all the session,
11103 "txn" : the variable is shared with all the transaction (request and
11104 response),
11105 "req" : the variable is shared only during the request processing,
11106 "res" : the variable is shared only during the response processing.
11107 This prefix is followed by a name. The separator is a '.'. The name may only
11108 contain characters 'a-z', 'A-Z', '0-9' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010011109
11110and(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011111 Performs a bitwise "AND" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020011112 integer, and returns the result as an signed integer. <value> can be a
11113 numeric value or a variable name. The name of the variable starts by an
11114 indication about its scope. The allowed scopes are:
11115 "sess" : the variable is shared with all the session,
11116 "txn" : the variable is shared with all the transaction (request and
11117 response),
11118 "req" : the variable is shared only during the request processing,
11119 "res" : the variable is shared only during the response processing.
11120 This prefix is followed by a name. The separator is a '.'. The name may only
11121 contain characters 'a-z', 'A-Z', '0-9' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010011122
Emeric Brun53d1a982014-04-30 18:21:37 +020011123base64
11124 Converts a binary input sample to a base64 string. It is used to log or
11125 transfer binary content in a way that can be reliably transferred (eg:
11126 an SSL ID can be copied in a header).
11127
Willy Tarreau97707872015-01-27 15:12:13 +010011128bool
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011129 Returns a boolean TRUE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010011130 non-null, otherwise returns FALSE. Used in conjunction with and(), it can be
11131 used to report true/false for bit testing on input values (eg: verify the
11132 presence of a flag).
11133
Emeric Brun54c4ac82014-11-03 15:32:43 +010011134bytes(<offset>[,<length>])
11135 Extracts some bytes from an input binary sample. The result is a binary
11136 sample starting at an offset (in bytes) of the original sample and
11137 optionnaly truncated at the given length.
11138
Willy Tarreau97707872015-01-27 15:12:13 +010011139cpl
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011140 Takes the input value of type signed integer, applies a ones-complement
11141 (flips all bits) and returns the result as an signed integer.
Willy Tarreau97707872015-01-27 15:12:13 +010011142
Willy Tarreau80599772015-01-20 19:35:24 +010011143crc32([<avalanche>])
11144 Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32
11145 hash function. Optionally, it is possible to apply a full avalanche hash
11146 function to the output if the optional <avalanche> argument equals 1. This
11147 converter uses the same functions as used by the various hash-based load
11148 balancing algorithms, so it will provide exactly the same results. It is
11149 provided for compatibility with other software which want a CRC32 to be
11150 computed on some input keys, so it follows the most common implementation as
11151 found in Ethernet, Gzip, PNG, etc... It is slower than the other algorithms
11152 but may provide a better or at least less predictable distribution. It must
11153 not be used for security purposes as a 32-bit hash is trivial to break. See
11154 also "djb2", "sdbm", "wt6" and the "hash-type" directive.
11155
David Carlier4542b102015-06-01 13:54:29 +020011156da-csv(<prop>[,<prop>*])
11157 Asks the DeviceAtlas converter to identify the User Agent string passed on
11158 input, and to emit a string made of the concatenation of the properties
11159 enumerated in argument, delimited by the separator defined by the global
11160 keyword "deviceatlas-property-separator", or by default the pipe character
11161 ('|'). There's a limit of 5 different properties imposed by the haproxy
11162 configuration language.
11163
11164 Example:
11165 frontend www
11166 bind *:8881
11167 default_backend servers
11168 http-request set-header X-DeviceAtlas-Data %[req.fhdr(User-Agent),da-csv(primaryHardwareType,osName,osVersion,browserName,browserVersion)]
11169
Thierry FOURNIER9687c772015-05-07 15:46:29 +020011170debug
11171 This converter is used as debug tool. It dumps on screen the content and the
11172 type of the input sample. The sample is returned as is on its output. This
11173 converter only exists when haproxy was built with debugging enabled.
11174
Willy Tarreau97707872015-01-27 15:12:13 +010011175div(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011176 Divides the input value of type signed integer by <value>, and returns the
11177 result as an signed integer. If <value> is null, the largest unsigned
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020011178 integer is returned (typically 2^63-1). <value> can be a numeric value or a
11179 variable name. The name of the variable starts by an indication about it
11180 scope. The scope allowed are:
11181 "sess" : the variable is shared with all the session,
11182 "txn" : the variable is shared with all the transaction (request and
11183 response),
11184 "req" : the variable is shared only during the request processing,
11185 "res" : the variable is shared only during the response processing.
11186 This prefix is followed by a name. The separator is a '.'. The name may only
11187 contain characters 'a-z', 'A-Z', '0-9' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010011188
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020011189djb2([<avalanche>])
11190 Hashes a binary input sample into an unsigned 32-bit quantity using the DJB2
11191 hash function. Optionally, it is possible to apply a full avalanche hash
11192 function to the output if the optional <avalanche> argument equals 1. This
11193 converter uses the same functions as used by the various hash-based load
11194 balancing algorithms, so it will provide exactly the same results. It is
11195 mostly intended for debugging, but can be used as a stick-table entry to
11196 collect rough statistics. It must not be used for security purposes as a
Willy Tarreau80599772015-01-20 19:35:24 +010011197 32-bit hash is trivial to break. See also "crc32", "sdbm", "wt6" and the
11198 "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020011199
Willy Tarreau97707872015-01-27 15:12:13 +010011200even
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011201 Returns a boolean TRUE if the input value of type signed integer is even
Willy Tarreau97707872015-01-27 15:12:13 +010011202 otherwise returns FALSE. It is functionally equivalent to "not,and(1),bool".
11203
Emeric Brunf399b0d2014-11-03 17:07:03 +010011204field(<index>,<delimiters>)
11205 Extracts the substring at the given index considering given delimiters from
11206 an input string. Indexes start at 1 and delimiters are a string formatted
11207 list of chars.
11208
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011209hex
11210 Converts a binary input sample to an hex string containing two hex digits per
11211 input byte. It is used to log or transfer hex dumps of some binary input data
11212 in a way that can be reliably transferred (eg: an SSL ID can be copied in a
11213 header).
Thierry FOURNIER2f49d6d2014-03-12 15:01:52 +010011214
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011215http_date([<offset>])
11216 Converts an integer supposed to contain a date since epoch to a string
11217 representing this date in a format suitable for use in HTTP header fields. If
11218 an offset value is specified, then it is a number of seconds that is added to
11219 the date before the conversion is operated. This is particularly useful to
11220 emit Date header fields, Expires values in responses when combined with a
11221 positive offset, or Last-Modified values when the offset is negative.
Willy Tarreau74ca5042013-06-11 23:12:07 +020011222
Willy Tarreaud9f316a2014-07-10 14:03:38 +020011223in_table(<table>)
11224 Uses the string representation of the input sample to perform a look up in
11225 the specified table. If the key is not found in the table, a boolean false
11226 is returned. Otherwise a boolean true is returned. This can be used to verify
11227 the presence of a certain key in a table tracking some elements (eg: whether
11228 or not a source IP address or an Authorization header was already seen).
11229
Willy Tarreauffcb2e42014-07-10 16:29:08 +020011230ipmask(<mask>)
11231 Apply a mask to an IPv4 address, and use the result for lookups and storage.
11232 This can be used to make all hosts within a certain mask to share the same
11233 table entries and as such use the same server. The mask can be passed in
11234 dotted form (eg: 255.255.255.0) or in CIDR form (eg: 24).
11235
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020011236json([<input-code>])
11237 Escapes the input string and produces an ASCII ouput string ready to use as a
11238 JSON string. The converter tries to decode the input string according to the
11239 <input-code> parameter. It can be "ascii", "utf8", "utf8s", "utf8"" or
11240 "utf8ps". The "ascii" decoder never fails. The "utf8" decoder detects 3 types
11241 of errors:
11242 - bad UTF-8 sequence (lone continuation byte, bad number of continuation
11243 bytes, ...)
11244 - invalid range (the decoded value is within a UTF-8 prohibited range),
11245 - code overlong (the value is encoded with more bytes than necessary).
11246
11247 The UTF-8 JSON encoding can produce a "too long value" error when the UTF-8
11248 character is greater than 0xffff because the JSON string escape specification
11249 only authorizes 4 hex digits for the value encoding. The UTF-8 decoder exists
11250 in 4 variants designated by a combination of two suffix letters : "p" for
11251 "permissive" and "s" for "silently ignore". The behaviors of the decoders
11252 are :
11253 - "ascii" : never fails ;
11254 - "utf8" : fails on any detected errors ;
11255 - "utf8s" : never fails, but removes characters corresponding to errors ;
11256 - "utf8p" : accepts and fixes the overlong errors, but fails on any other
11257 error ;
11258 - "utf8ps" : never fails, accepts and fixes the overlong errors, but removes
11259 characters corresponding to the other errors.
11260
11261 This converter is particularly useful for building properly escaped JSON for
11262 logging to servers which consume JSON-formated traffic logs.
11263
11264 Example:
11265 capture request header user-agent len 150
11266 capture request header Host len 15
11267 log-format {"ip":"%[src]","user-agent":"%[capture.req.hdr(1),json]"}
11268
11269 Input request from client 127.0.0.1:
11270 GET / HTTP/1.0
11271 User-Agent: Very "Ugly" UA 1/2
11272
11273 Output log:
11274 {"ip":"127.0.0.1","user-agent":"Very \"Ugly\" UA 1\/2"}
11275
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011276language(<value>[,<default>])
11277 Returns the value with the highest q-factor from a list as extracted from the
11278 "accept-language" header using "req.fhdr". Values with no q-factor have a
11279 q-factor of 1. Values with a q-factor of 0 are dropped. Only values which
11280 belong to the list of semi-colon delimited <values> will be considered. The
11281 argument <value> syntax is "lang[;lang[;lang[;...]]]". If no value matches the
11282 given list and a default value is provided, it is returned. Note that language
11283 names may have a variant after a dash ('-'). If this variant is present in the
11284 list, it will be matched, but if it is not, only the base language is checked.
11285 The match is case-sensitive, and the output string is always one of those
11286 provided in arguments. The ordering of arguments is meaningless, only the
11287 ordering of the values in the request counts, as the first value among
11288 multiple sharing the same q-factor is used.
Thierry FOURNIERad903512014-04-11 17:51:01 +020011289
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011290 Example :
Thierry FOURNIERad903512014-04-11 17:51:01 +020011291
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011292 # this configuration switches to the backend matching a
11293 # given language based on the request :
Thierry FOURNIERad903512014-04-11 17:51:01 +020011294
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011295 acl es req.fhdr(accept-language),language(es;fr;en) -m str es
11296 acl fr req.fhdr(accept-language),language(es;fr;en) -m str fr
11297 acl en req.fhdr(accept-language),language(es;fr;en) -m str en
11298 use_backend spanish if es
11299 use_backend french if fr
11300 use_backend english if en
11301 default_backend choose_your_language
Thierry FOURNIERad903512014-04-11 17:51:01 +020011302
Willy Tarreauffcb2e42014-07-10 16:29:08 +020011303lower
11304 Convert a string sample to lower case. This can only be placed after a string
11305 sample fetch function or after a transformation keyword returning a string
11306 type. The result is of type string.
11307
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020011308ltime(<format>[,<offset>])
11309 Converts an integer supposed to contain a date since epoch to a string
11310 representing this date in local time using a format defined by the <format>
11311 string using strftime(3). The purpose is to allow any date format to be used
11312 in logs. An optional <offset> in seconds may be applied to the input date
11313 (positive or negative). See the strftime() man page for the format supported
11314 by your operating system. See also the utime converter.
11315
11316 Example :
11317
11318 # Emit two colons, one with the local time and another with ip:port
11319 # Eg: 20140710162350 127.0.0.1:57325
11320 log-format %[date,ltime(%Y%m%d%H%M%S)]\ %ci:%cp
11321
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011322map(<map_file>[,<default_value>])
11323map_<match_type>(<map_file>[,<default_value>])
11324map_<match_type>_<output_type>(<map_file>[,<default_value>])
11325 Search the input value from <map_file> using the <match_type> matching method,
11326 and return the associated value converted to the type <output_type>. If the
11327 input value cannot be found in the <map_file>, the converter returns the
11328 <default_value>. If the <default_value> is not set, the converter fails and
11329 acts as if no input value could be fetched. If the <match_type> is not set, it
11330 defaults to "str". Likewise, if the <output_type> is not set, it defaults to
11331 "str". For convenience, the "map" keyword is an alias for "map_str" and maps a
11332 string to another string.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010011333
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011334 It is important to avoid overlapping between the keys : IP addresses and
11335 strings are stored in trees, so the first of the finest match will be used.
11336 Other keys are stored in lists, so the first matching occurrence will be used.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010011337
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011338 The following array contains the list of all map functions avalaible sorted by
11339 input type, match type and output type.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010011340
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011341 input type | match method | output type str | output type int | output type ip
11342 -----------+--------------+-----------------+-----------------+---------------
11343 str | str | map_str | map_str_int | map_str_ip
11344 -----------+--------------+-----------------+-----------------+---------------
Willy Tarreau787a4c02014-05-10 07:55:30 +020011345 str | beg | map_beg | map_beg_int | map_end_ip
11346 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011347 str | sub | map_sub | map_sub_int | map_sub_ip
11348 -----------+--------------+-----------------+-----------------+---------------
11349 str | dir | map_dir | map_dir_int | map_dir_ip
11350 -----------+--------------+-----------------+-----------------+---------------
11351 str | dom | map_dom | map_dom_int | map_dom_ip
11352 -----------+--------------+-----------------+-----------------+---------------
11353 str | end | map_end | map_end_int | map_end_ip
11354 -----------+--------------+-----------------+-----------------+---------------
11355 str | reg | map_reg | map_reg_int | map_reg_ip
11356 -----------+--------------+-----------------+-----------------+---------------
11357 int | int | map_int | map_int_int | map_int_ip
11358 -----------+--------------+-----------------+-----------------+---------------
11359 ip | ip | map_ip | map_ip_int | map_ip_ip
11360 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010011361
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011362 The file contains one key + value per line. Lines which start with '#' are
11363 ignored, just like empty lines. Leading tabs and spaces are stripped. The key
11364 is then the first "word" (series of non-space/tabs characters), and the value
11365 is what follows this series of space/tab till the end of the line excluding
11366 trailing spaces/tabs.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010011367
Thierry FOURNIER060762e2014-04-23 13:29:15 +020011368 Example :
11369
11370 # this is a comment and is ignored
11371 2.22.246.0/23 United Kingdom \n
11372 <-><-----------><--><------------><---->
11373 | | | | `- trailing spaces ignored
11374 | | | `---------- value
11375 | | `-------------------- middle spaces ignored
11376 | `---------------------------- key
11377 `------------------------------------ leading spaces ignored
11378
Willy Tarreau97707872015-01-27 15:12:13 +010011379mod(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011380 Divides the input value of type signed integer by <value>, and returns the
11381 remainder as an signed integer. If <value> is null, then zero is returned.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020011382 <value> can be a numeric value or a variable name. The name of the variable
11383 starts by an indication about its scope. The allowed scopes are:
11384 "sess" : the variable is shared with all the session,
11385 "txn" : the variable is shared with all the transaction (request and
11386 response),
11387 "req" : the variable is shared only during the request processing,
11388 "res" : the variable is shared only during the response processing.
11389 This prefix is followed by a name. The separator is a '.'. The name may only
11390 contain characters 'a-z', 'A-Z', '0-9' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010011391
11392mul(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011393 Multiplies the input value of type signed integer by <value>, and returns
Thierry FOURNIER00c005c2015-07-08 01:10:21 +020011394 the product as an signed integer. In case of overflow, the largest possible
11395 value for the sign is returned so that the operation doesn't wrap around.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020011396 <value> can be a numeric value or a variable name. The name of the variable
11397 starts by an indication about its scope. The allowed scopes are:
11398 "sess" : the variable is shared with all the session,
11399 "txn" : the variable is shared with all the transaction (request and
11400 response),
11401 "req" : the variable is shared only during the request processing,
11402 "res" : the variable is shared only during the response processing.
11403 This prefix is followed by a name. The separator is a '.'. The name may only
11404 contain characters 'a-z', 'A-Z', '0-9' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010011405
11406neg
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011407 Takes the input value of type signed integer, computes the opposite value,
11408 and returns the remainder as an signed integer. 0 is identity. This operator
11409 is provided for reversed subtracts : in order to subtract the input from a
11410 constant, simply perform a "neg,add(value)".
Willy Tarreau97707872015-01-27 15:12:13 +010011411
11412not
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011413 Returns a boolean FALSE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010011414 non-null, otherwise returns TRUE. Used in conjunction with and(), it can be
11415 used to report true/false for bit testing on input values (eg: verify the
11416 absence of a flag).
11417
11418odd
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011419 Returns a boolean TRUE if the input value of type signed integer is odd
Willy Tarreau97707872015-01-27 15:12:13 +010011420 otherwise returns FALSE. It is functionally equivalent to "and(1),bool".
11421
11422or(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011423 Performs a bitwise "OR" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020011424 integer, and returns the result as an signed integer. <value> can be a
11425 numeric value or a variable name. The name of the variable starts by an
11426 indication about its scope. The allowed scopes are:
11427 "sess" : the variable is shared with all the session,
11428 "txn" : the variable is shared with all the transaction (request and
11429 response),
11430 "req" : the variable is shared only during the request processing,
11431 "res" : the variable is shared only during the response processing.
11432 This prefix is followed by a name. The separator is a '.'. The name may only
11433 contain characters 'a-z', 'A-Z', '0-9' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010011434
Willy Tarreauc4dc3502015-01-23 20:39:28 +010011435regsub(<regex>,<subst>[,<flags>])
Willy Tarreau7eda8492015-01-20 19:47:06 +010011436 Applies a regex-based substitution to the input string. It does the same
11437 operation as the well-known "sed" utility with "s/<regex>/<subst>/". By
11438 default it will replace in the input string the first occurrence of the
11439 largest part matching the regular expression <regex> with the substitution
11440 string <subst>. It is possible to replace all occurrences instead by adding
11441 the flag "g" in the third argument <flags>. It is also possible to make the
11442 regex case insensitive by adding the flag "i" in <flags>. Since <flags> is a
11443 string, it is made up from the concatenation of all desired flags. Thus if
11444 both "i" and "g" are desired, using "gi" or "ig" will have the same effect.
11445 It is important to note that due to the current limitations of the
11446 configuration parser, some characters such as closing parenthesis or comma
11447 are not possible to use in the arguments. The first use of this converter is
11448 to replace certain characters or sequence of characters with other ones.
11449
11450 Example :
11451
11452 # de-duplicate "/" in header "x-path".
11453 # input: x-path: /////a///b/c/xzxyz/
11454 # output: x-path: /a/b/c/xzxyz/
11455 http-request set-header x-path %[hdr(x-path),regsub(/+,/,g)]
11456
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020011457capture-req(<id>)
11458 Capture the string entry in the request slot <id> and returns the entry as
11459 is. If the slot doesn't exist, the capture fails silently.
11460
11461 See also: "declare capture", "http-request capture",
11462 "http-response capture", "req.hdr.capture" and
11463 "res.hdr.capture" (sample fetches).
11464
11465capture-res(<id>)
11466 Capture the string entry in the response slot <id> and returns the entry as
11467 is. If the slot doesn't exist, the capture fails silently.
11468
11469 See also: "declare capture", "http-request capture",
11470 "http-response capture", "req.hdr.capture" and
11471 "res.hdr.capture" (sample fetches).
11472
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020011473sdbm([<avalanche>])
11474 Hashes a binary input sample into an unsigned 32-bit quantity using the SDBM
11475 hash function. Optionally, it is possible to apply a full avalanche hash
11476 function to the output if the optional <avalanche> argument equals 1. This
11477 converter uses the same functions as used by the various hash-based load
11478 balancing algorithms, so it will provide exactly the same results. It is
11479 mostly intended for debugging, but can be used as a stick-table entry to
11480 collect rough statistics. It must not be used for security purposes as a
Willy Tarreau80599772015-01-20 19:35:24 +010011481 32-bit hash is trivial to break. See also "crc32", "djb2", "wt6" and the
11482 "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020011483
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011484set-var(<var name>)
11485 Sets a variable with the input content and return the content on the output as
11486 is. The variable keep the value and the associated input type. The name of the
11487 variable starts by an indication about it scope. The scope allowed are:
11488 "sess" : the variable is shared with all the session,
11489 "txn" : the variable is shared with all the transaction (request and
11490 response),
11491 "req" : the variable is shared only during the request processing,
11492 "res" : the variable is shared only during the response processing.
11493 This prefix is followed by a name. The separator is a '.'. The name may only
11494 contain characters 'a-z', 'A-Z', '0-9' and '_'.
11495
Willy Tarreau97707872015-01-27 15:12:13 +010011496sub(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011497 Subtracts <value> from the input value of type signed integer, and returns
11498 the result as an signed integer. Note: in order to subtract the input from
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020011499 a constant, simply perform a "neg,add(value)". <value> can be a numeric value
11500 or a variable name. The name of the variable starts by an indication about its
11501 scope. The allowed scopes are:
11502 "sess" : the variable is shared with all the session,
11503 "txn" : the variable is shared with all the transaction (request and
11504 response),
11505 "req" : the variable is shared only during the request processing,
11506 "res" : the variable is shared only during the response processing.
11507 This prefix is followed by a name. The separator is a '.'. The name may only
11508 contain characters 'a-z', 'A-Z', '0-9' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010011509
Willy Tarreaud9f316a2014-07-10 14:03:38 +020011510table_bytes_in_rate(<table>)
11511 Uses the string representation of the input sample to perform a look up in
11512 the specified table. If the key is not found in the table, integer value zero
11513 is returned. Otherwise the converter returns the average client-to-server
11514 bytes rate associated with the input sample in the designated table, measured
11515 in amount of bytes over the period configured in the table. See also the
11516 sc_bytes_in_rate sample fetch keyword.
11517
11518
11519table_bytes_out_rate(<table>)
11520 Uses the string representation of the input sample to perform a look up in
11521 the specified table. If the key is not found in the table, integer value zero
11522 is returned. Otherwise the converter returns the average server-to-client
11523 bytes rate associated with the input sample in the designated table, measured
11524 in amount of bytes over the period configured in the table. See also the
11525 sc_bytes_out_rate sample fetch keyword.
11526
11527table_conn_cnt(<table>)
11528 Uses the string representation of the input sample to perform a look up in
11529 the specified table. If the key is not found in the table, integer value zero
11530 is returned. Otherwise the converter returns the cumulated amount of incoming
11531 connections associated with the input sample in the designated table. See
11532 also the sc_conn_cnt sample fetch keyword.
11533
11534table_conn_cur(<table>)
11535 Uses the string representation of the input sample to perform a look up in
11536 the specified table. If the key is not found in the table, integer value zero
11537 is returned. Otherwise the converter returns the current amount of concurrent
11538 tracked connections associated with the input sample in the designated table.
11539 See also the sc_conn_cur sample fetch keyword.
11540
11541table_conn_rate(<table>)
11542 Uses the string representation of the input sample to perform a look up in
11543 the specified table. If the key is not found in the table, integer value zero
11544 is returned. Otherwise the converter returns the average incoming connection
11545 rate associated with the input sample in the designated table. See also the
11546 sc_conn_rate sample fetch keyword.
11547
11548table_gpc0(<table>)
11549 Uses the string representation of the input sample to perform a look up in
11550 the specified table. If the key is not found in the table, integer value zero
11551 is returned. Otherwise the converter returns the current value of the first
11552 general purpose counter associated with the input sample in the designated
11553 table. See also the sc_get_gpc0 sample fetch keyword.
11554
11555table_gpc0_rate(<table>)
11556 Uses the string representation of the input sample to perform a look up in
11557 the specified table. If the key is not found in the table, integer value zero
11558 is returned. Otherwise the converter returns the frequency which the gpc0
11559 counter was incremented over the configured period in the table, associated
11560 with the input sample in the designated table. See also the sc_get_gpc0_rate
11561 sample fetch keyword.
11562
11563table_http_err_cnt(<table>)
11564 Uses the string representation of the input sample to perform a look up in
11565 the specified table. If the key is not found in the table, integer value zero
11566 is returned. Otherwise the converter returns the cumulated amount of HTTP
11567 errors associated with the input sample in the designated table. See also the
11568 sc_http_err_cnt sample fetch keyword.
11569
11570table_http_err_rate(<table>)
11571 Uses the string representation of the input sample to perform a look up in
11572 the specified table. If the key is not found in the table, integer value zero
11573 is returned. Otherwise the average rate of HTTP errors associated with the
11574 input sample in the designated table, measured in amount of errors over the
11575 period configured in the table. See also the sc_http_err_rate sample fetch
11576 keyword.
11577
11578table_http_req_cnt(<table>)
11579 Uses the string representation of the input sample to perform a look up in
11580 the specified table. If the key is not found in the table, integer value zero
11581 is returned. Otherwise the converter returns the cumulated amount of HTTP
11582 requests associated with the input sample in the designated table. See also
11583 the sc_http_req_cnt sample fetch keyword.
11584
11585table_http_req_rate(<table>)
11586 Uses the string representation of the input sample to perform a look up in
11587 the specified table. If the key is not found in the table, integer value zero
11588 is returned. Otherwise the average rate of HTTP requests associated with the
11589 input sample in the designated table, measured in amount of requests over the
11590 period configured in the table. See also the sc_http_req_rate sample fetch
11591 keyword.
11592
11593table_kbytes_in(<table>)
11594 Uses the string representation of the input sample to perform a look up in
11595 the specified table. If the key is not found in the table, integer value zero
11596 is returned. Otherwise the converter returns the cumulated amount of client-
11597 to-server data associated with the input sample in the designated table,
11598 measured in kilobytes. The test is currently performed on 32-bit integers,
11599 which limits values to 4 terabytes. See also the sc_kbytes_in sample fetch
11600 keyword.
11601
11602table_kbytes_out(<table>)
11603 Uses the string representation of the input sample to perform a look up in
11604 the specified table. If the key is not found in the table, integer value zero
11605 is returned. Otherwise the converter returns the cumulated amount of server-
11606 to-client data associated with the input sample in the designated table,
11607 measured in kilobytes. The test is currently performed on 32-bit integers,
11608 which limits values to 4 terabytes. See also the sc_kbytes_out sample fetch
11609 keyword.
11610
11611table_server_id(<table>)
11612 Uses the string representation of the input sample to perform a look up in
11613 the specified table. If the key is not found in the table, integer value zero
11614 is returned. Otherwise the converter returns the server ID associated with
11615 the input sample in the designated table. A server ID is associated to a
11616 sample by a "stick" rule when a connection to a server succeeds. A server ID
11617 zero means that no server is associated with this key.
11618
11619table_sess_cnt(<table>)
11620 Uses the string representation of the input sample to perform a look up in
11621 the specified table. If the key is not found in the table, integer value zero
11622 is returned. Otherwise the converter returns the cumulated amount of incoming
11623 sessions associated with the input sample in the designated table. Note that
11624 a session here refers to an incoming connection being accepted by the
11625 "tcp-request connection" rulesets. See also the sc_sess_cnt sample fetch
11626 keyword.
11627
11628table_sess_rate(<table>)
11629 Uses the string representation of the input sample to perform a look up in
11630 the specified table. If the key is not found in the table, integer value zero
11631 is returned. Otherwise the converter returns the average incoming session
11632 rate associated with the input sample in the designated table. Note that a
11633 session here refers to an incoming connection being accepted by the
11634 "tcp-request connection" rulesets. See also the sc_sess_rate sample fetch
11635 keyword.
11636
11637table_trackers(<table>)
11638 Uses the string representation of the input sample to perform a look up in
11639 the specified table. If the key is not found in the table, integer value zero
11640 is returned. Otherwise the converter returns the current amount of concurrent
11641 connections tracking the same key as the input sample in the designated
11642 table. It differs from table_conn_cur in that it does not rely on any stored
11643 information but on the table's reference count (the "use" value which is
11644 returned by "show table" on the CLI). This may sometimes be more suited for
11645 layer7 tracking. It can be used to tell a server how many concurrent
11646 connections there are from a given address for example. See also the
11647 sc_trackers sample fetch keyword.
11648
Willy Tarreauffcb2e42014-07-10 16:29:08 +020011649upper
11650 Convert a string sample to upper case. This can only be placed after a string
11651 sample fetch function or after a transformation keyword returning a string
11652 type. The result is of type string.
11653
Thierry FOURNIER82ff3c92015-05-07 15:46:20 +020011654url_dec
11655 Takes an url-encoded string provided as input and returns the decoded
11656 version as output. The input and the output are of type string.
11657
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020011658utime(<format>[,<offset>])
11659 Converts an integer supposed to contain a date since epoch to a string
11660 representing this date in UTC time using a format defined by the <format>
11661 string using strftime(3). The purpose is to allow any date format to be used
11662 in logs. An optional <offset> in seconds may be applied to the input date
11663 (positive or negative). See the strftime() man page for the format supported
11664 by your operating system. See also the ltime converter.
11665
11666 Example :
11667
11668 # Emit two colons, one with the UTC time and another with ip:port
11669 # Eg: 20140710162350 127.0.0.1:57325
11670 log-format %[date,utime(%Y%m%d%H%M%S)]\ %ci:%cp
11671
Emeric Brunc9a0f6d2014-11-25 14:09:01 +010011672word(<index>,<delimiters>)
11673 Extracts the nth word considering given delimiters from an input string.
11674 Indexes start at 1 and delimiters are a string formatted list of chars.
11675
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020011676wt6([<avalanche>])
11677 Hashes a binary input sample into an unsigned 32-bit quantity using the WT6
11678 hash function. Optionally, it is possible to apply a full avalanche hash
11679 function to the output if the optional <avalanche> argument equals 1. This
11680 converter uses the same functions as used by the various hash-based load
11681 balancing algorithms, so it will provide exactly the same results. It is
11682 mostly intended for debugging, but can be used as a stick-table entry to
11683 collect rough statistics. It must not be used for security purposes as a
Willy Tarreau80599772015-01-20 19:35:24 +010011684 32-bit hash is trivial to break. See also "crc32", "djb2", "sdbm", and the
11685 "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020011686
Willy Tarreau97707872015-01-27 15:12:13 +010011687xor(<value>)
11688 Performs a bitwise "XOR" (exclusive OR) between <value> and the input value
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011689 of type signed integer, and returns the result as an signed integer.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020011690 <value> can be a numeric value or a variable name. The name of the variable
11691 starts by an indication about its scope. The allowed scopes are:
11692 "sess" : the variable is shared with all the session,
11693 "txn" : the variable is shared with all the transaction (request and
11694 response),
11695 "req" : the variable is shared only during the request processing,
11696 "res" : the variable is shared only during the response processing.
11697 This prefix is followed by a name. The separator is a '.'. The name may only
11698 contain characters 'a-z', 'A-Z', '0-9' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010011699
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010011700
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200117017.3.2. Fetching samples from internal states
Willy Tarreau74ca5042013-06-11 23:12:07 +020011702--------------------------------------------
11703
11704A first set of sample fetch methods applies to internal information which does
11705not even relate to any client information. These ones are sometimes used with
11706"monitor-fail" directives to report an internal status to external watchers.
11707The sample fetch methods described in this section are usable anywhere.
11708
11709always_false : boolean
11710 Always returns the boolean "false" value. It may be used with ACLs as a
11711 temporary replacement for another one when adjusting configurations.
11712
11713always_true : boolean
11714 Always returns the boolean "true" value. It may be used with ACLs as a
11715 temporary replacement for another one when adjusting configurations.
11716
11717avg_queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010011718 Returns the total number of queued connections of the designated backend
Willy Tarreau74ca5042013-06-11 23:12:07 +020011719 divided by the number of active servers. The current backend is used if no
11720 backend is specified. This is very similar to "queue" except that the size of
11721 the farm is considered, in order to give a more accurate measurement of the
11722 time it may take for a new connection to be processed. The main usage is with
11723 ACL to return a sorry page to new users when it becomes certain they will get
11724 a degraded service, or to pass to the backend servers in a header so that
11725 they decide to work in degraded mode or to disable some functions to speed up
11726 the processing a bit. Note that in the event there would not be any active
11727 server anymore, twice the number of queued connections would be considered as
11728 the measured value. This is a fair estimate, as we expect one server to get
11729 back soon anyway, but we still prefer to send new traffic to another backend
11730 if in better shape. See also the "queue", "be_conn", and "be_sess_rate"
11731 sample fetches.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +010011732
Willy Tarreau74ca5042013-06-11 23:12:07 +020011733be_conn([<backend>]) : integer
Willy Tarreaua36af912009-10-10 12:02:45 +020011734 Applies to the number of currently established connections on the backend,
11735 possibly including the connection being evaluated. If no backend name is
11736 specified, the current one is used. But it is also possible to check another
11737 backend. It can be used to use a specific farm when the nominal one is full.
11738 See also the "fe_conn", "queue" and "be_sess_rate" criteria.
Willy Tarreau6a06a402007-07-15 20:15:28 +020011739
Willy Tarreau74ca5042013-06-11 23:12:07 +020011740be_sess_rate([<backend>]) : integer
11741 Returns an integer value corresponding to the sessions creation rate on the
11742 backend, in number of new sessions per second. This is used with ACLs to
11743 switch to an alternate backend when an expensive or fragile one reaches too
11744 high a session rate, or to limit abuse of service (eg. prevent sucking of an
11745 online dictionary). It can also be useful to add this element to logs using a
11746 log-format directive.
Willy Tarreaud63335a2010-02-26 12:56:52 +010011747
11748 Example :
11749 # Redirect to an error page if the dictionary is requested too often
11750 backend dynamic
11751 mode http
11752 acl being_scanned be_sess_rate gt 100
11753 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +010011754
Thierry FOURNIERcc103292015-06-06 19:30:17 +020011755bin(<hexa>) : bin
11756 Returns a binary chain. The input is the hexadecimal representation
11757 of the string.
11758
11759bool(<bool>) : bool
11760 Returns a boolean value. <bool> can be 'true', 'false', '1' or '0'.
11761 'false' and '0' are the same. 'true' and '1' are the same.
11762
Willy Tarreau74ca5042013-06-11 23:12:07 +020011763connslots([<backend>]) : integer
11764 Returns an integer value corresponding to the number of connection slots
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011765 still available in the backend, by totaling the maximum amount of
Willy Tarreau74ca5042013-06-11 23:12:07 +020011766 connections on all servers and the maximum queue size. This is probably only
11767 used with ACLs.
Tait Clarridge7896d522012-12-05 21:39:31 -050011768
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080011769 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +020011770 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080011771 usage; see "use_backend" keyword) can be redirected to a different backend.
11772
Willy Tarreau55165fe2009-05-10 12:02:55 +020011773 'connslots' = number of available server connection slots, + number of
11774 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080011775
Willy Tarreaua36af912009-10-10 12:02:45 +020011776 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +020011777 useful when you have a case of traffic going to one single ip, splitting into
Willy Tarreau74ca5042013-06-11 23:12:07 +020011778 multiple backends (perhaps using ACLs to do name-based load balancing) and
Willy Tarreau55165fe2009-05-10 12:02:55 +020011779 you want to be able to differentiate between different backends, and their
11780 available "connslots". Also, whereas "nbsrv" only measures servers that are
Willy Tarreau74ca5042013-06-11 23:12:07 +020011781 actually *down*, this fetch is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +020011782 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080011783
Willy Tarreau55165fe2009-05-10 12:02:55 +020011784 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
11785 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
Willy Tarreau74ca5042013-06-11 23:12:07 +020011786 then this fetch clearly does not make sense, in which case the value returned
Willy Tarreau55165fe2009-05-10 12:02:55 +020011787 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080011788
Willy Tarreau6236d3a2013-07-25 14:28:25 +020011789date([<offset>]) : integer
11790 Returns the current date as the epoch (number of seconds since 01/01/1970).
11791 If an offset value is specified, then it is a number of seconds that is added
11792 to the current date before returning the value. This is particularly useful
11793 to compute relative dates, as both positive and negative offsets are allowed.
Willy Tarreau276fae92013-07-25 14:36:01 +020011794 It is useful combined with the http_date converter.
11795
11796 Example :
11797
11798 # set an expires header to now+1 hour in every response
11799 http-response set-header Expires %[date(3600),http_date]
Willy Tarreau6236d3a2013-07-25 14:28:25 +020011800
Willy Tarreau595ec542013-06-12 21:34:28 +020011801env(<name>) : string
11802 Returns a string containing the value of environment variable <name>. As a
11803 reminder, environment variables are per-process and are sampled when the
11804 process starts. This can be useful to pass some information to a next hop
11805 server, or with ACLs to take specific action when the process is started a
11806 certain way.
11807
11808 Examples :
11809 # Pass the Via header to next hop with the local hostname in it
11810 http-request add-header Via 1.1\ %[env(HOSTNAME)]
11811
11812 # reject cookie-less requests when the STOP environment variable is set
11813 http-request deny if !{ cook(SESSIONID) -m found } { env(STOP) -m found }
11814
Willy Tarreau74ca5042013-06-11 23:12:07 +020011815fe_conn([<frontend>]) : integer
11816 Returns the number of currently established connections on the frontend,
Willy Tarreaud63335a2010-02-26 12:56:52 +010011817 possibly including the connection being evaluated. If no frontend name is
11818 specified, the current one is used. But it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020011819 frontend. It can be used to return a sorry page before hard-blocking, or to
11820 use a specific backend to drain new requests when the farm is considered
11821 full. This is mostly used with ACLs but can also be used to pass some
11822 statistics to servers in HTTP headers. See also the "dst_conn", "be_conn",
11823 "fe_sess_rate" fetches.
Willy Tarreaua36af912009-10-10 12:02:45 +020011824
Willy Tarreau74ca5042013-06-11 23:12:07 +020011825fe_sess_rate([<frontend>]) : integer
11826 Returns an integer value corresponding to the sessions creation rate on the
11827 frontend, in number of new sessions per second. This is used with ACLs to
11828 limit the incoming session rate to an acceptable range in order to prevent
11829 abuse of service at the earliest moment, for example when combined with other
11830 layer 4 ACLs in order to force the clients to wait a bit for the rate to go
11831 down below the limit. It can also be useful to add this element to logs using
11832 a log-format directive. See also the "rate-limit sessions" directive for use
11833 in frontends.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010011834
11835 Example :
11836 # This frontend limits incoming mails to 10/s with a max of 100
11837 # concurrent connections. We accept any connection below 10/s, and
11838 # force excess clients to wait for 100 ms. Since clients are limited to
11839 # 100 max, there cannot be more than 10 incoming mails per second.
11840 frontend mail
11841 bind :25
11842 mode tcp
11843 maxconn 100
11844 acl too_fast fe_sess_rate ge 10
11845 tcp-request inspect-delay 100ms
11846 tcp-request content accept if ! too_fast
11847 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +010011848
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020011849int(<integer>) : signed integer
11850 Returns a signed integer.
11851
Thierry FOURNIERcc103292015-06-06 19:30:17 +020011852ipv4(<ipv4>) : ipv4
11853 Returns an ipv4.
11854
11855ipv6(<ipv6>) : ipv6
11856 Returns an ipv6.
11857
11858meth(<method>) : method
11859 Returns a method.
11860
Willy Tarreau0f30d262014-11-24 16:02:05 +010011861nbproc : integer
11862 Returns an integer value corresponding to the number of processes that were
11863 started (it equals the global "nbproc" setting). This is useful for logging
11864 and debugging purposes.
11865
Willy Tarreau74ca5042013-06-11 23:12:07 +020011866nbsrv([<backend>]) : integer
11867 Returns an integer value corresponding to the number of usable servers of
11868 either the current backend or the named backend. This is mostly used with
11869 ACLs but can also be useful when added to logs. This is normally used to
Willy Tarreaud63335a2010-02-26 12:56:52 +010011870 switch to an alternate backend when the number of servers is too low to
11871 to handle some load. It is useful to report a failure when combined with
11872 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +010011873
Willy Tarreau0f30d262014-11-24 16:02:05 +010011874proc : integer
11875 Returns an integer value corresponding to the position of the process calling
11876 the function, between 1 and global.nbproc. This is useful for logging and
11877 debugging purposes.
11878
Willy Tarreau74ca5042013-06-11 23:12:07 +020011879queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010011880 Returns the total number of queued connections of the designated backend,
11881 including all the connections in server queues. If no backend name is
11882 specified, the current one is used, but it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020011883 one. This is useful with ACLs or to pass statistics to backend servers. This
11884 can be used to take actions when queuing goes above a known level, generally
11885 indicating a surge of traffic or a massive slowdown on the servers. One
11886 possible action could be to reject new users but still accept old ones. See
11887 also the "avg_queue", "be_conn", and "be_sess_rate" fetches.
11888
Willy Tarreau84310e22014-02-14 11:59:04 +010011889rand([<range>]) : integer
11890 Returns a random integer value within a range of <range> possible values,
11891 starting at zero. If the range is not specified, it defaults to 2^32, which
11892 gives numbers between 0 and 4294967295. It can be useful to pass some values
11893 needed to take some routing decisions for example, or just for debugging
11894 purposes. This random must not be used for security purposes.
11895
Willy Tarreau74ca5042013-06-11 23:12:07 +020011896srv_conn([<backend>/]<server>) : integer
11897 Returns an integer value corresponding to the number of currently established
11898 connections on the designated server, possibly including the connection being
11899 evaluated. If <backend> is omitted, then the server is looked up in the
11900 current backend. It can be used to use a specific farm when one server is
11901 full, or to inform the server about our view of the number of active
11902 connections with it. See also the "fe_conn", "be_conn" and "queue" fetch
11903 methods.
11904
11905srv_is_up([<backend>/]<server>) : boolean
11906 Returns true when the designated server is UP, and false when it is either
11907 DOWN or in maintenance mode. If <backend> is omitted, then the server is
11908 looked up in the current backend. It is mainly used to take action based on
11909 an external status reported via a health check (eg: a geographical site's
11910 availability). Another possible use which is more of a hack consists in
11911 using dummy servers as boolean variables that can be enabled or disabled from
11912 the CLI, so that rules depending on those ACLs can be tweaked in realtime.
11913
11914srv_sess_rate([<backend>/]<server>) : integer
11915 Returns an integer corresponding to the sessions creation rate on the
11916 designated server, in number of new sessions per second. If <backend> is
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011917 omitted, then the server is looked up in the current backend. This is mostly
Willy Tarreau74ca5042013-06-11 23:12:07 +020011918 used with ACLs but can make sense with logs too. This is used to switch to an
11919 alternate backend when an expensive or fragile one reaches too high a session
11920 rate, or to limit abuse of service (eg. prevent latent requests from
11921 overloading servers).
11922
11923 Example :
11924 # Redirect to a separate back
11925 acl srv1_full srv_sess_rate(be1/srv1) gt 50
11926 acl srv2_full srv_sess_rate(be1/srv2) gt 50
11927 use_backend be2 if srv1_full or srv2_full
11928
Willy Tarreau0f30d262014-11-24 16:02:05 +010011929stopping : boolean
11930 Returns TRUE if the process calling the function is currently stopping. This
11931 can be useful for logging, or for relaxing certain checks or helping close
11932 certain connections upon graceful shutdown.
11933
Thierry FOURNIERcc103292015-06-06 19:30:17 +020011934str(<string>) : string
11935 Returns a string.
11936
Willy Tarreau74ca5042013-06-11 23:12:07 +020011937table_avl([<table>]) : integer
11938 Returns the total number of available entries in the current proxy's
11939 stick-table or in the designated stick-table. See also table_cnt.
11940
11941table_cnt([<table>]) : integer
11942 Returns the total number of entries currently in use in the current proxy's
11943 stick-table or in the designated stick-table. See also src_conn_cnt and
11944 table_avl for other entry counting methods.
11945
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011946var(<var-name>) : undefined
11947 Returns a variable with the stored type. If the variable is not set, the
11948 sample fetch fails. The name of the variable starts by an indication about its
11949 scope. The scope allowed are:
11950 "sess" : the variable is shared with all the session,
11951 "txn" : the variable is shared with all the transaction (request and
11952 response),
11953 "req" : the variable is shared only during the request processing,
11954 "res" : the variable is shared only during the response processing.
11955 This prefix is followed by a name. The separator is a '.'. The name may only
11956 contain characters 'a-z', 'A-Z', '0-9' and '_'.
11957
Willy Tarreau74ca5042013-06-11 23:12:07 +020011958
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200119597.3.3. Fetching samples at Layer 4
Willy Tarreau74ca5042013-06-11 23:12:07 +020011960----------------------------------
11961
11962The layer 4 usually describes just the transport layer which in haproxy is
11963closest to the connection, where no content is yet made available. The fetch
11964methods described here are usable as low as the "tcp-request connection" rule
11965sets unless they require some future information. Those generally include
11966TCP/IP addresses and ports, as well as elements from stick-tables related to
Willy Tarreau4d4149c2013-07-23 19:33:46 +020011967the incoming connection. For retrieving a value from a sticky counters, the
11968counter number can be explicitly set as 0, 1, or 2 using the pre-defined
11969"sc0_", "sc1_", or "sc2_" prefix, or it can be specified as the first integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020011970argument when using the "sc_" prefix. An optional table may be specified with
11971the "sc*" form, in which case the currently tracked key will be looked up into
11972this alternate table instead of the table currently being tracked.
Willy Tarreau74ca5042013-06-11 23:12:07 +020011973
11974be_id : integer
11975 Returns an integer containing the current backend's id. It can be used in
11976 frontends with responses to check which backend processed the request.
11977
11978dst : ip
11979 This is the destination IPv4 address of the connection on the client side,
11980 which is the address the client connected to. It can be useful when running
11981 in transparent mode. It is of type IP and works on both IPv4 and IPv6 tables.
11982 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent, according to
11983 RFC 4291.
11984
11985dst_conn : integer
11986 Returns an integer value corresponding to the number of currently established
11987 connections on the same socket including the one being evaluated. It is
11988 normally used with ACLs but can as well be used to pass the information to
11989 servers in an HTTP header or in logs. It can be used to either return a sorry
11990 page before hard-blocking, or to use a specific backend to drain new requests
11991 when the socket is considered saturated. This offers the ability to assign
11992 different limits to different listening ports or addresses. See also the
11993 "fe_conn" and "be_conn" fetches.
Willy Tarreaud63335a2010-02-26 12:56:52 +010011994
Willy Tarreau74ca5042013-06-11 23:12:07 +020011995dst_port : integer
11996 Returns an integer value corresponding to the destination TCP port of the
11997 connection on the client side, which is the port the client connected to.
11998 This might be used when running in transparent mode, when assigning dynamic
11999 ports to some clients for a whole application session, to stick all users to
12000 a same server, or to pass the destination port information to a server using
12001 an HTTP header.
12002
12003fe_id : integer
12004 Returns an integer containing the current frontend's id. It can be used in
12005 backends to check from which backend it was called, or to stick all users
12006 coming via a same frontend to the same server.
12007
Cyril Bonté62ba8702014-04-22 23:52:25 +020012008sc_bytes_in_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012009sc0_bytes_in_rate([<table>]) : integer
12010sc1_bytes_in_rate([<table>]) : integer
12011sc2_bytes_in_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012012 Returns the average client-to-server bytes rate from the currently tracked
12013 counters, measured in amount of bytes over the period configured in the
12014 table. See also src_bytes_in_rate.
12015
Cyril Bonté62ba8702014-04-22 23:52:25 +020012016sc_bytes_out_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012017sc0_bytes_out_rate([<table>]) : integer
12018sc1_bytes_out_rate([<table>]) : integer
12019sc2_bytes_out_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012020 Returns the average server-to-client bytes rate from the currently tracked
12021 counters, measured in amount of bytes over the period configured in the
12022 table. See also src_bytes_out_rate.
12023
Cyril Bonté62ba8702014-04-22 23:52:25 +020012024sc_clr_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012025sc0_clr_gpc0([<table>]) : integer
12026sc1_clr_gpc0([<table>]) : integer
12027sc2_clr_gpc0([<table>]) : integer
Willy Tarreauf73cd112011-08-13 01:45:16 +020012028 Clears the first General Purpose Counter associated to the currently tracked
12029 counters, and returns its previous value. Before the first invocation, the
Willy Tarreau869948b2013-01-04 14:14:57 +010012030 stored value is zero, so first invocation will always return zero. This is
12031 typically used as a second ACL in an expression in order to mark a connection
12032 when a first ACL was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020012033
12034 # block if 5 consecutive requests continue to come faster than 10 sess
12035 # per second, and reset the counter as soon as the traffic slows down.
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020012036 acl abuse sc0_http_req_rate gt 10
12037 acl kill sc0_inc_gpc0 gt 5
12038 acl save sc0_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020012039 tcp-request connection accept if !abuse save
12040 tcp-request connection reject if abuse kill
12041
Cyril Bonté62ba8702014-04-22 23:52:25 +020012042sc_conn_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012043sc0_conn_cnt([<table>]) : integer
12044sc1_conn_cnt([<table>]) : integer
12045sc2_conn_cnt([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012046 Returns the cumulated number of incoming connections from currently tracked
12047 counters. See also src_conn_cnt.
12048
Cyril Bonté62ba8702014-04-22 23:52:25 +020012049sc_conn_cur(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012050sc0_conn_cur([<table>]) : integer
12051sc1_conn_cur([<table>]) : integer
12052sc2_conn_cur([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012053 Returns the current amount of concurrent connections tracking the same
12054 tracked counters. This number is automatically incremented when tracking
12055 begins and decremented when tracking stops. See also src_conn_cur.
12056
Cyril Bonté62ba8702014-04-22 23:52:25 +020012057sc_conn_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012058sc0_conn_rate([<table>]) : integer
12059sc1_conn_rate([<table>]) : integer
12060sc2_conn_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012061 Returns the average connection rate from the currently tracked counters,
12062 measured in amount of connections over the period configured in the table.
12063 See also src_conn_rate.
12064
Cyril Bonté62ba8702014-04-22 23:52:25 +020012065sc_get_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012066sc0_get_gpc0([<table>]) : integer
12067sc1_get_gpc0([<table>]) : integer
12068sc2_get_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012069 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012070 currently tracked counters. See also src_get_gpc0 and sc/sc0/sc1/sc2_inc_gpc0.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020012071
Cyril Bonté62ba8702014-04-22 23:52:25 +020012072sc_gpc0_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012073sc0_gpc0_rate([<table>]) : integer
12074sc1_gpc0_rate([<table>]) : integer
12075sc2_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020012076 Returns the average increment rate of the first General Purpose Counter
12077 associated to the currently tracked counters. It reports the frequency
12078 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012079 src_gpc0_rate, sc/sc0/sc1/sc2_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
12080 that the "gpc0_rate" counter must be stored in the stick-table for a value to
12081 be returned, as "gpc0" only holds the event count.
Willy Tarreaue9656522010-08-17 15:40:09 +020012082
Cyril Bonté62ba8702014-04-22 23:52:25 +020012083sc_http_err_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012084sc0_http_err_cnt([<table>]) : integer
12085sc1_http_err_cnt([<table>]) : integer
12086sc2_http_err_cnt([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012087 Returns the cumulated number of HTTP errors from the currently tracked
12088 counters. This includes the both request errors and 4xx error responses.
12089 See also src_http_err_cnt.
12090
Cyril Bonté62ba8702014-04-22 23:52:25 +020012091sc_http_err_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012092sc0_http_err_rate([<table>]) : integer
12093sc1_http_err_rate([<table>]) : integer
12094sc2_http_err_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012095 Returns the average rate of HTTP errors from the currently tracked counters,
12096 measured in amount of errors over the period configured in the table. This
12097 includes the both request errors and 4xx error responses. See also
12098 src_http_err_rate.
12099
Cyril Bonté62ba8702014-04-22 23:52:25 +020012100sc_http_req_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012101sc0_http_req_cnt([<table>]) : integer
12102sc1_http_req_cnt([<table>]) : integer
12103sc2_http_req_cnt([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012104 Returns the cumulated number of HTTP requests from the currently tracked
12105 counters. This includes every started request, valid or not. See also
12106 src_http_req_cnt.
12107
Cyril Bonté62ba8702014-04-22 23:52:25 +020012108sc_http_req_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012109sc0_http_req_rate([<table>]) : integer
12110sc1_http_req_rate([<table>]) : integer
12111sc2_http_req_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012112 Returns the average rate of HTTP requests from the currently tracked
12113 counters, measured in amount of requests over the period configured in
12114 the table. This includes every started request, valid or not. See also
12115 src_http_req_rate.
12116
Cyril Bonté62ba8702014-04-22 23:52:25 +020012117sc_inc_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012118sc0_inc_gpc0([<table>]) : integer
12119sc1_inc_gpc0([<table>]) : integer
12120sc2_inc_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012121 Increments the first General Purpose Counter associated to the currently
Willy Tarreau869948b2013-01-04 14:14:57 +010012122 tracked counters, and returns its new value. Before the first invocation,
12123 the stored value is zero, so first invocation will increase it to 1 and will
12124 return 1. This is typically used as a second ACL in an expression in order
12125 to mark a connection when a first ACL was verified :
Willy Tarreaue9656522010-08-17 15:40:09 +020012126
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020012127 acl abuse sc0_http_req_rate gt 10
12128 acl kill sc0_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020012129 tcp-request connection reject if abuse kill
12130
Cyril Bonté62ba8702014-04-22 23:52:25 +020012131sc_kbytes_in(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012132sc0_kbytes_in([<table>]) : integer
12133sc1_kbytes_in([<table>]) : integer
12134sc2_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020012135 Returns the total amount of client-to-server data from the currently tracked
12136 counters, measured in kilobytes. The test is currently performed on 32-bit
12137 integers, which limits values to 4 terabytes. See also src_kbytes_in.
Willy Tarreaue9656522010-08-17 15:40:09 +020012138
Cyril Bonté62ba8702014-04-22 23:52:25 +020012139sc_kbytes_out(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012140sc0_kbytes_out([<table>]) : integer
12141sc1_kbytes_out([<table>]) : integer
12142sc2_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020012143 Returns the total amount of server-to-client data from the currently tracked
12144 counters, measured in kilobytes. The test is currently performed on 32-bit
12145 integers, which limits values to 4 terabytes. See also src_kbytes_out.
Willy Tarreaue9656522010-08-17 15:40:09 +020012146
Cyril Bonté62ba8702014-04-22 23:52:25 +020012147sc_sess_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012148sc0_sess_cnt([<table>]) : integer
12149sc1_sess_cnt([<table>]) : integer
12150sc2_sess_cnt([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012151 Returns the cumulated number of incoming connections that were transformed
12152 into sessions, which means that they were accepted by a "tcp-request
12153 connection" rule, from the currently tracked counters. A backend may count
12154 more sessions than connections because each connection could result in many
Jamie Gloudonaaa21002012-08-25 00:18:33 -040012155 backend sessions if some HTTP keep-alive is performed over the connection
Willy Tarreaue9656522010-08-17 15:40:09 +020012156 with the client. See also src_sess_cnt.
12157
Cyril Bonté62ba8702014-04-22 23:52:25 +020012158sc_sess_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012159sc0_sess_rate([<table>]) : integer
12160sc1_sess_rate([<table>]) : integer
12161sc2_sess_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020012162 Returns the average session rate from the currently tracked counters,
12163 measured in amount of sessions over the period configured in the table. A
12164 session is a connection that got past the early "tcp-request connection"
12165 rules. A backend may count more sessions than connections because each
12166 connection could result in many backend sessions if some HTTP keep-alive is
Jamie Gloudonaaa21002012-08-25 00:18:33 -040012167 performed over the connection with the client. See also src_sess_rate.
Willy Tarreaue9656522010-08-17 15:40:09 +020012168
Cyril Bonté62ba8702014-04-22 23:52:25 +020012169sc_tracked(<ctr>[,<table>]) : boolean
Willy Tarreau0f791d42013-07-23 19:56:43 +020012170sc0_tracked([<table>]) : boolean
12171sc1_tracked([<table>]) : boolean
12172sc2_tracked([<table>]) : boolean
Willy Tarreau6f1615f2013-06-03 15:15:22 +020012173 Returns true if the designated session counter is currently being tracked by
12174 the current session. This can be useful when deciding whether or not we want
12175 to set some values in a header passed to the server.
12176
Cyril Bonté62ba8702014-04-22 23:52:25 +020012177sc_trackers(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020012178sc0_trackers([<table>]) : integer
12179sc1_trackers([<table>]) : integer
12180sc2_trackers([<table>]) : integer
Willy Tarreau2406db42012-12-09 12:16:43 +010012181 Returns the current amount of concurrent connections tracking the same
12182 tracked counters. This number is automatically incremented when tracking
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020012183 begins and decremented when tracking stops. It differs from sc0_conn_cur in
Willy Tarreau2406db42012-12-09 12:16:43 +010012184 that it does not rely on any stored information but on the table's reference
12185 count (the "use" value which is returned by "show table" on the CLI). This
Willy Tarreau74ca5042013-06-11 23:12:07 +020012186 may sometimes be more suited for layer7 tracking. It can be used to tell a
12187 server how many concurrent connections there are from a given address for
12188 example.
Willy Tarreau2406db42012-12-09 12:16:43 +010012189
Willy Tarreau74ca5042013-06-11 23:12:07 +020012190so_id : integer
12191 Returns an integer containing the current listening socket's id. It is useful
12192 in frontends involving many "bind" lines, or to stick all users coming via a
12193 same socket to the same server.
Willy Tarreaud63335a2010-02-26 12:56:52 +010012194
Willy Tarreau74ca5042013-06-11 23:12:07 +020012195src : ip
12196 This is the source IPv4 address of the client of the session. It is of type
12197 IP and works on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are
12198 mapped to their IPv6 equivalent, according to RFC 4291. Note that it is the
12199 TCP-level source address which is used, and not the address of a client
12200 behind a proxy. However if the "accept-proxy" bind directive is used, it can
12201 be the address of a client behind another PROXY-protocol compatible component
12202 for all rule sets except "tcp-request connection" which sees the real address.
Willy Tarreaud63335a2010-02-26 12:56:52 +010012203
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010012204 Example:
12205 # add an HTTP header in requests with the originating address' country
12206 http-request set-header X-Country %[src,map_ip(geoip.lst)]
12207
Willy Tarreau74ca5042013-06-11 23:12:07 +020012208src_bytes_in_rate([<table>]) : integer
12209 Returns the average bytes rate from the incoming connection's source address
12210 in the current proxy's stick-table or in the designated stick-table, measured
12211 in amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012212 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012213
Willy Tarreau74ca5042013-06-11 23:12:07 +020012214src_bytes_out_rate([<table>]) : integer
12215 Returns the average bytes rate to the incoming connection's source address in
12216 the current proxy's stick-table or in the designated stick-table, measured in
Willy Tarreauc9705a12010-07-27 20:05:50 +020012217 amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012218 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012219
Willy Tarreau74ca5042013-06-11 23:12:07 +020012220src_clr_gpc0([<table>]) : integer
12221 Clears the first General Purpose Counter associated to the incoming
12222 connection's source address in the current proxy's stick-table or in the
12223 designated stick-table, and returns its previous value. If the address is not
12224 found, an entry is created and 0 is returned. This is typically used as a
12225 second ACL in an expression in order to mark a connection when a first ACL
12226 was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020012227
12228 # block if 5 consecutive requests continue to come faster than 10 sess
12229 # per second, and reset the counter as soon as the traffic slows down.
12230 acl abuse src_http_req_rate gt 10
12231 acl kill src_inc_gpc0 gt 5
Willy Tarreau869948b2013-01-04 14:14:57 +010012232 acl save src_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020012233 tcp-request connection accept if !abuse save
12234 tcp-request connection reject if abuse kill
12235
Willy Tarreau74ca5042013-06-11 23:12:07 +020012236src_conn_cnt([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020012237 Returns the cumulated number of connections initiated from the current
Willy Tarreau74ca5042013-06-11 23:12:07 +020012238 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020012239 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012240 See also sc/sc0/sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012241
Willy Tarreau74ca5042013-06-11 23:12:07 +020012242src_conn_cur([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020012243 Returns the current amount of concurrent connections initiated from the
Willy Tarreau74ca5042013-06-11 23:12:07 +020012244 current incoming connection's source address in the current proxy's
12245 stick-table or in the designated stick-table. If the address is not found,
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012246 zero is returned. See also sc/sc0/sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012247
Willy Tarreau74ca5042013-06-11 23:12:07 +020012248src_conn_rate([<table>]) : integer
12249 Returns the average connection rate from the incoming connection's source
12250 address in the current proxy's stick-table or in the designated stick-table,
12251 measured in amount of connections over the period configured in the table. If
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012252 the address is not found, zero is returned. See also sc/sc0/sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012253
Willy Tarreau74ca5042013-06-11 23:12:07 +020012254src_get_gpc0([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020012255 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau74ca5042013-06-11 23:12:07 +020012256 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020012257 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012258 See also sc/sc0/sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012259
Willy Tarreau74ca5042013-06-11 23:12:07 +020012260src_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020012261 Returns the average increment rate of the first General Purpose Counter
Willy Tarreau74ca5042013-06-11 23:12:07 +020012262 associated to the incoming connection's source address in the current proxy's
Willy Tarreauba2ffd12013-05-29 15:54:14 +020012263 stick-table or in the designated stick-table. It reports the frequency
12264 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012265 sc/sc0/sc1/sc2_gpc0_rate, src_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
12266 that the "gpc0_rate" counter must be stored in the stick-table for a value to
12267 be returned, as "gpc0" only holds the event count.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020012268
Willy Tarreau74ca5042013-06-11 23:12:07 +020012269src_http_err_cnt([<table>]) : integer
12270 Returns the cumulated number of HTTP errors from the incoming connection's
12271 source address in the current proxy's stick-table or in the designated
Willy Tarreauc9705a12010-07-27 20:05:50 +020012272 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012273 See also sc/sc0/sc1/sc2_http_err_cnt. If the address is not found, zero is
Willy Tarreau74ca5042013-06-11 23:12:07 +020012274 returned.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012275
Willy Tarreau74ca5042013-06-11 23:12:07 +020012276src_http_err_rate([<table>]) : integer
12277 Returns the average rate of HTTP errors from the incoming connection's source
12278 address in the current proxy's stick-table or in the designated stick-table,
12279 measured in amount of errors over the period configured in the table. This
12280 includes the both request errors and 4xx error responses. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012281 not found, zero is returned. See also sc/sc0/sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012282
Willy Tarreau74ca5042013-06-11 23:12:07 +020012283src_http_req_cnt([<table>]) : integer
12284 Returns the cumulated number of HTTP requests from the incoming connection's
12285 source address in the current proxy's stick-table or in the designated stick-
12286 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012287 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012288
Willy Tarreau74ca5042013-06-11 23:12:07 +020012289src_http_req_rate([<table>]) : integer
12290 Returns the average rate of HTTP requests from the incoming connection's
12291 source address in the current proxy's stick-table or in the designated stick-
12292 table, measured in amount of requests over the period configured in the
Willy Tarreauc9705a12010-07-27 20:05:50 +020012293 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012294 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012295
Willy Tarreau74ca5042013-06-11 23:12:07 +020012296src_inc_gpc0([<table>]) : integer
12297 Increments the first General Purpose Counter associated to the incoming
12298 connection's source address in the current proxy's stick-table or in the
12299 designated stick-table, and returns its new value. If the address is not
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020012300 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc0.
Willy Tarreau74ca5042013-06-11 23:12:07 +020012301 This is typically used as a second ACL in an expression in order to mark a
12302 connection when a first ACL was verified :
Willy Tarreauc9705a12010-07-27 20:05:50 +020012303
12304 acl abuse src_http_req_rate gt 10
Willy Tarreau869948b2013-01-04 14:14:57 +010012305 acl kill src_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020012306 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +020012307
Willy Tarreau74ca5042013-06-11 23:12:07 +020012308src_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020012309 Returns the total amount of data received from the incoming connection's
12310 source address in the current proxy's stick-table or in the designated
12311 stick-table, measured in kilobytes. If the address is not found, zero is
12312 returned. The test is currently performed on 32-bit integers, which limits
12313 values to 4 terabytes. See also sc/sc0/sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012314
Willy Tarreau74ca5042013-06-11 23:12:07 +020012315src_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020012316 Returns the total amount of data sent to the incoming connection's source
12317 address in the current proxy's stick-table or in the designated stick-table,
12318 measured in kilobytes. If the address is not found, zero is returned. The
12319 test is currently performed on 32-bit integers, which limits values to 4
12320 terabytes. See also sc/sc0/sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020012321
Willy Tarreau74ca5042013-06-11 23:12:07 +020012322src_port : integer
12323 Returns an integer value corresponding to the TCP source port of the
12324 connection on the client side, which is the port the client connected from.
12325 Usage of this function is very limited as modern protocols do not care much
12326 about source ports nowadays.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010012327
Willy Tarreau74ca5042013-06-11 23:12:07 +020012328src_sess_cnt([<table>]) : integer
12329 Returns the cumulated number of connections initiated from the incoming
Willy Tarreauc9705a12010-07-27 20:05:50 +020012330 connection's source IPv4 address in the current proxy's stick-table or in the
12331 designated stick-table, that were transformed into sessions, which means that
12332 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012333 is returned. See also sc/sc0/sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012334
Willy Tarreau74ca5042013-06-11 23:12:07 +020012335src_sess_rate([<table>]) : integer
12336 Returns the average session rate from the incoming connection's source
12337 address in the current proxy's stick-table or in the designated stick-table,
12338 measured in amount of sessions over the period configured in the table. A
12339 session is a connection that went past the early "tcp-request" rules. If the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020012340 address is not found, zero is returned. See also sc/sc0/sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020012341
Willy Tarreau74ca5042013-06-11 23:12:07 +020012342src_updt_conn_cnt([<table>]) : integer
12343 Creates or updates the entry associated to the incoming connection's source
12344 address in the current proxy's stick-table or in the designated stick-table.
12345 This table must be configured to store the "conn_cnt" data type, otherwise
12346 the match will be ignored. The current count is incremented by one, and the
12347 expiration timer refreshed. The updated count is returned, so this match
12348 can't return zero. This was used to reject service abusers based on their
12349 source address. Note: it is recommended to use the more complete "track-sc*"
12350 actions in "tcp-request" rules instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020012351
12352 Example :
12353 # This frontend limits incoming SSH connections to 3 per 10 second for
12354 # each source address, and rejects excess connections until a 10 second
12355 # silence is observed. At most 20 addresses are tracked.
12356 listen ssh
12357 bind :22
12358 mode tcp
12359 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +020012360 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreau74ca5042013-06-11 23:12:07 +020012361 tcp-request content reject if { src_updt_conn_cnt gt 3 }
Willy Tarreaua975b8f2010-06-05 19:13:27 +020012362 server local 127.0.0.1:22
12363
Willy Tarreau74ca5042013-06-11 23:12:07 +020012364srv_id : integer
12365 Returns an integer containing the server's id when processing the response.
12366 While it's almost only used with ACLs, it may be used for logging or
12367 debugging.
Hervé COMMOWICKdaa824e2011-08-05 12:09:44 +020012368
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +010012369
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200123707.3.4. Fetching samples at Layer 5
Willy Tarreau74ca5042013-06-11 23:12:07 +020012371----------------------------------
Willy Tarreau0b1cd942010-05-16 22:18:27 +020012372
Willy Tarreau74ca5042013-06-11 23:12:07 +020012373The layer 5 usually describes just the session layer which in haproxy is
12374closest to the session once all the connection handshakes are finished, but
12375when no content is yet made available. The fetch methods described here are
12376usable as low as the "tcp-request content" rule sets unless they require some
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012377future information. Those generally include the results of SSL negotiations.
Willy Tarreauc735a072011-03-29 00:57:02 +020012378
Emeric Brun645ae792014-04-30 14:21:06 +020012379ssl_bc : boolean
12380 Returns true when the back connection was made via an SSL/TLS transport
12381 layer and is locally deciphered. This means the outgoing connection was made
12382 other a server with the "ssl" option.
12383
12384ssl_bc_alg_keysize : integer
12385 Returns the symmetric cipher key size supported in bits when the outgoing
12386 connection was made over an SSL/TLS transport layer.
12387
12388ssl_bc_cipher : string
12389 Returns the name of the used cipher when the outgoing connection was made
12390 over an SSL/TLS transport layer.
12391
12392ssl_bc_protocol : string
12393 Returns the name of the used protocol when the outgoing connection was made
12394 over an SSL/TLS transport layer.
12395
Emeric Brunb73a9b02014-04-30 18:49:19 +020012396ssl_bc_unique_id : binary
Emeric Brun645ae792014-04-30 14:21:06 +020012397 When the outgoing connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020012398 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
12399 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".
Emeric Brun645ae792014-04-30 14:21:06 +020012400
12401ssl_bc_session_id : binary
12402 Returns the SSL ID of the back connection when the outgoing connection was
12403 made over an SSL/TLS transport layer. It is useful to log if we want to know
12404 if session was reused or not.
12405
12406ssl_bc_use_keysize : integer
12407 Returns the symmetric cipher key size used in bits when the outgoing
12408 connection was made over an SSL/TLS transport layer.
12409
Willy Tarreau74ca5042013-06-11 23:12:07 +020012410ssl_c_ca_err : integer
12411 When the incoming connection was made over an SSL/TLS transport layer,
12412 returns the ID of the first error detected during verification of the client
12413 certificate at depth > 0, or 0 if no error was encountered during this
12414 verification process. Please refer to your SSL library's documentation to
12415 find the exhaustive list of error codes.
Willy Tarreauc735a072011-03-29 00:57:02 +020012416
Willy Tarreau74ca5042013-06-11 23:12:07 +020012417ssl_c_ca_err_depth : integer
12418 When the incoming connection was made over an SSL/TLS transport layer,
12419 returns the depth in the CA chain of the first error detected during the
12420 verification of the client certificate. If no error is encountered, 0 is
12421 returned.
Willy Tarreau0ba27502007-12-24 16:55:16 +010012422
Emeric Brun43e79582014-10-29 19:03:26 +010012423ssl_c_der : binary
12424 Returns the DER formatted certificate presented by the client when the
12425 incoming connection was made over an SSL/TLS transport layer. When used for
12426 an ACL, the value(s) to match against can be passed in hexadecimal form.
12427
Willy Tarreau74ca5042013-06-11 23:12:07 +020012428ssl_c_err : integer
12429 When the incoming connection was made over an SSL/TLS transport layer,
12430 returns the ID of the first error detected during verification at depth 0, or
12431 0 if no error was encountered during this verification process. Please refer
12432 to your SSL library's documentation to find the exhaustive list of error
12433 codes.
Willy Tarreau62644772008-07-16 18:36:06 +020012434
Willy Tarreau74ca5042013-06-11 23:12:07 +020012435ssl_c_i_dn([<entry>[,<occ>]]) : string
12436 When the incoming connection was made over an SSL/TLS transport layer,
12437 returns the full distinguished name of the issuer of the certificate
12438 presented by the client when no <entry> is specified, or the value of the
12439 first given entry found from the beginning of the DN. If a positive/negative
12440 occurrence number is specified as the optional second argument, it returns
12441 the value of the nth given entry value from the beginning/end of the DN.
12442 For instance, "ssl_c_i_dn(OU,2)" the second organization unit, and
12443 "ssl_c_i_dn(CN)" retrieves the common name.
Willy Tarreau62644772008-07-16 18:36:06 +020012444
Willy Tarreau74ca5042013-06-11 23:12:07 +020012445ssl_c_key_alg : string
12446 Returns the name of the algorithm used to generate the key of the certificate
12447 presented by the client when the incoming connection was made over an SSL/TLS
12448 transport layer.
Willy Tarreau62644772008-07-16 18:36:06 +020012449
Willy Tarreau74ca5042013-06-11 23:12:07 +020012450ssl_c_notafter : string
12451 Returns the end date presented by the client as a formatted string
12452 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
12453 transport layer.
Emeric Brunbede3d02009-06-30 17:54:00 +020012454
Willy Tarreau74ca5042013-06-11 23:12:07 +020012455ssl_c_notbefore : string
12456 Returns the start date presented by the client as a formatted string
12457 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
12458 transport layer.
Willy Tarreaub6672b52011-12-12 17:23:41 +010012459
Willy Tarreau74ca5042013-06-11 23:12:07 +020012460ssl_c_s_dn([<entry>[,<occ>]]) : string
12461 When the incoming connection was made over an SSL/TLS transport layer,
12462 returns the full distinguished name of the subject of the certificate
12463 presented by the client when no <entry> is specified, or the value of the
12464 first given entry found from the beginning of the DN. If a positive/negative
12465 occurrence number is specified as the optional second argument, it returns
12466 the value of the nth given entry value from the beginning/end of the DN.
12467 For instance, "ssl_c_s_dn(OU,2)" the second organization unit, and
12468 "ssl_c_s_dn(CN)" retrieves the common name.
Willy Tarreaub6672b52011-12-12 17:23:41 +010012469
Willy Tarreau74ca5042013-06-11 23:12:07 +020012470ssl_c_serial : binary
12471 Returns the serial of the certificate presented by the client when the
12472 incoming connection was made over an SSL/TLS transport layer. When used for
12473 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun2525b6b2012-10-18 15:59:43 +020012474
Willy Tarreau74ca5042013-06-11 23:12:07 +020012475ssl_c_sha1 : binary
12476 Returns the SHA-1 fingerprint of the certificate presented by the client when
12477 the incoming connection was made over an SSL/TLS transport layer. This can be
12478 used to stick a client to a server, or to pass this information to a server.
Willy Tarreau2d0caa32014-07-02 19:01:22 +020012479 Note that the output is binary, so if you want to pass that signature to the
12480 server, you need to encode it in hex or base64, such as in the example below:
12481
12482 http-request set-header X-SSL-Client-SHA1 %[ssl_c_sha1,hex]
Emeric Brun2525b6b2012-10-18 15:59:43 +020012483
Willy Tarreau74ca5042013-06-11 23:12:07 +020012484ssl_c_sig_alg : string
12485 Returns the name of the algorithm used to sign the certificate presented by
12486 the client when the incoming connection was made over an SSL/TLS transport
12487 layer.
Emeric Brun87855892012-10-17 17:39:35 +020012488
Willy Tarreau74ca5042013-06-11 23:12:07 +020012489ssl_c_used : boolean
12490 Returns true if current SSL session uses a client certificate even if current
12491 connection uses SSL session resumption. See also "ssl_fc_has_crt".
Emeric Brun7f56e742012-10-19 18:15:40 +020012492
Willy Tarreau74ca5042013-06-11 23:12:07 +020012493ssl_c_verify : integer
12494 Returns the verify result error ID when the incoming connection was made over
12495 an SSL/TLS transport layer, otherwise zero if no error is encountered. Please
12496 refer to your SSL library's documentation for an exhaustive list of error
12497 codes.
Emeric Brunce5ad802012-10-22 14:11:22 +020012498
Willy Tarreau74ca5042013-06-11 23:12:07 +020012499ssl_c_version : integer
12500 Returns the version of the certificate presented by the client when the
12501 incoming connection was made over an SSL/TLS transport layer.
Emeric Brunce5ad802012-10-22 14:11:22 +020012502
Emeric Brun43e79582014-10-29 19:03:26 +010012503ssl_f_der : binary
12504 Returns the DER formatted certificate presented by the frontend when the
12505 incoming connection was made over an SSL/TLS transport layer. When used for
12506 an ACL, the value(s) to match against can be passed in hexadecimal form.
12507
Willy Tarreau74ca5042013-06-11 23:12:07 +020012508ssl_f_i_dn([<entry>[,<occ>]]) : string
12509 When the incoming connection was made over an SSL/TLS transport layer,
12510 returns the full distinguished name of the issuer of the certificate
12511 presented by the frontend when no <entry> is specified, or the value of the
12512 first given entry found from the beginning of the DN. If a positive/negative
Emeric Brun87855892012-10-17 17:39:35 +020012513 occurrence number is specified as the optional second argument, it returns
Willy Tarreau74ca5042013-06-11 23:12:07 +020012514 the value of the nth given entry value from the beginning/end of the DN.
12515 For instance, "ssl_f_i_dn(OU,2)" the second organization unit, and
12516 "ssl_f_i_dn(CN)" retrieves the common name.
Emeric Brun87855892012-10-17 17:39:35 +020012517
Willy Tarreau74ca5042013-06-11 23:12:07 +020012518ssl_f_key_alg : string
12519 Returns the name of the algorithm used to generate the key of the certificate
12520 presented by the frontend when the incoming connection was made over an
12521 SSL/TLS transport layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020012522
Willy Tarreau74ca5042013-06-11 23:12:07 +020012523ssl_f_notafter : string
12524 Returns the end date presented by the frontend as a formatted string
12525 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
12526 transport layer.
Emeric Brun2525b6b2012-10-18 15:59:43 +020012527
Willy Tarreau74ca5042013-06-11 23:12:07 +020012528ssl_f_notbefore : string
12529 Returns the start date presented by the frontend as a formatted string
12530 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
12531 transport layer.
Emeric Brun87855892012-10-17 17:39:35 +020012532
Willy Tarreau74ca5042013-06-11 23:12:07 +020012533ssl_f_s_dn([<entry>[,<occ>]]) : string
12534 When the incoming connection was made over an SSL/TLS transport layer,
12535 returns the full distinguished name of the subject of the certificate
12536 presented by the frontend when no <entry> is specified, or the value of the
12537 first given entry found from the beginning of the DN. If a positive/negative
12538 occurrence number is specified as the optional second argument, it returns
12539 the value of the nth given entry value from the beginning/end of the DN.
12540 For instance, "ssl_f_s_dn(OU,2)" the second organization unit, and
12541 "ssl_f_s_dn(CN)" retrieves the common name.
Emeric Brunce5ad802012-10-22 14:11:22 +020012542
Willy Tarreau74ca5042013-06-11 23:12:07 +020012543ssl_f_serial : binary
12544 Returns the serial of the certificate presented by the frontend when the
12545 incoming connection was made over an SSL/TLS transport layer. When used for
12546 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun87855892012-10-17 17:39:35 +020012547
Emeric Brun55f4fa82014-04-30 17:11:25 +020012548ssl_f_sha1 : binary
12549 Returns the SHA-1 fingerprint of the certificate presented by the frontend
12550 when the incoming connection was made over an SSL/TLS transport layer. This
12551 can be used to know which certificate was chosen using SNI.
12552
Willy Tarreau74ca5042013-06-11 23:12:07 +020012553ssl_f_sig_alg : string
12554 Returns the name of the algorithm used to sign the certificate presented by
12555 the frontend when the incoming connection was made over an SSL/TLS transport
12556 layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020012557
Willy Tarreau74ca5042013-06-11 23:12:07 +020012558ssl_f_version : integer
12559 Returns the version of the certificate presented by the frontend when the
12560 incoming connection was made over an SSL/TLS transport layer.
12561
12562ssl_fc : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020012563 Returns true when the front connection was made via an SSL/TLS transport
12564 layer and is locally deciphered. This means it has matched a socket declared
12565 with a "bind" line having the "ssl" option.
12566
Willy Tarreau74ca5042013-06-11 23:12:07 +020012567 Example :
12568 # This passes "X-Proto: https" to servers when client connects over SSL
12569 listen http-https
12570 bind :80
12571 bind :443 ssl crt /etc/haproxy.pem
12572 http-request add-header X-Proto https if { ssl_fc }
12573
12574ssl_fc_alg_keysize : integer
12575 Returns the symmetric cipher key size supported in bits when the incoming
12576 connection was made over an SSL/TLS transport layer.
12577
12578ssl_fc_alpn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012579 This extracts the Application Layer Protocol Negotiation field from an
Willy Tarreau74ca5042013-06-11 23:12:07 +020012580 incoming connection made via a TLS transport layer and locally deciphered by
12581 haproxy. The result is a string containing the protocol name advertised by
12582 the client. The SSL library must have been built with support for TLS
12583 extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
12584 not advertised unless the "alpn" keyword on the "bind" line specifies a
12585 protocol list. Also, nothing forces the client to pick a protocol from this
12586 list, any other one may be requested. The TLS ALPN extension is meant to
12587 replace the TLS NPN extension. See also "ssl_fc_npn".
12588
Willy Tarreau74ca5042013-06-11 23:12:07 +020012589ssl_fc_cipher : string
12590 Returns the name of the used cipher when the incoming connection was made
12591 over an SSL/TLS transport layer.
Willy Tarreauab861d32013-04-02 02:30:41 +020012592
Willy Tarreau74ca5042013-06-11 23:12:07 +020012593ssl_fc_has_crt : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020012594 Returns true if a client certificate is present in an incoming connection over
12595 SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
Emeric Brun9143d372012-12-20 15:44:16 +010012596 Note: on SSL session resumption with Session ID or TLS ticket, client
12597 certificate is not present in the current connection but may be retrieved
12598 from the cache or the ticket. So prefer "ssl_c_used" if you want to check if
12599 current SSL session uses a client certificate.
Emeric Brun2525b6b2012-10-18 15:59:43 +020012600
Willy Tarreau74ca5042013-06-11 23:12:07 +020012601ssl_fc_has_sni : boolean
12602 This checks for the presence of a Server Name Indication TLS extension (SNI)
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020012603 in an incoming connection was made over an SSL/TLS transport layer. Returns
12604 true when the incoming connection presents a TLS SNI field. This requires
12605 that the SSL library is build with support for TLS extensions enabled (check
12606 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +020012607
Nenad Merdanovic26ea8222015-05-18 02:28:57 +020012608ssl_fc_is_resumed: boolean
12609 Returns true if the SSL/TLS session has been resumed through the use of
12610 SSL session cache or TLS tickets.
12611
Willy Tarreau74ca5042013-06-11 23:12:07 +020012612ssl_fc_npn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012613 This extracts the Next Protocol Negotiation field from an incoming connection
Willy Tarreau74ca5042013-06-11 23:12:07 +020012614 made via a TLS transport layer and locally deciphered by haproxy. The result
12615 is a string containing the protocol name advertised by the client. The SSL
12616 library must have been built with support for TLS extensions enabled (check
12617 haproxy -vv). Note that the TLS NPN extension is not advertised unless the
12618 "npn" keyword on the "bind" line specifies a protocol list. Also, nothing
12619 forces the client to pick a protocol from this list, any other one may be
12620 requested. Please note that the TLS NPN extension was replaced with ALPN.
Willy Tarreaua33c6542012-10-15 13:19:06 +020012621
Willy Tarreau74ca5042013-06-11 23:12:07 +020012622ssl_fc_protocol : string
12623 Returns the name of the used protocol when the incoming connection was made
12624 over an SSL/TLS transport layer.
Willy Tarreau7875d092012-09-10 08:20:03 +020012625
Emeric Brunb73a9b02014-04-30 18:49:19 +020012626ssl_fc_unique_id : binary
David Sc1ad52e2014-04-08 18:48:47 -040012627 When the incoming connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020012628 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
12629 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".
David Sc1ad52e2014-04-08 18:48:47 -040012630
Willy Tarreau74ca5042013-06-11 23:12:07 +020012631ssl_fc_session_id : binary
12632 Returns the SSL ID of the front connection when the incoming connection was
12633 made over an SSL/TLS transport layer. It is useful to stick a given client to
12634 a server. It is important to note that some browsers refresh their session ID
12635 every few minutes.
Willy Tarreau7875d092012-09-10 08:20:03 +020012636
Willy Tarreau74ca5042013-06-11 23:12:07 +020012637ssl_fc_sni : string
12638 This extracts the Server Name Indication TLS extension (SNI) field from an
12639 incoming connection made via an SSL/TLS transport layer and locally
12640 deciphered by haproxy. The result (when present) typically is a string
12641 matching the HTTPS host name (253 chars or less). The SSL library must have
12642 been built with support for TLS extensions enabled (check haproxy -vv).
12643
12644 This fetch is different from "req_ssl_sni" above in that it applies to the
12645 connection being deciphered by haproxy and not to SSL contents being blindly
12646 forwarded. See also "ssl_fc_sni_end" and "ssl_fc_sni_reg" below. This
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +020012647 requires that the SSL library is build with support for TLS extensions
12648 enabled (check haproxy -vv).
Willy Tarreau62644772008-07-16 18:36:06 +020012649
Willy Tarreau74ca5042013-06-11 23:12:07 +020012650 ACL derivatives :
Willy Tarreau74ca5042013-06-11 23:12:07 +020012651 ssl_fc_sni_end : suffix match
12652 ssl_fc_sni_reg : regex match
Emeric Brun589fcad2012-10-16 14:13:26 +020012653
Willy Tarreau74ca5042013-06-11 23:12:07 +020012654ssl_fc_use_keysize : integer
12655 Returns the symmetric cipher key size used in bits when the incoming
12656 connection was made over an SSL/TLS transport layer.
Willy Tarreaub6fb4202008-07-20 11:18:28 +020012657
Willy Tarreaub6fb4202008-07-20 11:18:28 +020012658
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200126597.3.5. Fetching samples from buffer contents (Layer 6)
Willy Tarreau74ca5042013-06-11 23:12:07 +020012660------------------------------------------------------
Willy Tarreaub6fb4202008-07-20 11:18:28 +020012661
Willy Tarreau74ca5042013-06-11 23:12:07 +020012662Fetching samples from buffer contents is a bit different from the previous
12663sample fetches above because the sampled data are ephemeral. These data can
12664only be used when they're available and will be lost when they're forwarded.
12665For this reason, samples fetched from buffer contents during a request cannot
12666be used in a response for example. Even while the data are being fetched, they
12667can change. Sometimes it is necessary to set some delays or combine multiple
12668sample fetch methods to ensure that the expected data are complete and usable,
12669for example through TCP request content inspection. Please see the "tcp-request
12670content" keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +020012671
Willy Tarreau74ca5042013-06-11 23:12:07 +020012672payload(<offset>,<length>) : binary (deprecated)
12673 This is an alias for "req.payload" when used in the context of a request (eg:
12674 "stick on", "stick match"), and for "res.payload" when used in the context of
12675 a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010012676
Willy Tarreau74ca5042013-06-11 23:12:07 +020012677payload_lv(<offset1>,<length>[,<offset2>]) : binary (deprecated)
12678 This is an alias for "req.payload_lv" when used in the context of a request
12679 (eg: "stick on", "stick match"), and for "res.payload_lv" when used in the
12680 context of a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010012681
Willy Tarreau74ca5042013-06-11 23:12:07 +020012682req.len : integer
12683req_len : integer (deprecated)
12684 Returns an integer value corresponding to the number of bytes present in the
12685 request buffer. This is mostly used in ACL. It is important to understand
12686 that this test does not return false as long as the buffer is changing. This
12687 means that a check with equality to zero will almost always immediately match
12688 at the beginning of the session, while a test for more data will wait for
12689 that data to come in and return false only when haproxy is certain that no
12690 more data will come in. This test was designed to be used with TCP request
12691 content inspection.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020012692
Willy Tarreau74ca5042013-06-11 23:12:07 +020012693req.payload(<offset>,<length>) : binary
12694 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020012695 in the request buffer. As a special case, if the <length> argument is zero,
12696 the the whole buffer from <offset> to the end is extracted. This can be used
12697 with ACLs in order to check for the presence of some content in a buffer at
12698 any location.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020012699
Willy Tarreau74ca5042013-06-11 23:12:07 +020012700 ACL alternatives :
12701 payload(<offset>,<length>) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020012702
Willy Tarreau74ca5042013-06-11 23:12:07 +020012703req.payload_lv(<offset1>,<length>[,<offset2>]) : binary
12704 This extracts a binary block whose size is specified at <offset1> for <length>
12705 bytes, and which starts at <offset2> if specified or just after the length in
12706 the request buffer. The <offset2> parameter also supports relative offsets if
12707 prepended with a '+' or '-' sign.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020012708
Willy Tarreau74ca5042013-06-11 23:12:07 +020012709 ACL alternatives :
12710 payload_lv(<offset1>,<length>[,<offset2>]) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020012711
Willy Tarreau74ca5042013-06-11 23:12:07 +020012712 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020012713
Willy Tarreau74ca5042013-06-11 23:12:07 +020012714req.proto_http : boolean
12715req_proto_http : boolean (deprecated)
12716 Returns true when data in the request buffer look like HTTP and correctly
12717 parses as such. It is the same parser as the common HTTP request parser which
12718 is used so there should be no surprises. The test does not match until the
12719 request is complete, failed or timed out. This test may be used to report the
12720 protocol in TCP logs, but the biggest use is to block TCP request analysis
12721 until a complete HTTP request is present in the buffer, for example to track
12722 a header.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020012723
Willy Tarreau74ca5042013-06-11 23:12:07 +020012724 Example:
12725 # track request counts per "base" (concatenation of Host+URL)
12726 tcp-request inspect-delay 10s
12727 tcp-request content reject if !HTTP
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020012728 tcp-request content track-sc0 base table req-rate
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020012729
Willy Tarreau74ca5042013-06-11 23:12:07 +020012730req.rdp_cookie([<name>]) : string
12731rdp_cookie([<name>]) : string (deprecated)
12732 When the request buffer looks like the RDP protocol, extracts the RDP cookie
12733 <name>, or any cookie if unspecified. The parser only checks for the first
12734 cookie, as illustrated in the RDP protocol specification. The cookie name is
12735 case insensitive. Generally the "MSTS" cookie name will be used, as it can
12736 contain the user name of the client connecting to the server if properly
12737 configured on the client. The "MSTSHASH" cookie is often used as well for
12738 session stickiness to servers.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020012739
Willy Tarreau74ca5042013-06-11 23:12:07 +020012740 This differs from "balance rdp-cookie" in that any balancing algorithm may be
12741 used and thus the distribution of clients to backend servers is not linked to
12742 a hash of the RDP cookie. It is envisaged that using a balancing algorithm
12743 such as "balance roundrobin" or "balance leastconn" will lead to a more even
12744 distribution of clients to backend servers than the hash used by "balance
12745 rdp-cookie".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020012746
Willy Tarreau74ca5042013-06-11 23:12:07 +020012747 ACL derivatives :
12748 req_rdp_cookie([<name>]) : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020012749
Willy Tarreau74ca5042013-06-11 23:12:07 +020012750 Example :
12751 listen tse-farm
12752 bind 0.0.0.0:3389
12753 # wait up to 5s for an RDP cookie in the request
12754 tcp-request inspect-delay 5s
12755 tcp-request content accept if RDP_COOKIE
12756 # apply RDP cookie persistence
12757 persist rdp-cookie
12758 # Persist based on the mstshash cookie
12759 # This is only useful makes sense if
12760 # balance rdp-cookie is not used
12761 stick-table type string size 204800
12762 stick on req.rdp_cookie(mstshash)
12763 server srv1 1.1.1.1:3389
12764 server srv1 1.1.1.2:3389
Willy Tarreau04aa6a92012-04-06 18:57:55 +020012765
Willy Tarreau74ca5042013-06-11 23:12:07 +020012766 See also : "balance rdp-cookie", "persist rdp-cookie", "tcp-request" and the
12767 "req_rdp_cookie" ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020012768
Willy Tarreau74ca5042013-06-11 23:12:07 +020012769req.rdp_cookie_cnt([name]) : integer
12770rdp_cookie_cnt([name]) : integer (deprecated)
12771 Tries to parse the request buffer as RDP protocol, then returns an integer
12772 corresponding to the number of RDP cookies found. If an optional cookie name
12773 is passed, only cookies matching this name are considered. This is mostly
12774 used in ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020012775
Willy Tarreau74ca5042013-06-11 23:12:07 +020012776 ACL derivatives :
12777 req_rdp_cookie_cnt([<name>]) : integer match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020012778
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020012779req.ssl_ec_ext : boolean
12780 Returns a boolean identifying if client sent the Supported Elliptic Curves
12781 Extension as defined in RFC4492, section 5.1. within the SSL ClientHello
12782 message. This can be used to present ECC compatible clients with EC certificate
12783 and to use RSA for all others, on the same IP address. Note that this only
12784 applies to raw contents found in the request buffer and not to contents
12785 deciphered via an SSL data layer, so this will not work with "bind" lines
12786 having the "ssl" option.
12787
Willy Tarreau74ca5042013-06-11 23:12:07 +020012788req.ssl_hello_type : integer
12789req_ssl_hello_type : integer (deprecated)
12790 Returns an integer value containing the type of the SSL hello message found
12791 in the request buffer if the buffer contains data that parse as a complete
12792 SSL (v3 or superior) client hello message. Note that this only applies to raw
12793 contents found in the request buffer and not to contents deciphered via an
12794 SSL data layer, so this will not work with "bind" lines having the "ssl"
12795 option. This is mostly used in ACL to detect presence of an SSL hello message
12796 that is supposed to contain an SSL session ID usable for stickiness.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020012797
Willy Tarreau74ca5042013-06-11 23:12:07 +020012798req.ssl_sni : string
12799req_ssl_sni : string (deprecated)
12800 Returns a string containing the value of the Server Name TLS extension sent
12801 by a client in a TLS stream passing through the request buffer if the buffer
12802 contains data that parse as a complete SSL (v3 or superior) client hello
12803 message. Note that this only applies to raw contents found in the request
12804 buffer and not to contents deciphered via an SSL data layer, so this will not
12805 work with "bind" lines having the "ssl" option. SNI normally contains the
12806 name of the host the client tries to connect to (for recent browsers). SNI is
12807 useful for allowing or denying access to certain hosts when SSL/TLS is used
12808 by the client. This test was designed to be used with TCP request content
12809 inspection. If content switching is needed, it is recommended to first wait
12810 for a complete client hello (type 1), like in the example below. See also
12811 "ssl_fc_sni".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020012812
Willy Tarreau74ca5042013-06-11 23:12:07 +020012813 ACL derivatives :
12814 req_ssl_sni : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020012815
Willy Tarreau74ca5042013-06-11 23:12:07 +020012816 Examples :
12817 # Wait for a client hello for at most 5 seconds
12818 tcp-request inspect-delay 5s
12819 tcp-request content accept if { req_ssl_hello_type 1 }
12820 use_backend bk_allow if { req_ssl_sni -f allowed_sites }
12821 default_backend bk_sorry_page
Willy Tarreau04aa6a92012-04-06 18:57:55 +020012822
Willy Tarreau74ca5042013-06-11 23:12:07 +020012823res.ssl_hello_type : integer
12824rep_ssl_hello_type : integer (deprecated)
12825 Returns an integer value containing the type of the SSL hello message found
12826 in the response buffer if the buffer contains data that parses as a complete
12827 SSL (v3 or superior) hello message. Note that this only applies to raw
12828 contents found in the response buffer and not to contents deciphered via an
12829 SSL data layer, so this will not work with "server" lines having the "ssl"
12830 option. This is mostly used in ACL to detect presence of an SSL hello message
12831 that is supposed to contain an SSL session ID usable for stickiness.
Willy Tarreau51539362012-05-08 12:46:28 +020012832
Willy Tarreau74ca5042013-06-11 23:12:07 +020012833req.ssl_ver : integer
12834req_ssl_ver : integer (deprecated)
12835 Returns an integer value containing the version of the SSL/TLS protocol of a
12836 stream present in the request buffer. Both SSLv2 hello messages and SSLv3
12837 messages are supported. TLSv1 is announced as SSL version 3.1. The value is
12838 composed of the major version multiplied by 65536, added to the minor
12839 version. Note that this only applies to raw contents found in the request
12840 buffer and not to contents deciphered via an SSL data layer, so this will not
12841 work with "bind" lines having the "ssl" option. The ACL version of the test
12842 matches against a decimal notation in the form MAJOR.MINOR (eg: 3.1). This
12843 fetch is mostly used in ACL.
Willy Tarreaud63335a2010-02-26 12:56:52 +010012844
Willy Tarreau74ca5042013-06-11 23:12:07 +020012845 ACL derivatives :
12846 req_ssl_ver : decimal match
Willy Tarreaud63335a2010-02-26 12:56:52 +010012847
Willy Tarreau47e8eba2013-09-11 23:28:46 +020012848res.len : integer
12849 Returns an integer value corresponding to the number of bytes present in the
12850 response buffer. This is mostly used in ACL. It is important to understand
12851 that this test does not return false as long as the buffer is changing. This
12852 means that a check with equality to zero will almost always immediately match
12853 at the beginning of the session, while a test for more data will wait for
12854 that data to come in and return false only when haproxy is certain that no
12855 more data will come in. This test was designed to be used with TCP response
12856 content inspection.
12857
Willy Tarreau74ca5042013-06-11 23:12:07 +020012858res.payload(<offset>,<length>) : binary
12859 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020012860 in the response buffer. As a special case, if the <length> argument is zero,
12861 the the whole buffer from <offset> to the end is extracted. This can be used
12862 with ACLs in order to check for the presence of some content in a buffer at
12863 any location.
Willy Tarreaud63335a2010-02-26 12:56:52 +010012864
Willy Tarreau74ca5042013-06-11 23:12:07 +020012865res.payload_lv(<offset1>,<length>[,<offset2>]) : binary
12866 This extracts a binary block whose size is specified at <offset1> for <length>
12867 bytes, and which starts at <offset2> if specified or just after the length in
12868 the response buffer. The <offset2> parameter also supports relative offsets
12869 if prepended with a '+' or '-' sign.
Willy Tarreaud63335a2010-02-26 12:56:52 +010012870
Willy Tarreau74ca5042013-06-11 23:12:07 +020012871 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaud63335a2010-02-26 12:56:52 +010012872
Willy Tarreau74ca5042013-06-11 23:12:07 +020012873wait_end : boolean
12874 This fetch either returns true when the inspection period is over, or does
12875 not fetch. It is only used in ACLs, in conjunction with content analysis to
12876 avoid returning a wrong verdict early. It may also be used to delay some
12877 actions, such as a delayed reject for some special addresses. Since it either
12878 stops the rules evaluation or immediately returns true, it is recommended to
12879 use this acl as the last one in a rule. Please note that the default ACL
12880 "WAIT_END" is always usable without prior declaration. This test was designed
12881 to be used with TCP request content inspection.
Willy Tarreaud63335a2010-02-26 12:56:52 +010012882
Willy Tarreau74ca5042013-06-11 23:12:07 +020012883 Examples :
12884 # delay every incoming request by 2 seconds
12885 tcp-request inspect-delay 2s
12886 tcp-request content accept if WAIT_END
Willy Tarreaud63335a2010-02-26 12:56:52 +010012887
Willy Tarreau74ca5042013-06-11 23:12:07 +020012888 # don't immediately tell bad guys they are rejected
12889 tcp-request inspect-delay 10s
12890 acl goodguys src 10.0.0.0/24
12891 acl badguys src 10.0.1.0/24
12892 tcp-request content accept if goodguys
12893 tcp-request content reject if badguys WAIT_END
12894 tcp-request content reject
12895
12896
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200128977.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +020012898--------------------------------------
12899
12900It is possible to fetch samples from HTTP contents, requests and responses.
12901This application layer is also called layer 7. It is only possible to fetch the
12902data in this section when a full HTTP request or response has been parsed from
12903its respective request or response buffer. This is always the case with all
12904HTTP specific rules and for sections running with "mode http". When using TCP
12905content inspection, it may be necessary to support an inspection delay in order
12906to let the request or response come in first. These fetches may require a bit
12907more CPU resources than the layer 4 ones, but not much since the request and
12908response are indexed.
12909
12910base : string
12911 This returns the concatenation of the first Host header and the path part of
12912 the request, which starts at the first slash and ends before the question
12913 mark. It can be useful in virtual hosted environments to detect URL abuses as
12914 well as to improve shared caches efficiency. Using this with a limited size
12915 stick table also allows one to collect statistics about most commonly
12916 requested objects by host/path. With ACLs it can allow simple content
12917 switching rules involving the host and the path at the same time, such as
12918 "www.example.com/favicon.ico". See also "path" and "uri".
12919
12920 ACL derivatives :
12921 base : exact string match
12922 base_beg : prefix match
12923 base_dir : subdir match
12924 base_dom : domain match
12925 base_end : suffix match
12926 base_len : length match
12927 base_reg : regex match
12928 base_sub : substring match
12929
12930base32 : integer
12931 This returns a 32-bit hash of the value returned by the "base" fetch method
12932 above. This is useful to track per-URL activity on high traffic sites without
12933 having to store all URLs. Instead a shorter hash is stored, saving a lot of
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020012934 memory. The output type is an unsigned integer. The hash function used is
12935 SDBM with full avalanche on the output. Technically, base32 is exactly equal
12936 to "base,sdbm(1)".
Willy Tarreau74ca5042013-06-11 23:12:07 +020012937
12938base32+src : binary
12939 This returns the concatenation of the base32 fetch above and the src fetch
12940 below. The resulting type is of type binary, with a size of 8 or 20 bytes
12941 depending on the source address family. This can be used to track per-IP,
12942 per-URL counters.
12943
William Lallemand65ad6e12014-01-31 15:08:02 +010012944capture.req.hdr(<idx>) : string
12945 This extracts the content of the header captured by the "capture request
12946 header", idx is the position of the capture keyword in the configuration.
12947 The first entry is an index of 0. See also: "capture request header".
12948
12949capture.req.method : string
12950 This extracts the METHOD of an HTTP request. It can be used in both request
12951 and response. Unlike "method", it can be used in both request and response
12952 because it's allocated.
12953
12954capture.req.uri : string
12955 This extracts the request's URI, which starts at the first slash and ends
12956 before the first space in the request (without the host part). Unlike "path"
12957 and "url", it can be used in both request and response because it's
12958 allocated.
12959
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020012960capture.req.ver : string
12961 This extracts the request's HTTP version and returns either "HTTP/1.0" or
12962 "HTTP/1.1". Unlike "req.ver", it can be used in both request, response, and
12963 logs because it relies on a persistent flag.
12964
William Lallemand65ad6e12014-01-31 15:08:02 +010012965capture.res.hdr(<idx>) : string
12966 This extracts the content of the header captured by the "capture response
12967 header", idx is the position of the capture keyword in the configuration.
12968 The first entry is an index of 0.
12969 See also: "capture response header"
12970
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020012971capture.res.ver : string
12972 This extracts the response's HTTP version and returns either "HTTP/1.0" or
12973 "HTTP/1.1". Unlike "res.ver", it can be used in logs because it relies on a
12974 persistent flag.
12975
Willy Tarreaua5910cc2015-05-02 00:46:08 +020012976req.body : binary
12977 This returns the HTTP request's available body as a block of data. It
12978 requires that the request body has been buffered made available using
12979 "option http-buffer-request". In case of chunked-encoded body, currently only
12980 the first chunk is analyzed.
12981
Thierry FOURNIER9826c772015-05-20 15:50:54 +020012982req.body_param([<name>) : string
12983 This fetch assumes that the body of the POST request is url-encoded. The user
12984 can check if the "content-type" contains the value
12985 "application/x-www-form-urlencoded". This extracts the first occurrence of the
12986 parameter <name> in the body, which ends before '&'. The parameter name is
12987 case-sensitive. If no name is given, any parameter will match, and the first
12988 one will be returned. The result is a string corresponding to the value of the
12989 parameter <name> as presented in the request body (no URL decoding is
12990 performed). Note that the ACL version of this fetch iterates over multiple
12991 parameters and will iteratively report all parameters values if no name is
12992 given.
12993
Willy Tarreaua5910cc2015-05-02 00:46:08 +020012994req.body_len : integer
12995 This returns the length of the HTTP request's available body in bytes. It may
12996 be lower than the advertised length if the body is larger than the buffer. It
12997 requires that the request body has been buffered made available using
12998 "option http-buffer-request".
12999
13000req.body_size : integer
13001 This returns the advertised length of the HTTP request's body in bytes. It
13002 will represent the advertised Content-Length header, or the size of the first
13003 chunk in case of chunked encoding. In order to parse the chunks, it requires
13004 that the request body has been buffered made available using
13005 "option http-buffer-request".
13006
Willy Tarreau74ca5042013-06-11 23:12:07 +020013007req.cook([<name>]) : string
13008cook([<name>]) : string (deprecated)
13009 This extracts the last occurrence of the cookie name <name> on a "Cookie"
13010 header line from the request, and returns its value as string. If no name is
13011 specified, the first cookie value is returned. When used with ACLs, all
13012 matching cookies are evaluated. Spaces around the name and the value are
13013 ignored as requested by the Cookie header specification (RFC6265). The cookie
13014 name is case-sensitive. Empty cookies are valid, so an empty cookie may very
13015 well return an empty value if it is present. Use the "found" match to detect
13016 presence. Use the res.cook() variant for response cookies sent by the server.
13017
13018 ACL derivatives :
13019 cook([<name>]) : exact string match
13020 cook_beg([<name>]) : prefix match
13021 cook_dir([<name>]) : subdir match
13022 cook_dom([<name>]) : domain match
13023 cook_end([<name>]) : suffix match
13024 cook_len([<name>]) : length match
13025 cook_reg([<name>]) : regex match
13026 cook_sub([<name>]) : substring match
Willy Tarreaud63335a2010-02-26 12:56:52 +010013027
Willy Tarreau74ca5042013-06-11 23:12:07 +020013028req.cook_cnt([<name>]) : integer
13029cook_cnt([<name>]) : integer (deprecated)
13030 Returns an integer value representing the number of occurrences of the cookie
13031 <name> in the request, or all cookies if <name> is not specified.
Willy Tarreaud63335a2010-02-26 12:56:52 +010013032
Willy Tarreau74ca5042013-06-11 23:12:07 +020013033req.cook_val([<name>]) : integer
13034cook_val([<name>]) : integer (deprecated)
13035 This extracts the last occurrence of the cookie name <name> on a "Cookie"
13036 header line from the request, and converts its value to an integer which is
13037 returned. If no name is specified, the first cookie value is returned. When
13038 used in ACLs, all matching names are iterated over until a value matches.
Willy Tarreau0e698542011-09-16 08:32:32 +020013039
Willy Tarreau74ca5042013-06-11 23:12:07 +020013040cookie([<name>]) : string (deprecated)
13041 This extracts the last occurrence of the cookie name <name> on a "Cookie"
13042 header line from the request, or a "Set-Cookie" header from the response, and
13043 returns its value as a string. A typical use is to get multiple clients
13044 sharing a same profile use the same server. This can be similar to what
Willy Tarreau294d0f02015-08-10 19:40:12 +020013045 "appsession" did with the "request-learn" statement, but with support for
Willy Tarreau74ca5042013-06-11 23:12:07 +020013046 multi-peer synchronization and state keeping across restarts. If no name is
13047 specified, the first cookie value is returned. This fetch should not be used
13048 anymore and should be replaced by req.cook() or res.cook() instead as it
13049 ambiguously uses the direction based on the context where it is used.
Willy Tarreaud63335a2010-02-26 12:56:52 +010013050
Willy Tarreau74ca5042013-06-11 23:12:07 +020013051hdr([<name>[,<occ>]]) : string
13052 This is equivalent to req.hdr() when used on requests, and to res.hdr() when
13053 used on responses. Please refer to these respective fetches for more details.
13054 In case of doubt about the fetch direction, please use the explicit ones.
13055 Note that contrary to the hdr() sample fetch method, the hdr_* ACL keywords
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013056 unambiguously apply to the request headers.
Willy Tarreaud63335a2010-02-26 12:56:52 +010013057
Willy Tarreau74ca5042013-06-11 23:12:07 +020013058req.fhdr(<name>[,<occ>]) : string
13059 This extracts the last occurrence of header <name> in an HTTP request. When
13060 used from an ACL, all occurrences are iterated over until a match is found.
13061 Optionally, a specific occurrence might be specified as a position number.
13062 Positive values indicate a position from the first occurrence, with 1 being
13063 the first one. Negative values indicate positions relative to the last one,
13064 with -1 being the last one. It differs from req.hdr() in that any commas
13065 present in the value are returned and are not used as delimiters. This is
13066 sometimes useful with headers such as User-Agent.
Willy Tarreaud63335a2010-02-26 12:56:52 +010013067
Willy Tarreau74ca5042013-06-11 23:12:07 +020013068req.fhdr_cnt([<name>]) : integer
13069 Returns an integer value representing the number of occurrences of request
13070 header field name <name>, or the total number of header fields if <name> is
13071 not specified. Contrary to its req.hdr_cnt() cousin, this function returns
13072 the number of full line headers and does not stop on commas.
Willy Tarreaud63335a2010-02-26 12:56:52 +010013073
Willy Tarreau74ca5042013-06-11 23:12:07 +020013074req.hdr([<name>[,<occ>]]) : string
13075 This extracts the last occurrence of header <name> in an HTTP request. When
13076 used from an ACL, all occurrences are iterated over until a match is found.
13077 Optionally, a specific occurrence might be specified as a position number.
13078 Positive values indicate a position from the first occurrence, with 1 being
13079 the first one. Negative values indicate positions relative to the last one,
13080 with -1 being the last one. A typical use is with the X-Forwarded-For header
13081 once converted to IP, associated with an IP stick-table. The function
13082 considers any comma as a delimiter for distinct values. If full-line headers
13083 are desired instead, use req.fhdr(). Please carefully check RFC2616 to know
13084 how certain headers are supposed to be parsed. Also, some of them are case
13085 insensitive (eg: Connection).
Willy Tarreaud63335a2010-02-26 12:56:52 +010013086
Willy Tarreau74ca5042013-06-11 23:12:07 +020013087 ACL derivatives :
13088 hdr([<name>[,<occ>]]) : exact string match
13089 hdr_beg([<name>[,<occ>]]) : prefix match
13090 hdr_dir([<name>[,<occ>]]) : subdir match
13091 hdr_dom([<name>[,<occ>]]) : domain match
13092 hdr_end([<name>[,<occ>]]) : suffix match
13093 hdr_len([<name>[,<occ>]]) : length match
13094 hdr_reg([<name>[,<occ>]]) : regex match
13095 hdr_sub([<name>[,<occ>]]) : substring match
13096
13097req.hdr_cnt([<name>]) : integer
13098hdr_cnt([<header>]) : integer (deprecated)
13099 Returns an integer value representing the number of occurrences of request
13100 header field name <name>, or the total number of header field values if
13101 <name> is not specified. It is important to remember that one header line may
13102 count as several headers if it has several values. The function considers any
13103 comma as a delimiter for distinct values. If full-line headers are desired
13104 instead, req.fhdr_cnt() should be used instead. With ACLs, it can be used to
13105 detect presence, absence or abuse of a specific header, as well as to block
13106 request smuggling attacks by rejecting requests which contain more than one
13107 of certain headers. See "req.hdr" for more information on header matching.
13108
13109req.hdr_ip([<name>[,<occ>]]) : ip
13110hdr_ip([<name>[,<occ>]]) : ip (deprecated)
13111 This extracts the last occurrence of header <name> in an HTTP request,
13112 converts it to an IPv4 or IPv6 address and returns this address. When used
13113 with ACLs, all occurrences are checked, and if <name> is omitted, every value
13114 of every header is checked. Optionally, a specific occurrence might be
13115 specified as a position number. Positive values indicate a position from the
13116 first occurrence, with 1 being the first one. Negative values indicate
13117 positions relative to the last one, with -1 being the last one. A typical use
13118 is with the X-Forwarded-For and X-Client-IP headers.
13119
13120req.hdr_val([<name>[,<occ>]]) : integer
13121hdr_val([<name>[,<occ>]]) : integer (deprecated)
13122 This extracts the last occurrence of header <name> in an HTTP request, and
13123 converts it to an integer value. When used with ACLs, all occurrences are
13124 checked, and if <name> is omitted, every value of every header is checked.
13125 Optionally, a specific occurrence might be specified as a position number.
13126 Positive values indicate a position from the first occurrence, with 1 being
13127 the first one. Negative values indicate positions relative to the last one,
13128 with -1 being the last one. A typical use is with the X-Forwarded-For header.
13129
13130http_auth(<userlist>) : boolean
13131 Returns a boolean indicating whether the authentication data received from
13132 the client match a username & password stored in the specified userlist. This
13133 fetch function is not really useful outside of ACLs. Currently only http
13134 basic auth is supported.
13135
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010013136http_auth_group(<userlist>) : string
13137 Returns a string corresponding to the user name found in the authentication
13138 data received from the client if both the user name and password are valid
13139 according to the specified userlist. The main purpose is to use it in ACLs
13140 where it is then checked whether the user belongs to any group within a list.
Willy Tarreau74ca5042013-06-11 23:12:07 +020013141 This fetch function is not really useful outside of ACLs. Currently only http
13142 basic auth is supported.
13143
13144 ACL derivatives :
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010013145 http_auth_group(<userlist>) : group ...
13146 Returns true when the user extracted from the request and whose password is
13147 valid according to the specified userlist belongs to at least one of the
13148 groups.
Willy Tarreau74ca5042013-06-11 23:12:07 +020013149
13150http_first_req : boolean
Willy Tarreau7f18e522010-10-22 20:04:13 +020013151 Returns true when the request being processed is the first one of the
13152 connection. This can be used to add or remove headers that may be missing
Willy Tarreau74ca5042013-06-11 23:12:07 +020013153 from some requests when a request is not the first one, or to help grouping
13154 requests in the logs.
Willy Tarreau7f18e522010-10-22 20:04:13 +020013155
Willy Tarreau74ca5042013-06-11 23:12:07 +020013156method : integer + string
13157 Returns an integer value corresponding to the method in the HTTP request. For
13158 example, "GET" equals 1 (check sources to establish the matching). Value 9
13159 means "other method" and may be converted to a string extracted from the
13160 stream. This should not be used directly as a sample, this is only meant to
13161 be used from ACLs, which transparently convert methods from patterns to these
13162 integer + string values. Some predefined ACL already check for most common
13163 methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013164
Willy Tarreau74ca5042013-06-11 23:12:07 +020013165 ACL derivatives :
13166 method : case insensitive method match
Willy Tarreau6a06a402007-07-15 20:15:28 +020013167
Willy Tarreau74ca5042013-06-11 23:12:07 +020013168 Example :
13169 # only accept GET and HEAD requests
13170 acl valid_method method GET HEAD
13171 http-request deny if ! valid_method
Willy Tarreau6a06a402007-07-15 20:15:28 +020013172
Willy Tarreau74ca5042013-06-11 23:12:07 +020013173path : string
13174 This extracts the request's URL path, which starts at the first slash and
13175 ends before the question mark (without the host part). A typical use is with
13176 prefetch-capable caches, and with portals which need to aggregate multiple
13177 information from databases and keep them in caches. Note that with outgoing
13178 caches, it would be wiser to use "url" instead. With ACLs, it's typically
13179 used to match exact file names (eg: "/login.php"), or directory parts using
13180 the derivative forms. See also the "url" and "base" fetch methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013181
Willy Tarreau74ca5042013-06-11 23:12:07 +020013182 ACL derivatives :
13183 path : exact string match
13184 path_beg : prefix match
13185 path_dir : subdir match
13186 path_dom : domain match
13187 path_end : suffix match
13188 path_len : length match
13189 path_reg : regex match
13190 path_sub : substring match
Willy Tarreau6a06a402007-07-15 20:15:28 +020013191
Willy Tarreau49ad95c2015-01-19 15:06:26 +010013192query : string
13193 This extracts the request's query string, which starts after the first
13194 question mark. If no question mark is present, this fetch returns nothing. If
13195 a question mark is present but nothing follows, it returns an empty string.
13196 This means it's possible to easily know whether a query string is present
13197 using the "found" matching method. This fetch is the completemnt of "path"
13198 which stops before the question mark.
13199
Willy Tarreaueb27ec72015-02-20 13:55:29 +010013200req.hdr_names([<delim>]) : string
13201 This builds a string made from the concatenation of all header names as they
13202 appear in the request when the rule is evaluated. The default delimiter is
13203 the comma (',') but it may be overridden as an optional argument <delim>. In
13204 this case, only the first character of <delim> is considered.
13205
Willy Tarreau74ca5042013-06-11 23:12:07 +020013206req.ver : string
13207req_ver : string (deprecated)
13208 Returns the version string from the HTTP request, for example "1.1". This can
13209 be useful for logs, but is mostly there for ACL. Some predefined ACL already
13210 check for versions 1.0 and 1.1.
Willy Tarreaud63335a2010-02-26 12:56:52 +010013211
Willy Tarreau74ca5042013-06-11 23:12:07 +020013212 ACL derivatives :
13213 req_ver : exact string match
Willy Tarreau0e698542011-09-16 08:32:32 +020013214
Willy Tarreau74ca5042013-06-11 23:12:07 +020013215res.comp : boolean
13216 Returns the boolean "true" value if the response has been compressed by
13217 HAProxy, otherwise returns boolean "false". This may be used to add
13218 information in the logs.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013219
Willy Tarreau74ca5042013-06-11 23:12:07 +020013220res.comp_algo : string
13221 Returns a string containing the name of the algorithm used if the response
13222 was compressed by HAProxy, for example : "deflate". This may be used to add
13223 some information in the logs.
Willy Tarreaud63335a2010-02-26 12:56:52 +010013224
Willy Tarreau74ca5042013-06-11 23:12:07 +020013225res.cook([<name>]) : string
13226scook([<name>]) : string (deprecated)
13227 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
13228 header line from the response, and returns its value as string. If no name is
13229 specified, the first cookie value is returned.
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020013230
Willy Tarreau74ca5042013-06-11 23:12:07 +020013231 ACL derivatives :
13232 scook([<name>] : exact string match
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020013233
Willy Tarreau74ca5042013-06-11 23:12:07 +020013234res.cook_cnt([<name>]) : integer
13235scook_cnt([<name>]) : integer (deprecated)
13236 Returns an integer value representing the number of occurrences of the cookie
13237 <name> in the response, or all cookies if <name> is not specified. This is
13238 mostly useful when combined with ACLs to detect suspicious responses.
Willy Tarreaud63335a2010-02-26 12:56:52 +010013239
Willy Tarreau74ca5042013-06-11 23:12:07 +020013240res.cook_val([<name>]) : integer
13241scook_val([<name>]) : integer (deprecated)
13242 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
13243 header line from the response, and converts its value to an integer which is
13244 returned. If no name is specified, the first cookie value is returned.
Willy Tarreaud63335a2010-02-26 12:56:52 +010013245
Willy Tarreau74ca5042013-06-11 23:12:07 +020013246res.fhdr([<name>[,<occ>]]) : string
13247 This extracts the last occurrence of header <name> in an HTTP response, or of
13248 the last header if no <name> is specified. Optionally, a specific occurrence
13249 might be specified as a position number. Positive values indicate a position
13250 from the first occurrence, with 1 being the first one. Negative values
13251 indicate positions relative to the last one, with -1 being the last one. It
13252 differs from res.hdr() in that any commas present in the value are returned
13253 and are not used as delimiters. If this is not desired, the res.hdr() fetch
13254 should be used instead. This is sometimes useful with headers such as Date or
13255 Expires.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013256
Willy Tarreau74ca5042013-06-11 23:12:07 +020013257res.fhdr_cnt([<name>]) : integer
13258 Returns an integer value representing the number of occurrences of response
13259 header field name <name>, or the total number of header fields if <name> is
13260 not specified. Contrary to its res.hdr_cnt() cousin, this function returns
13261 the number of full line headers and does not stop on commas. If this is not
13262 desired, the res.hdr_cnt() fetch should be used instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013263
Willy Tarreau74ca5042013-06-11 23:12:07 +020013264res.hdr([<name>[,<occ>]]) : string
13265shdr([<name>[,<occ>]]) : string (deprecated)
13266 This extracts the last occurrence of header <name> in an HTTP response, or of
13267 the last header if no <name> is specified. Optionally, a specific occurrence
13268 might be specified as a position number. Positive values indicate a position
13269 from the first occurrence, with 1 being the first one. Negative values
13270 indicate positions relative to the last one, with -1 being the last one. This
13271 can be useful to learn some data into a stick-table. The function considers
13272 any comma as a delimiter for distinct values. If this is not desired, the
13273 res.fhdr() fetch should be used instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013274
Willy Tarreau74ca5042013-06-11 23:12:07 +020013275 ACL derivatives :
13276 shdr([<name>[,<occ>]]) : exact string match
13277 shdr_beg([<name>[,<occ>]]) : prefix match
13278 shdr_dir([<name>[,<occ>]]) : subdir match
13279 shdr_dom([<name>[,<occ>]]) : domain match
13280 shdr_end([<name>[,<occ>]]) : suffix match
13281 shdr_len([<name>[,<occ>]]) : length match
13282 shdr_reg([<name>[,<occ>]]) : regex match
13283 shdr_sub([<name>[,<occ>]]) : substring match
13284
13285res.hdr_cnt([<name>]) : integer
13286shdr_cnt([<name>]) : integer (deprecated)
13287 Returns an integer value representing the number of occurrences of response
13288 header field name <name>, or the total number of header fields if <name> is
13289 not specified. The function considers any comma as a delimiter for distinct
13290 values. If this is not desired, the res.fhdr_cnt() fetch should be used
13291 instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013292
Willy Tarreau74ca5042013-06-11 23:12:07 +020013293res.hdr_ip([<name>[,<occ>]]) : ip
13294shdr_ip([<name>[,<occ>]]) : ip (deprecated)
13295 This extracts the last occurrence of header <name> in an HTTP response,
13296 convert it to an IPv4 or IPv6 address and returns this address. Optionally, a
13297 specific occurrence might be specified as a position number. Positive values
13298 indicate a position from the first occurrence, with 1 being the first one.
13299 Negative values indicate positions relative to the last one, with -1 being
13300 the last one. This can be useful to learn some data into a stick table.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013301
Willy Tarreaueb27ec72015-02-20 13:55:29 +010013302res.hdr_names([<delim>]) : string
13303 This builds a string made from the concatenation of all header names as they
13304 appear in the response when the rule is evaluated. The default delimiter is
13305 the comma (',') but it may be overridden as an optional argument <delim>. In
13306 this case, only the first character of <delim> is considered.
13307
Willy Tarreau74ca5042013-06-11 23:12:07 +020013308res.hdr_val([<name>[,<occ>]]) : integer
13309shdr_val([<name>[,<occ>]]) : integer (deprecated)
13310 This extracts the last occurrence of header <name> in an HTTP response, and
13311 converts it to an integer value. Optionally, a specific occurrence might be
13312 specified as a position number. Positive values indicate a position from the
13313 first occurrence, with 1 being the first one. Negative values indicate
13314 positions relative to the last one, with -1 being the last one. This can be
13315 useful to learn some data into a stick table.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010013316
Willy Tarreau74ca5042013-06-11 23:12:07 +020013317res.ver : string
13318resp_ver : string (deprecated)
13319 Returns the version string from the HTTP response, for example "1.1". This
13320 can be useful for logs, but is mostly there for ACL.
Willy Tarreau0e698542011-09-16 08:32:32 +020013321
Willy Tarreau74ca5042013-06-11 23:12:07 +020013322 ACL derivatives :
13323 resp_ver : exact string match
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010013324
Willy Tarreau74ca5042013-06-11 23:12:07 +020013325set-cookie([<name>]) : string (deprecated)
13326 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
13327 header line from the response and uses the corresponding value to match. This
Willy Tarreau294d0f02015-08-10 19:40:12 +020013328 can be comparable to what "appsession" did with default options, but with
Willy Tarreau74ca5042013-06-11 23:12:07 +020013329 support for multi-peer synchronization and state keeping across restarts.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010013330
Willy Tarreau74ca5042013-06-11 23:12:07 +020013331 This fetch function is deprecated and has been superseded by the "res.cook"
13332 fetch. This keyword will disappear soon.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010013333
Willy Tarreau74ca5042013-06-11 23:12:07 +020013334status : integer
13335 Returns an integer containing the HTTP status code in the HTTP response, for
13336 example, 302. It is mostly used within ACLs and integer ranges, for example,
13337 to remove any Location header if the response is not a 3xx.
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020013338
Willy Tarreau74ca5042013-06-11 23:12:07 +020013339url : string
13340 This extracts the request's URL as presented in the request. A typical use is
13341 with prefetch-capable caches, and with portals which need to aggregate
13342 multiple information from databases and keep them in caches. With ACLs, using
13343 "path" is preferred over using "url", because clients may send a full URL as
13344 is normally done with proxies. The only real use is to match "*" which does
13345 not match in "path", and for which there is already a predefined ACL. See
13346 also "path" and "base".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020013347
Willy Tarreau74ca5042013-06-11 23:12:07 +020013348 ACL derivatives :
13349 url : exact string match
13350 url_beg : prefix match
13351 url_dir : subdir match
13352 url_dom : domain match
13353 url_end : suffix match
13354 url_len : length match
13355 url_reg : regex match
13356 url_sub : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020013357
Willy Tarreau74ca5042013-06-11 23:12:07 +020013358url_ip : ip
13359 This extracts the IP address from the request's URL when the host part is
13360 presented as an IP address. Its use is very limited. For instance, a
13361 monitoring system might use this field as an alternative for the source IP in
13362 order to test what path a given source address would follow, or to force an
13363 entry in a table for a given source address. With ACLs it can be used to
13364 restrict access to certain systems through a proxy, for example when combined
13365 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020013366
Willy Tarreau74ca5042013-06-11 23:12:07 +020013367url_port : integer
13368 This extracts the port part from the request's URL. Note that if the port is
13369 not specified in the request, port 80 is assumed. With ACLs it can be used to
13370 restrict access to certain systems through a proxy, for example when combined
13371 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020013372
Willy Tarreau1ede1da2015-05-07 16:06:18 +020013373urlp([<name>[,<delim>]]) : string
13374url_param([<name>[,<delim>]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020013375 This extracts the first occurrence of the parameter <name> in the query
13376 string, which begins after either '?' or <delim>, and which ends before '&',
Willy Tarreau1ede1da2015-05-07 16:06:18 +020013377 ';' or <delim>. The parameter name is case-sensitive. If no name is given,
13378 any parameter will match, and the first one will be returned. The result is
13379 a string corresponding to the value of the parameter <name> as presented in
13380 the request (no URL decoding is performed). This can be used for session
Willy Tarreau74ca5042013-06-11 23:12:07 +020013381 stickiness based on a client ID, to extract an application cookie passed as a
13382 URL parameter, or in ACLs to apply some checks. Note that the ACL version of
Willy Tarreau1ede1da2015-05-07 16:06:18 +020013383 this fetch iterates over multiple parameters and will iteratively report all
13384 parameters values if no name is given
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020013385
Willy Tarreau74ca5042013-06-11 23:12:07 +020013386 ACL derivatives :
13387 urlp(<name>[,<delim>]) : exact string match
13388 urlp_beg(<name>[,<delim>]) : prefix match
13389 urlp_dir(<name>[,<delim>]) : subdir match
13390 urlp_dom(<name>[,<delim>]) : domain match
13391 urlp_end(<name>[,<delim>]) : suffix match
13392 urlp_len(<name>[,<delim>]) : length match
13393 urlp_reg(<name>[,<delim>]) : regex match
13394 urlp_sub(<name>[,<delim>]) : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020013395
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020013396
Willy Tarreau74ca5042013-06-11 23:12:07 +020013397 Example :
13398 # match http://example.com/foo?PHPSESSIONID=some_id
13399 stick on urlp(PHPSESSIONID)
13400 # match http://example.com/foo;JSESSIONID=some_id
13401 stick on urlp(JSESSIONID,;)
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020013402
Willy Tarreau1ede1da2015-05-07 16:06:18 +020013403urlp_val([<name>[,<delim>])] : integer
Willy Tarreau74ca5042013-06-11 23:12:07 +020013404 See "urlp" above. This one extracts the URL parameter <name> in the request
13405 and converts it to an integer value. This can be used for session stickiness
13406 based on a user ID for example, or with ACLs to match a page number or price.
Willy Tarreaua9fddca2012-07-31 07:51:48 +020013407
Willy Tarreau198a7442008-01-17 12:05:32 +010013408
Willy Tarreau74ca5042013-06-11 23:12:07 +0200134097.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013410---------------------
Willy Tarreauced27012008-01-17 20:35:34 +010013411
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013412Some predefined ACLs are hard-coded so that they do not have to be declared in
13413every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +020013414order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +010013415
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013416ACL name Equivalent to Usage
13417---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013418FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +020013419HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013420HTTP_1.0 req_ver 1.0 match HTTP version 1.0
13421HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +010013422HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
13423HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
13424HTTP_URL_SLASH url_beg / match URL beginning with "/"
13425HTTP_URL_STAR url * match URL equal to "*"
13426LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013427METH_CONNECT method CONNECT match HTTP CONNECT method
13428METH_GET method GET HEAD match HTTP GET or HEAD method
13429METH_HEAD method HEAD match HTTP HEAD method
13430METH_OPTIONS method OPTIONS match HTTP OPTIONS method
13431METH_POST method POST match HTTP POST method
13432METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +020013433RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013434REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +010013435TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013436WAIT_END wait_end wait for end of content analysis
13437---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +010013438
Willy Tarreaub937b7e2010-01-12 15:27:54 +010013439
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200134408. Logging
13441----------
Willy Tarreau844e3c52008-01-11 16:28:18 +010013442
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013443One of HAProxy's strong points certainly lies is its precise logs. It probably
13444provides the finest level of information available for such a product, which is
13445very important for troubleshooting complex environments. Standard information
13446provided in logs include client ports, TCP/HTTP state timers, precise session
13447state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010013448to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013449headers.
13450
13451In order to improve administrators reactivity, it offers a great transparency
13452about encountered problems, both internal and external, and it is possible to
13453send logs to different sources at the same time with different level filters :
13454
13455 - global process-level logs (system errors, start/stop, etc..)
13456 - per-instance system and internal errors (lack of resource, bugs, ...)
13457 - per-instance external troubles (servers up/down, max connections)
13458 - per-instance activity (client connections), either at the establishment or
13459 at the termination.
Jim Freeman9e8714b2015-05-26 09:16:34 -060013460 - per-request control of log-level, eg:
13461 http-request set-log-level silent if sensitive_request
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013462
13463The ability to distribute different levels of logs to different log servers
13464allow several production teams to interact and to fix their problems as soon
13465as possible. For example, the system team might monitor system-wide errors,
13466while the application team might be monitoring the up/down for their servers in
13467real time, and the security team might analyze the activity logs with one hour
13468delay.
13469
13470
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200134718.1. Log levels
13472---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013473
Simon Hormandf791f52011-05-29 15:01:10 +090013474TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013475source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +090013476HTTP request, HTTP return code, number of bytes transmitted, conditions
13477in which the session ended, and even exchanged cookies values. For example
13478track a particular user's problems. All messages may be sent to up to two
13479syslog servers. Check the "log" keyword in section 4.2 for more information
13480about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013481
13482
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200134838.2. Log formats
13484----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013485
William Lallemand48940402012-01-30 16:47:22 +010013486HAProxy supports 5 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +090013487and will be detailed in the following sections. A few of them may vary
13488slightly with the configuration, due to indicators specific to certain
13489options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013490
13491 - the default format, which is very basic and very rarely used. It only
13492 provides very basic information about the incoming connection at the moment
13493 it is accepted : source IP:port, destination IP:port, and frontend-name.
13494 This mode will eventually disappear so it will not be described to great
13495 extents.
13496
13497 - the TCP format, which is more advanced. This format is enabled when "option
13498 tcplog" is set on the frontend. HAProxy will then usually wait for the
13499 connection to terminate before logging. This format provides much richer
13500 information, such as timers, connection counts, queue size, etc... This
13501 format is recommended for pure TCP proxies.
13502
13503 - the HTTP format, which is the most advanced for HTTP proxying. This format
13504 is enabled when "option httplog" is set on the frontend. It provides the
13505 same information as the TCP format with some HTTP-specific fields such as
13506 the request, the status code, and captures of headers and cookies. This
13507 format is recommended for HTTP proxies.
13508
Emeric Brun3a058f32009-06-30 18:26:00 +020013509 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
13510 fields arranged in the same order as the CLF format. In this mode, all
13511 timers, captures, flags, etc... appear one per field after the end of the
13512 common fields, in the same order they appear in the standard HTTP format.
13513
William Lallemand48940402012-01-30 16:47:22 +010013514 - the custom log format, allows you to make your own log line.
13515
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013516Next sections will go deeper into details for each of these formats. Format
13517specification will be performed on a "field" basis. Unless stated otherwise, a
13518field is a portion of text delimited by any number of spaces. Since syslog
13519servers are susceptible of inserting fields at the beginning of a line, it is
13520always assumed that the first field is the one containing the process name and
13521identifier.
13522
13523Note : Since log lines may be quite long, the log examples in sections below
13524 might be broken into multiple lines. The example log lines will be
13525 prefixed with 3 closing angle brackets ('>>>') and each time a log is
13526 broken into multiple lines, each non-final line will end with a
13527 backslash ('\') and the next line will start indented by two characters.
13528
13529
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200135308.2.1. Default log format
13531-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013532
13533This format is used when no specific option is set. The log is emitted as soon
13534as the connection is accepted. One should note that this currently is the only
13535format which logs the request's destination IP and ports.
13536
13537 Example :
13538 listen www
13539 mode http
13540 log global
13541 server srv1 127.0.0.1:8000
13542
13543 >>> Feb 6 12:12:09 localhost \
13544 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
13545 (www/HTTP)
13546
13547 Field Format Extract from the example above
13548 1 process_name '[' pid ']:' haproxy[14385]:
13549 2 'Connect from' Connect from
13550 3 source_ip ':' source_port 10.0.1.2:33312
13551 4 'to' to
13552 5 destination_ip ':' destination_port 10.0.3.31:8012
13553 6 '(' frontend_name '/' mode ')' (www/HTTP)
13554
13555Detailed fields description :
13556 - "source_ip" is the IP address of the client which initiated the connection.
13557 - "source_port" is the TCP port of the client which initiated the connection.
13558 - "destination_ip" is the IP address the client connected to.
13559 - "destination_port" is the TCP port the client connected to.
13560 - "frontend_name" is the name of the frontend (or listener) which received
13561 and processed the connection.
13562 - "mode is the mode the frontend is operating (TCP or HTTP).
13563
Willy Tarreauceb24bc2010-11-09 12:46:41 +010013564In case of a UNIX socket, the source and destination addresses are marked as
13565"unix:" and the ports reflect the internal ID of the socket which accepted the
13566connection (the same ID as reported in the stats).
13567
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013568It is advised not to use this deprecated format for newer installations as it
13569will eventually disappear.
13570
13571
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200135728.2.2. TCP log format
13573---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013574
13575The TCP format is used when "option tcplog" is specified in the frontend, and
13576is the recommended format for pure TCP proxies. It provides a lot of precious
13577information for troubleshooting. Since this format includes timers and byte
13578counts, the log is normally emitted at the end of the session. It can be
13579emitted earlier if "option logasap" is specified, which makes sense in most
13580environments with long sessions such as remote terminals. Sessions which match
13581the "monitor" rules are never logged. It is also possible not to emit logs for
13582sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020013583specifying "option dontlognull" in the frontend. Successful connections will
13584not be logged if "option dontlog-normal" is specified in the frontend. A few
13585fields may slightly vary depending on some configuration options, those are
13586marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013587
13588 Example :
13589 frontend fnt
13590 mode tcp
13591 option tcplog
13592 log global
13593 default_backend bck
13594
13595 backend bck
13596 server srv1 127.0.0.1:8000
13597
13598 >>> Feb 6 12:12:56 localhost \
13599 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
13600 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
13601
13602 Field Format Extract from the example above
13603 1 process_name '[' pid ']:' haproxy[14387]:
13604 2 client_ip ':' client_port 10.0.1.2:33313
13605 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
13606 4 frontend_name fnt
13607 5 backend_name '/' server_name bck/srv1
13608 6 Tw '/' Tc '/' Tt* 0/0/5007
13609 7 bytes_read* 212
13610 8 termination_state --
13611 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
13612 10 srv_queue '/' backend_queue 0/0
13613
13614Detailed fields description :
13615 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010013616 connection to haproxy. If the connection was accepted on a UNIX socket
13617 instead, the IP address would be replaced with the word "unix". Note that
13618 when the connection is accepted on a socket configured with "accept-proxy"
13619 and the PROXY protocol is correctly used, then the logs will reflect the
13620 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013621
13622 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010013623 If the connection was accepted on a UNIX socket instead, the port would be
13624 replaced with the ID of the accepting socket, which is also reported in the
13625 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013626
13627 - "accept_date" is the exact date when the connection was received by haproxy
13628 (which might be very slightly different from the date observed on the
13629 network if there was some queuing in the system's backlog). This is usually
13630 the same date which may appear in any upstream firewall's log.
13631
13632 - "frontend_name" is the name of the frontend (or listener) which received
13633 and processed the connection.
13634
13635 - "backend_name" is the name of the backend (or listener) which was selected
13636 to manage the connection to the server. This will be the same as the
13637 frontend if no switching rule has been applied, which is common for TCP
13638 applications.
13639
13640 - "server_name" is the name of the last server to which the connection was
13641 sent, which might differ from the first one if there were connection errors
13642 and a redispatch occurred. Note that this server belongs to the backend
13643 which processed the request. If the connection was aborted before reaching
13644 a server, "<NOSRV>" is indicated instead of a server name.
13645
13646 - "Tw" is the total time in milliseconds spent waiting in the various queues.
13647 It can be "-1" if the connection was aborted before reaching the queue.
13648 See "Timers" below for more details.
13649
13650 - "Tc" is the total time in milliseconds spent waiting for the connection to
13651 establish to the final server, including retries. It can be "-1" if the
13652 connection was aborted before a connection could be established. See
13653 "Timers" below for more details.
13654
13655 - "Tt" is the total time in milliseconds elapsed between the accept and the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013656 last close. It covers all possible processing. There is one exception, if
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013657 "option logasap" was specified, then the time counting stops at the moment
13658 the log is emitted. In this case, a '+' sign is prepended before the value,
13659 indicating that the final one will be larger. See "Timers" below for more
13660 details.
13661
13662 - "bytes_read" is the total number of bytes transmitted from the server to
13663 the client when the log is emitted. If "option logasap" is specified, the
13664 this value will be prefixed with a '+' sign indicating that the final one
13665 may be larger. Please note that this value is a 64-bit counter, so log
13666 analysis tools must be able to handle it without overflowing.
13667
13668 - "termination_state" is the condition the session was in when the session
13669 ended. This indicates the session state, which side caused the end of
13670 session to happen, and for what reason (timeout, error, ...). The normal
13671 flags should be "--", indicating the session was closed by either end with
13672 no data remaining in buffers. See below "Session state at disconnection"
13673 for more details.
13674
13675 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040013676 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013677 limits have been reached. For instance, if actconn is close to 512 when
13678 multiple connection errors occur, chances are high that the system limits
13679 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013680 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013681
13682 - "feconn" is the total number of concurrent connections on the frontend when
13683 the session was logged. It is useful to estimate the amount of resource
13684 required to sustain high loads, and to detect when the frontend's "maxconn"
13685 has been reached. Most often when this value increases by huge jumps, it is
13686 because there is congestion on the backend servers, but sometimes it can be
13687 caused by a denial of service attack.
13688
13689 - "beconn" is the total number of concurrent connections handled by the
13690 backend when the session was logged. It includes the total number of
13691 concurrent connections active on servers as well as the number of
13692 connections pending in queues. It is useful to estimate the amount of
13693 additional servers needed to support high loads for a given application.
13694 Most often when this value increases by huge jumps, it is because there is
13695 congestion on the backend servers, but sometimes it can be caused by a
13696 denial of service attack.
13697
13698 - "srv_conn" is the total number of concurrent connections still active on
13699 the server when the session was logged. It can never exceed the server's
13700 configured "maxconn" parameter. If this value is very often close or equal
13701 to the server's "maxconn", it means that traffic regulation is involved a
13702 lot, meaning that either the server's maxconn value is too low, or that
13703 there aren't enough servers to process the load with an optimal response
13704 time. When only one of the server's "srv_conn" is high, it usually means
13705 that this server has some trouble causing the connections to take longer to
13706 be processed than on other servers.
13707
13708 - "retries" is the number of connection retries experienced by this session
13709 when trying to connect to the server. It must normally be zero, unless a
13710 server is being stopped at the same moment the connection was attempted.
13711 Frequent retries generally indicate either a network problem between
13712 haproxy and the server, or a misconfigured system backlog on the server
13713 preventing new connections from being queued. This field may optionally be
13714 prefixed with a '+' sign, indicating that the session has experienced a
13715 redispatch after the maximal retry count has been reached on the initial
13716 server. In this case, the server name appearing in the log is the one the
13717 connection was redispatched to, and not the first one, though both may
13718 sometimes be the same in case of hashing for instance. So as a general rule
13719 of thumb, when a '+' is present in front of the retry count, this count
13720 should not be attributed to the logged server.
13721
13722 - "srv_queue" is the total number of requests which were processed before
13723 this one in the server queue. It is zero when the request has not gone
13724 through the server queue. It makes it possible to estimate the approximate
13725 server's response time by dividing the time spent in queue by the number of
13726 requests in the queue. It is worth noting that if a session experiences a
13727 redispatch and passes through two server queues, their positions will be
13728 cumulated. A request should not pass through both the server queue and the
13729 backend queue unless a redispatch occurs.
13730
13731 - "backend_queue" is the total number of requests which were processed before
13732 this one in the backend's global queue. It is zero when the request has not
13733 gone through the global queue. It makes it possible to estimate the average
13734 queue length, which easily translates into a number of missing servers when
13735 divided by a server's "maxconn" parameter. It is worth noting that if a
13736 session experiences a redispatch, it may pass twice in the backend's queue,
13737 and then both positions will be cumulated. A request should not pass
13738 through both the server queue and the backend queue unless a redispatch
13739 occurs.
13740
13741
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200137428.2.3. HTTP log format
13743----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013744
13745The HTTP format is the most complete and the best suited for HTTP proxies. It
13746is enabled by when "option httplog" is specified in the frontend. It provides
13747the same level of information as the TCP format with additional features which
13748are specific to the HTTP protocol. Just like the TCP format, the log is usually
13749emitted at the end of the session, unless "option logasap" is specified, which
13750generally only makes sense for download sites. A session which matches the
13751"monitor" rules will never logged. It is also possible not to log sessions for
13752which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020013753frontend. Successful connections will not be logged if "option dontlog-normal"
13754is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013755
13756Most fields are shared with the TCP log, some being different. A few fields may
13757slightly vary depending on some configuration options. Those ones are marked
13758with a star ('*') after the field name below.
13759
13760 Example :
13761 frontend http-in
13762 mode http
13763 option httplog
13764 log global
13765 default_backend bck
13766
13767 backend static
13768 server srv1 127.0.0.1:8000
13769
13770 >>> Feb 6 12:14:14 localhost \
13771 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
13772 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 +010013773 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013774
13775 Field Format Extract from the example above
13776 1 process_name '[' pid ']:' haproxy[14389]:
13777 2 client_ip ':' client_port 10.0.1.2:33317
13778 3 '[' accept_date ']' [06/Feb/2009:12:14:14.655]
13779 4 frontend_name http-in
13780 5 backend_name '/' server_name static/srv1
13781 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt* 10/0/30/69/109
13782 7 status_code 200
13783 8 bytes_read* 2750
13784 9 captured_request_cookie -
13785 10 captured_response_cookie -
13786 11 termination_state ----
13787 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
13788 13 srv_queue '/' backend_queue 0/0
13789 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
13790 15 '{' captured_response_headers* '}' {}
13791 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +010013792
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013793
13794Detailed fields description :
13795 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010013796 connection to haproxy. If the connection was accepted on a UNIX socket
13797 instead, the IP address would be replaced with the word "unix". Note that
13798 when the connection is accepted on a socket configured with "accept-proxy"
13799 and the PROXY protocol is correctly used, then the logs will reflect the
13800 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013801
13802 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010013803 If the connection was accepted on a UNIX socket instead, the port would be
13804 replaced with the ID of the accepting socket, which is also reported in the
13805 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013806
13807 - "accept_date" is the exact date when the TCP connection was received by
13808 haproxy (which might be very slightly different from the date observed on
13809 the network if there was some queuing in the system's backlog). This is
13810 usually the same date which may appear in any upstream firewall's log. This
13811 does not depend on the fact that the client has sent the request or not.
13812
13813 - "frontend_name" is the name of the frontend (or listener) which received
13814 and processed the connection.
13815
13816 - "backend_name" is the name of the backend (or listener) which was selected
13817 to manage the connection to the server. This will be the same as the
13818 frontend if no switching rule has been applied.
13819
13820 - "server_name" is the name of the last server to which the connection was
13821 sent, which might differ from the first one if there were connection errors
13822 and a redispatch occurred. Note that this server belongs to the backend
13823 which processed the request. If the request was aborted before reaching a
13824 server, "<NOSRV>" is indicated instead of a server name. If the request was
13825 intercepted by the stats subsystem, "<STATS>" is indicated instead.
13826
13827 - "Tq" is the total time in milliseconds spent waiting for the client to send
13828 a full HTTP request, not counting data. It can be "-1" if the connection
13829 was aborted before a complete request could be received. It should always
13830 be very small because a request generally fits in one single packet. Large
13831 times here generally indicate network trouble between the client and
13832 haproxy. See "Timers" below for more details.
13833
13834 - "Tw" is the total time in milliseconds spent waiting in the various queues.
13835 It can be "-1" if the connection was aborted before reaching the queue.
13836 See "Timers" below for more details.
13837
13838 - "Tc" is the total time in milliseconds spent waiting for the connection to
13839 establish to the final server, including retries. It can be "-1" if the
13840 request was aborted before a connection could be established. See "Timers"
13841 below for more details.
13842
13843 - "Tr" is the total time in milliseconds spent waiting for the server to send
13844 a full HTTP response, not counting data. It can be "-1" if the request was
13845 aborted before a complete response could be received. It generally matches
13846 the server's processing time for the request, though it may be altered by
13847 the amount of data sent by the client to the server. Large times here on
13848 "GET" requests generally indicate an overloaded server. See "Timers" below
13849 for more details.
13850
13851 - "Tt" is the total time in milliseconds elapsed between the accept and the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013852 last close. It covers all possible processing. There is one exception, if
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013853 "option logasap" was specified, then the time counting stops at the moment
13854 the log is emitted. In this case, a '+' sign is prepended before the value,
13855 indicating that the final one will be larger. See "Timers" below for more
13856 details.
13857
13858 - "status_code" is the HTTP status code returned to the client. This status
13859 is generally set by the server, but it might also be set by haproxy when
13860 the server cannot be reached or when its response is blocked by haproxy.
13861
13862 - "bytes_read" is the total number of bytes transmitted to the client when
13863 the log is emitted. This does include HTTP headers. If "option logasap" is
13864 specified, the this value will be prefixed with a '+' sign indicating that
13865 the final one may be larger. Please note that this value is a 64-bit
13866 counter, so log analysis tools must be able to handle it without
13867 overflowing.
13868
13869 - "captured_request_cookie" is an optional "name=value" entry indicating that
13870 the client had this cookie in the request. The cookie name and its maximum
13871 length are defined by the "capture cookie" statement in the frontend
13872 configuration. The field is a single dash ('-') when the option is not
13873 set. Only one cookie may be captured, it is generally used to track session
13874 ID exchanges between a client and a server to detect session crossing
13875 between clients due to application bugs. For more details, please consult
13876 the section "Capturing HTTP headers and cookies" below.
13877
13878 - "captured_response_cookie" is an optional "name=value" entry indicating
13879 that the server has returned a cookie with its response. The cookie name
13880 and its maximum length are defined by the "capture cookie" statement in the
13881 frontend configuration. The field is a single dash ('-') when the option is
13882 not set. Only one cookie may be captured, it is generally used to track
13883 session ID exchanges between a client and a server to detect session
13884 crossing between clients due to application bugs. For more details, please
13885 consult the section "Capturing HTTP headers and cookies" below.
13886
13887 - "termination_state" is the condition the session was in when the session
13888 ended. This indicates the session state, which side caused the end of
13889 session to happen, for what reason (timeout, error, ...), just like in TCP
13890 logs, and information about persistence operations on cookies in the last
13891 two characters. The normal flags should begin with "--", indicating the
13892 session was closed by either end with no data remaining in buffers. See
13893 below "Session state at disconnection" for more details.
13894
13895 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040013896 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013897 limits have been reached. For instance, if actconn is close to 512 or 1024
13898 when multiple connection errors occur, chances are high that the system
13899 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013900 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010013901 system.
13902
13903 - "feconn" is the total number of concurrent connections on the frontend when
13904 the session was logged. It is useful to estimate the amount of resource
13905 required to sustain high loads, and to detect when the frontend's "maxconn"
13906 has been reached. Most often when this value increases by huge jumps, it is
13907 because there is congestion on the backend servers, but sometimes it can be
13908 caused by a denial of service attack.
13909
13910 - "beconn" is the total number of concurrent connections handled by the
13911 backend when the session was logged. It includes the total number of
13912 concurrent connections active on servers as well as the number of
13913 connections pending in queues. It is useful to estimate the amount of
13914 additional servers needed to support high loads for a given application.
13915 Most often when this value increases by huge jumps, it is because there is
13916 congestion on the backend servers, but sometimes it can be caused by a
13917 denial of service attack.
13918
13919 - "srv_conn" is the total number of concurrent connections still active on
13920 the server when the session was logged. It can never exceed the server's
13921 configured "maxconn" parameter. If this value is very often close or equal
13922 to the server's "maxconn", it means that traffic regulation is involved a
13923 lot, meaning that either the server's maxconn value is too low, or that
13924 there aren't enough servers to process the load with an optimal response
13925 time. When only one of the server's "srv_conn" is high, it usually means
13926 that this server has some trouble causing the requests to take longer to be
13927 processed than on other servers.
13928
13929 - "retries" is the number of connection retries experienced by this session
13930 when trying to connect to the server. It must normally be zero, unless a
13931 server is being stopped at the same moment the connection was attempted.
13932 Frequent retries generally indicate either a network problem between
13933 haproxy and the server, or a misconfigured system backlog on the server
13934 preventing new connections from being queued. This field may optionally be
13935 prefixed with a '+' sign, indicating that the session has experienced a
13936 redispatch after the maximal retry count has been reached on the initial
13937 server. In this case, the server name appearing in the log is the one the
13938 connection was redispatched to, and not the first one, though both may
13939 sometimes be the same in case of hashing for instance. So as a general rule
13940 of thumb, when a '+' is present in front of the retry count, this count
13941 should not be attributed to the logged server.
13942
13943 - "srv_queue" is the total number of requests which were processed before
13944 this one in the server queue. It is zero when the request has not gone
13945 through the server queue. It makes it possible to estimate the approximate
13946 server's response time by dividing the time spent in queue by the number of
13947 requests in the queue. It is worth noting that if a session experiences a
13948 redispatch and passes through two server queues, their positions will be
13949 cumulated. A request should not pass through both the server queue and the
13950 backend queue unless a redispatch occurs.
13951
13952 - "backend_queue" is the total number of requests which were processed before
13953 this one in the backend's global queue. It is zero when the request has not
13954 gone through the global queue. It makes it possible to estimate the average
13955 queue length, which easily translates into a number of missing servers when
13956 divided by a server's "maxconn" parameter. It is worth noting that if a
13957 session experiences a redispatch, it may pass twice in the backend's queue,
13958 and then both positions will be cumulated. A request should not pass
13959 through both the server queue and the backend queue unless a redispatch
13960 occurs.
13961
13962 - "captured_request_headers" is a list of headers captured in the request due
13963 to the presence of the "capture request header" statement in the frontend.
13964 Multiple headers can be captured, they will be delimited by a vertical bar
13965 ('|'). When no capture is enabled, the braces do not appear, causing a
13966 shift of remaining fields. It is important to note that this field may
13967 contain spaces, and that using it requires a smarter log parser than when
13968 it's not used. Please consult the section "Capturing HTTP headers and
13969 cookies" below for more details.
13970
13971 - "captured_response_headers" is a list of headers captured in the response
13972 due to the presence of the "capture response header" statement in the
13973 frontend. Multiple headers can be captured, they will be delimited by a
13974 vertical bar ('|'). When no capture is enabled, the braces do not appear,
13975 causing a shift of remaining fields. It is important to note that this
13976 field may contain spaces, and that using it requires a smarter log parser
13977 than when it's not used. Please consult the section "Capturing HTTP headers
13978 and cookies" below for more details.
13979
13980 - "http_request" is the complete HTTP request line, including the method,
13981 request and HTTP version string. Non-printable characters are encoded (see
13982 below the section "Non-printable characters"). This is always the last
13983 field, and it is always delimited by quotes and is the only one which can
13984 contain quotes. If new fields are added to the log format, they will be
13985 added before this field. This field might be truncated if the request is
13986 huge and does not fit in the standard syslog buffer (1024 characters). This
13987 is the reason why this field must always remain the last one.
13988
13989
Cyril Bontédc4d9032012-04-08 21:57:39 +0200139908.2.4. Custom log format
13991------------------------
William Lallemand48940402012-01-30 16:47:22 +010013992
Willy Tarreau2beef582012-12-20 17:22:52 +010013993The directive log-format allows you to customize the logs in http mode and tcp
William Lallemandbddd4fd2012-02-27 11:23:10 +010013994mode. It takes a string as argument.
William Lallemand48940402012-01-30 16:47:22 +010013995
13996HAproxy understands some log format variables. % precedes log format variables.
13997Variables can take arguments using braces ('{}'), and multiple arguments are
13998separated by commas within the braces. Flags may be added or removed by
13999prefixing them with a '+' or '-' sign.
14000
14001Special variable "%o" may be used to propagate its flags to all other
14002variables on the same format string. This is particularly handy with quoted
14003string formats ("Q").
14004
Willy Tarreauc8368452012-12-21 00:09:23 +010014005If a variable is named between square brackets ('[' .. ']') then it is used
Willy Tarreaube722a22014-06-13 16:31:59 +020014006as a sample expression rule (see section 7.3). This it useful to add some
Willy Tarreauc8368452012-12-21 00:09:23 +010014007less common information such as the client's SSL certificate's DN, or to log
14008the key that would be used to store an entry into a stick table.
14009
William Lallemand48940402012-01-30 16:47:22 +010014010Note: spaces must be escaped. A space character is considered as a separator.
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014011In order to emit a verbatim '%', it must be preceded by another '%' resulting
Willy Tarreau06d97f92013-12-02 17:45:48 +010014012in '%%'. HAProxy will automatically merge consecutive separators.
William Lallemand48940402012-01-30 16:47:22 +010014013
14014Flags are :
14015 * Q: quote a string
Jamie Gloudonaaa21002012-08-25 00:18:33 -040014016 * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid)
William Lallemand48940402012-01-30 16:47:22 +010014017
14018 Example:
14019
14020 log-format %T\ %t\ Some\ Text
14021 log-format %{+Q}o\ %t\ %s\ %{-Q}r
14022
14023At the moment, the default HTTP format is defined this way :
14024
Willy Tarreau2beef582012-12-20 17:22:52 +010014025 log-format %ci:%cp\ [%t]\ %ft\ %b/%s\ %Tq/%Tw/%Tc/%Tr/%Tt\ %ST\ %B\ %CC\ \
14026 %CS\ %tsc\ %ac/%fc/%bc/%sc/%rc\ %sq/%bq\ %hr\ %hs\ %{+Q}r
William Lallemand48940402012-01-30 16:47:22 +010014027
William Lallemandbddd4fd2012-02-27 11:23:10 +010014028the default CLF format is defined this way :
William Lallemand48940402012-01-30 16:47:22 +010014029
Willy Tarreau2beef582012-12-20 17:22:52 +010014030 log-format %{+Q}o\ %{-Q}ci\ -\ -\ [%T]\ %r\ %ST\ %B\ \"\"\ \"\"\ %cp\ \
Willy Tarreau773d65f2012-10-12 14:56:11 +020014031 %ms\ %ft\ %b\ %s\ \%Tq\ %Tw\ %Tc\ %Tr\ %Tt\ %tsc\ %ac\ %fc\ \
Willy Tarreau2beef582012-12-20 17:22:52 +010014032 %bc\ %sc\ %rc\ %sq\ %bq\ %CC\ %CS\ \%hrl\ %hsl
William Lallemand48940402012-01-30 16:47:22 +010014033
William Lallemandbddd4fd2012-02-27 11:23:10 +010014034and the default TCP format is defined this way :
14035
Willy Tarreau2beef582012-12-20 17:22:52 +010014036 log-format %ci:%cp\ [%t]\ %ft\ %b/%s\ %Tw/%Tc/%Tt\ %B\ %ts\ \
William Lallemandbddd4fd2012-02-27 11:23:10 +010014037 %ac/%fc/%bc/%sc/%rc\ %sq/%bq
14038
William Lallemand48940402012-01-30 16:47:22 +010014039Please refer to the table below for currently defined variables :
14040
William Lallemandbddd4fd2012-02-27 11:23:10 +010014041 +---+------+-----------------------------------------------+-------------+
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020014042 | R | var | field name (8.2.2 and 8.2.3 for description) | type |
William Lallemandbddd4fd2012-02-27 11:23:10 +010014043 +---+------+-----------------------------------------------+-------------+
14044 | | %o | special variable, apply flags on all next var | |
14045 +---+------+-----------------------------------------------+-------------+
Willy Tarreau2beef582012-12-20 17:22:52 +010014046 | | %B | bytes_read (from server to client) | numeric |
14047 | H | %CC | captured_request_cookie | string |
14048 | H | %CS | captured_response_cookie | string |
William Lallemand5f232402012-04-05 18:02:55 +020014049 | | %H | hostname | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000014050 | H | %HM | HTTP method (ex: POST) | string |
14051 | H | %HP | HTTP request URI without query string (path) | string |
Andrew Hayworthe63ac872015-07-31 16:14:16 +000014052 | H | %HQ | HTTP request URI query string (ex: ?bar=baz) | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000014053 | H | %HU | HTTP request URI (ex: /foo?bar=baz) | string |
14054 | H | %HV | HTTP version (ex: HTTP/1.0) | string |
William Lallemanda73203e2012-03-12 12:48:57 +010014055 | | %ID | unique-id | string |
Willy Tarreau4bf99632014-06-13 12:21:40 +020014056 | | %ST | status_code | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020014057 | | %T | gmt_date_time | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010014058 | | %Tc | Tc | numeric |
Yuxans Yao4e25b012012-10-19 10:36:09 +080014059 | | %Tl | local_date_time | date |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020014060 | H | %Tq | Tq | numeric |
14061 | H | %Tr | Tr | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020014062 | | %Ts | timestamp | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010014063 | | %Tt | Tt | numeric |
14064 | | %Tw | Tw | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010014065 | | %U | bytes_uploaded (from client to server) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010014066 | | %ac | actconn | numeric |
14067 | | %b | backend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010014068 | | %bc | beconn (backend concurrent connections) | numeric |
14069 | | %bi | backend_source_ip (connecting address) | IP |
14070 | | %bp | backend_source_port (connecting address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010014071 | | %bq | backend_queue | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010014072 | | %ci | client_ip (accepted address) | IP |
14073 | | %cp | client_port (accepted address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010014074 | | %f | frontend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010014075 | | %fc | feconn (frontend concurrent connections) | numeric |
14076 | | %fi | frontend_ip (accepting address) | IP |
14077 | | %fp | frontend_port (accepting address) | numeric |
Willy Tarreau773d65f2012-10-12 14:56:11 +020014078 | | %ft | frontend_name_transport ('~' suffix for SSL) | string |
Willy Tarreau7346acb2014-08-28 15:03:15 +020014079 | | %lc | frontend_log_counter | numeric |
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020014080 | | %hr | captured_request_headers default style | string |
14081 | | %hrl | captured_request_headers CLF style | string list |
14082 | | %hs | captured_response_headers default style | string |
14083 | | %hsl | captured_response_headers CLF style | string list |
Willy Tarreau812c88e2015-08-09 10:56:35 +020014084 | | %ms | accept date milliseconds (left-padded with 0) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020014085 | | %pid | PID | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020014086 | H | %r | http_request | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010014087 | | %rc | retries | numeric |
Willy Tarreau1f0da242014-01-25 11:01:50 +010014088 | | %rt | request_counter (HTTP req or TCP session) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010014089 | | %s | server_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010014090 | | %sc | srv_conn (server concurrent connections) | numeric |
14091 | | %si | server_IP (target address) | IP |
14092 | | %sp | server_port (target address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010014093 | | %sq | srv_queue | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020014094 | S | %sslc| ssl_ciphers (ex: AES-SHA) | string |
14095 | S | %sslv| ssl_version (ex: TLSv1) | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010014096 | | %t | date_time (with millisecond resolution) | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010014097 | | %ts | termination_state | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020014098 | H | %tsc | termination_state with cookie status | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010014099 +---+------+-----------------------------------------------+-------------+
William Lallemand48940402012-01-30 16:47:22 +010014100
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020014101 R = Restrictions : H = mode http only ; S = SSL only
William Lallemand48940402012-01-30 16:47:22 +010014102
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010014103
141048.2.5. Error log format
14105-----------------------
14106
14107When an incoming connection fails due to an SSL handshake or an invalid PROXY
14108protocol header, haproxy will log the event using a shorter, fixed line format.
14109By default, logs are emitted at the LOG_INFO level, unless the option
14110"log-separate-errors" is set in the backend, in which case the LOG_ERR level
14111will be used. Connections on which no data are exchanged (eg: probes) are not
14112logged if the "dontlognull" option is set.
14113
14114The format looks like this :
14115
14116 >>> Dec 3 18:27:14 localhost \
14117 haproxy[6103]: 127.0.0.1:56059 [03/Dec/2012:17:35:10.380] frt/f1: \
14118 Connection error during SSL handshake
14119
14120 Field Format Extract from the example above
14121 1 process_name '[' pid ']:' haproxy[6103]:
14122 2 client_ip ':' client_port 127.0.0.1:56059
14123 3 '[' accept_date ']' [03/Dec/2012:17:35:10.380]
14124 4 frontend_name "/" bind_name ":" frt/f1:
14125 5 message Connection error during SSL handshake
14126
14127These fields just provide minimal information to help debugging connection
14128failures.
14129
14130
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200141318.3. Advanced logging options
14132-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014133
14134Some advanced logging options are often looked for but are not easy to find out
14135just by looking at the various options. Here is an entry point for the few
14136options which can enable better logging. Please refer to the keywords reference
14137for more information about their usage.
14138
14139
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200141408.3.1. Disabling logging of external tests
14141------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014142
14143It is quite common to have some monitoring tools perform health checks on
14144haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
14145commercial load-balancer, and sometimes it will simply be a more complete
14146monitoring system such as Nagios. When the tests are very frequent, users often
14147ask how to disable logging for those checks. There are three possibilities :
14148
14149 - if connections come from everywhere and are just TCP probes, it is often
14150 desired to simply disable logging of connections without data exchange, by
14151 setting "option dontlognull" in the frontend. It also disables logging of
14152 port scans, which may or may not be desired.
14153
14154 - if the connection come from a known source network, use "monitor-net" to
14155 declare this network as monitoring only. Any host in this network will then
14156 only be able to perform health checks, and their requests will not be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014157 logged. This is generally appropriate to designate a list of equipment
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014158 such as other load-balancers.
14159
14160 - if the tests are performed on a known URI, use "monitor-uri" to declare
14161 this URI as dedicated to monitoring. Any host sending this request will
14162 only get the result of a health-check, and the request will not be logged.
14163
14164
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200141658.3.2. Logging before waiting for the session to terminate
14166----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014167
14168The problem with logging at end of connection is that you have no clue about
14169what is happening during very long sessions, such as remote terminal sessions
14170or large file downloads. This problem can be worked around by specifying
14171"option logasap" in the frontend. Haproxy will then log as soon as possible,
14172just before data transfer begins. This means that in case of TCP, it will still
14173log the connection status to the server, and in case of HTTP, it will log just
14174after processing the server headers. In this case, the number of bytes reported
14175is the number of header bytes sent to the client. In order to avoid confusion
14176with normal logs, the total time field and the number of bytes are prefixed
14177with a '+' sign which means that real numbers are certainly larger.
14178
14179
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200141808.3.3. Raising log level upon errors
14181------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020014182
14183Sometimes it is more convenient to separate normal traffic from errors logs,
14184for instance in order to ease error monitoring from log files. When the option
14185"log-separate-errors" is used, connections which experience errors, timeouts,
14186retries, redispatches or HTTP status codes 5xx will see their syslog level
14187raised from "info" to "err". This will help a syslog daemon store the log in
14188a separate file. It is very important to keep the errors in the normal traffic
14189file too, so that log ordering is not altered. You should also be careful if
14190you already have configured your syslog daemon to store all logs higher than
14191"notice" in an "admin" file, because the "err" level is higher than "notice".
14192
14193
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200141948.3.4. Disabling logging of successful connections
14195--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020014196
14197Although this may sound strange at first, some large sites have to deal with
14198multiple thousands of logs per second and are experiencing difficulties keeping
14199them intact for a long time or detecting errors within them. If the option
14200"dontlog-normal" is set on the frontend, all normal connections will not be
14201logged. In this regard, a normal connection is defined as one without any
14202error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
14203and a response with a status 5xx is not considered normal and will be logged
14204too. Of course, doing is is really discouraged as it will remove most of the
14205useful information from the logs. Do this only if you have no other
14206alternative.
14207
14208
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200142098.4. Timing events
14210------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014211
14212Timers provide a great help in troubleshooting network problems. All values are
14213reported in milliseconds (ms). These timers should be used in conjunction with
14214the session termination flags. In TCP mode with "option tcplog" set on the
14215frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
14216mode, 5 control points are reported under the form "Tq/Tw/Tc/Tr/Tt" :
14217
14218 - Tq: total time to get the client request (HTTP mode only). It's the time
14219 elapsed between the moment the client connection was accepted and the
14220 moment the proxy received the last HTTP header. The value "-1" indicates
14221 that the end of headers (empty line) has never been seen. This happens when
14222 the client closes prematurely or times out.
14223
14224 - Tw: total time spent in the queues waiting for a connection slot. It
14225 accounts for backend queue as well as the server queues, and depends on the
14226 queue size, and the time needed for the server to complete previous
14227 requests. The value "-1" means that the request was killed before reaching
14228 the queue, which is generally what happens with invalid or denied requests.
14229
14230 - Tc: total time to establish the TCP connection to the server. It's the time
14231 elapsed between the moment the proxy sent the connection request, and the
14232 moment it was acknowledged by the server, or between the TCP SYN packet and
14233 the matching SYN/ACK packet in return. The value "-1" means that the
14234 connection never established.
14235
14236 - Tr: server response time (HTTP mode only). It's the time elapsed between
14237 the moment the TCP connection was established to the server and the moment
14238 the server sent its complete response headers. It purely shows its request
14239 processing time, without the network overhead due to the data transmission.
14240 It is worth noting that when the client has data to send to the server, for
14241 instance during a POST request, the time already runs, and this can distort
14242 apparent response time. For this reason, it's generally wise not to trust
14243 too much this field for POST requests initiated from clients behind an
14244 untrusted network. A value of "-1" here means that the last the response
14245 header (empty line) was never seen, most likely because the server timeout
14246 stroke before the server managed to process the request.
14247
14248 - Tt: total session duration time, between the moment the proxy accepted it
14249 and the moment both ends were closed. The exception is when the "logasap"
14250 option is specified. In this case, it only equals (Tq+Tw+Tc+Tr), and is
14251 prefixed with a '+' sign. From this field, we can deduce "Td", the data
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014252 transmission time, by subtracting other timers when valid :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014253
14254 Td = Tt - (Tq + Tw + Tc + Tr)
14255
14256 Timers with "-1" values have to be excluded from this equation. In TCP
14257 mode, "Tq" and "Tr" have to be excluded too. Note that "Tt" can never be
14258 negative.
14259
14260These timers provide precious indications on trouble causes. Since the TCP
14261protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
14262that timers close to multiples of 3s are nearly always related to lost packets
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010014263due to network problems (wires, negotiation, congestion). Moreover, if "Tt" is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014264close to a timeout value specified in the configuration, it often means that a
14265session has been aborted on timeout.
14266
14267Most common cases :
14268
14269 - If "Tq" is close to 3000, a packet has probably been lost between the
14270 client and the proxy. This is very rare on local networks but might happen
14271 when clients are on far remote networks and send large requests. It may
14272 happen that values larger than usual appear here without any network cause.
14273 Sometimes, during an attack or just after a resource starvation has ended,
14274 haproxy may accept thousands of connections in a few milliseconds. The time
14275 spent accepting these connections will inevitably slightly delay processing
14276 of other connections, and it can happen that request times in the order of
14277 a few tens of milliseconds are measured after a few thousands of new
Patrick Mezard105faca2010-06-12 17:02:46 +020014278 connections have been accepted at once. Setting "option http-server-close"
14279 may display larger request times since "Tq" also measures the time spent
14280 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014281
14282 - If "Tc" is close to 3000, a packet has probably been lost between the
14283 server and the proxy during the server connection phase. This value should
14284 always be very low, such as 1 ms on local networks and less than a few tens
14285 of ms on remote networks.
14286
Willy Tarreau55165fe2009-05-10 12:02:55 +020014287 - If "Tr" is nearly always lower than 3000 except some rare values which seem
14288 to be the average majored by 3000, there are probably some packets lost
14289 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014290
14291 - If "Tt" is large even for small byte counts, it generally is because
14292 neither the client nor the server decides to close the connection, for
14293 instance because both have agreed on a keep-alive connection mode. In order
14294 to solve this issue, it will be needed to specify "option httpclose" on
14295 either the frontend or the backend. If the problem persists, it means that
14296 the server ignores the "close" connection mode and expects the client to
14297 close. Then it will be required to use "option forceclose". Having the
14298 smallest possible 'Tt' is important when connection regulation is used with
14299 the "maxconn" option on the servers, since no new connection will be sent
14300 to the server until another one is released.
14301
14302Other noticeable HTTP log cases ('xx' means any value to be ignored) :
14303
14304 Tq/Tw/Tc/Tr/+Tt The "option logasap" is present on the frontend and the log
14305 was emitted before the data phase. All the timers are valid
14306 except "Tt" which is shorter than reality.
14307
14308 -1/xx/xx/xx/Tt The client was not able to send a complete request in time
14309 or it aborted too early. Check the session termination flags
14310 then "timeout http-request" and "timeout client" settings.
14311
14312 Tq/-1/xx/xx/Tt It was not possible to process the request, maybe because
14313 servers were out of order, because the request was invalid
14314 or forbidden by ACL rules. Check the session termination
14315 flags.
14316
14317 Tq/Tw/-1/xx/Tt The connection could not establish on the server. Either it
14318 actively refused it or it timed out after Tt-(Tq+Tw) ms.
14319 Check the session termination flags, then check the
14320 "timeout connect" setting. Note that the tarpit action might
14321 return similar-looking patterns, with "Tw" equal to the time
14322 the client connection was maintained open.
14323
14324 Tq/Tw/Tc/-1/Tt The server has accepted the connection but did not return
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014325 a complete response in time, or it closed its connection
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014326 unexpectedly after Tt-(Tq+Tw+Tc) ms. Check the session
14327 termination flags, then check the "timeout server" setting.
14328
14329
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200143308.5. Session state at disconnection
14331-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014332
14333TCP and HTTP logs provide a session termination indicator in the
14334"termination_state" field, just before the number of active connections. It is
143352-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
14336each of which has a special meaning :
14337
14338 - On the first character, a code reporting the first event which caused the
14339 session to terminate :
14340
14341 C : the TCP session was unexpectedly aborted by the client.
14342
14343 S : the TCP session was unexpectedly aborted by the server, or the
14344 server explicitly refused it.
14345
14346 P : the session was prematurely aborted by the proxy, because of a
14347 connection limit enforcement, because a DENY filter was matched,
14348 because of a security check which detected and blocked a dangerous
14349 error in server response which might have caused information leak
Willy Tarreau570f2212013-06-10 16:42:09 +020014350 (eg: cacheable cookie).
14351
14352 L : the session was locally processed by haproxy and was not passed to
14353 a server. This is what happens for stats and redirects.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014354
14355 R : a resource on the proxy has been exhausted (memory, sockets, source
14356 ports, ...). Usually, this appears during the connection phase, and
14357 system logs should contain a copy of the precise error. If this
14358 happens, it must be considered as a very serious anomaly which
14359 should be fixed as soon as possible by any means.
14360
14361 I : an internal error was identified by the proxy during a self-check.
14362 This should NEVER happen, and you are encouraged to report any log
14363 containing this, because this would almost certainly be a bug. It
14364 would be wise to preventively restart the process after such an
14365 event too, in case it would be caused by memory corruption.
14366
Simon Horman752dc4a2011-06-21 14:34:59 +090014367 D : the session was killed by haproxy because the server was detected
14368 as down and was configured to kill all connections when going down.
14369
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070014370 U : the session was killed by haproxy on this backup server because an
14371 active server was detected as up and was configured to kill all
14372 backup connections when going up.
14373
Willy Tarreaua2a64e92011-09-07 23:01:56 +020014374 K : the session was actively killed by an admin operating on haproxy.
14375
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014376 c : the client-side timeout expired while waiting for the client to
14377 send or receive data.
14378
14379 s : the server-side timeout expired while waiting for the server to
14380 send or receive data.
14381
14382 - : normal session completion, both the client and the server closed
14383 with nothing left in the buffers.
14384
14385 - on the second character, the TCP or HTTP session state when it was closed :
14386
Willy Tarreauf7b30a92010-12-06 22:59:17 +010014387 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014388 (HTTP mode only). Nothing was sent to any server.
14389
14390 Q : the proxy was waiting in the QUEUE for a connection slot. This can
14391 only happen when servers have a 'maxconn' parameter set. It can
14392 also happen in the global queue after a redispatch consecutive to
14393 a failed attempt to connect to a dying server. If no redispatch is
14394 reported, then no connection attempt was made to any server.
14395
14396 C : the proxy was waiting for the CONNECTION to establish on the
14397 server. The server might at most have noticed a connection attempt.
14398
14399 H : the proxy was waiting for complete, valid response HEADERS from the
14400 server (HTTP only).
14401
14402 D : the session was in the DATA phase.
14403
14404 L : the proxy was still transmitting LAST data to the client while the
14405 server had already finished. This one is very rare as it can only
14406 happen when the client dies while receiving the last packets.
14407
14408 T : the request was tarpitted. It has been held open with the client
14409 during the whole "timeout tarpit" duration or until the client
14410 closed, both of which will be reported in the "Tw" timer.
14411
14412 - : normal session completion after end of data transfer.
14413
14414 - the third character tells whether the persistence cookie was provided by
14415 the client (only in HTTP mode) :
14416
14417 N : the client provided NO cookie. This is usually the case for new
14418 visitors, so counting the number of occurrences of this flag in the
14419 logs generally indicate a valid trend for the site frequentation.
14420
14421 I : the client provided an INVALID cookie matching no known server.
14422 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +020014423 cookies between HTTP/HTTPS sites, persistence conditionally
14424 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014425
14426 D : the client provided a cookie designating a server which was DOWN,
14427 so either "option persist" was used and the client was sent to
14428 this server, or it was not set and the client was redispatched to
14429 another server.
14430
Willy Tarreau996a92c2010-10-13 19:30:47 +020014431 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014432 server.
14433
Willy Tarreau996a92c2010-10-13 19:30:47 +020014434 E : the client provided a valid cookie, but with a last date which was
14435 older than what is allowed by the "maxidle" cookie parameter, so
14436 the cookie is consider EXPIRED and is ignored. The request will be
14437 redispatched just as if there was no cookie.
14438
14439 O : the client provided a valid cookie, but with a first date which was
14440 older than what is allowed by the "maxlife" cookie parameter, so
14441 the cookie is consider too OLD and is ignored. The request will be
14442 redispatched just as if there was no cookie.
14443
Willy Tarreauc89ccb62012-04-05 21:18:22 +020014444 U : a cookie was present but was not used to select the server because
14445 some other server selection mechanism was used instead (typically a
14446 "use-server" rule).
14447
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014448 - : does not apply (no cookie set in configuration).
14449
14450 - the last character reports what operations were performed on the persistence
14451 cookie returned by the server (only in HTTP mode) :
14452
14453 N : NO cookie was provided by the server, and none was inserted either.
14454
14455 I : no cookie was provided by the server, and the proxy INSERTED one.
14456 Note that in "cookie insert" mode, if the server provides a cookie,
14457 it will still be overwritten and reported as "I" here.
14458
Willy Tarreau996a92c2010-10-13 19:30:47 +020014459 U : the proxy UPDATED the last date in the cookie that was presented by
14460 the client. This can only happen in insert mode with "maxidle". It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014461 happens every time there is activity at a different date than the
Willy Tarreau996a92c2010-10-13 19:30:47 +020014462 date indicated in the cookie. If any other change happens, such as
14463 a redispatch, then the cookie will be marked as inserted instead.
14464
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014465 P : a cookie was PROVIDED by the server and transmitted as-is.
14466
14467 R : the cookie provided by the server was REWRITTEN by the proxy, which
14468 happens in "cookie rewrite" or "cookie prefix" modes.
14469
14470 D : the cookie provided by the server was DELETED by the proxy.
14471
14472 - : does not apply (no cookie set in configuration).
14473
Willy Tarreau996a92c2010-10-13 19:30:47 +020014474The combination of the two first flags gives a lot of information about what
14475was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014476helpful to detect server saturation, network troubles, local system resource
14477starvation, attacks, etc...
14478
14479The most common termination flags combinations are indicated below. They are
14480alphabetically sorted, with the lowercase set just after the upper case for
14481easier finding and understanding.
14482
14483 Flags Reason
14484
14485 -- Normal termination.
14486
14487 CC The client aborted before the connection could be established to the
14488 server. This can happen when haproxy tries to connect to a recently
14489 dead (or unchecked) server, and the client aborts while haproxy is
14490 waiting for the server to respond or for "timeout connect" to expire.
14491
14492 CD The client unexpectedly aborted during data transfer. This can be
14493 caused by a browser crash, by an intermediate equipment between the
14494 client and haproxy which decided to actively break the connection,
14495 by network routing issues between the client and haproxy, or by a
14496 keep-alive session between the server and the client terminated first
14497 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +010014498
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014499 cD The client did not send nor acknowledge any data for as long as the
14500 "timeout client" delay. This is often caused by network failures on
Cyril Bontédc4d9032012-04-08 21:57:39 +020014501 the client side, or the client simply leaving the net uncleanly.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014502
14503 CH The client aborted while waiting for the server to start responding.
14504 It might be the server taking too long to respond or the client
14505 clicking the 'Stop' button too fast.
14506
14507 cH The "timeout client" stroke while waiting for client data during a
14508 POST request. This is sometimes caused by too large TCP MSS values
14509 for PPPoE networks which cannot transport full-sized packets. It can
14510 also happen when client timeout is smaller than server timeout and
14511 the server takes too long to respond.
14512
14513 CQ The client aborted while its session was queued, waiting for a server
14514 with enough empty slots to accept it. It might be that either all the
14515 servers were saturated or that the assigned server was taking too
14516 long a time to respond.
14517
14518 CR The client aborted before sending a full HTTP request. Most likely
14519 the request was typed by hand using a telnet client, and aborted
14520 too early. The HTTP status code is likely a 400 here. Sometimes this
14521 might also be caused by an IDS killing the connection between haproxy
Willy Tarreau0f228a02015-05-01 15:37:53 +020014522 and the client. "option http-ignore-probes" can be used to ignore
14523 connections without any data transfer.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014524
14525 cR The "timeout http-request" stroke before the client sent a full HTTP
14526 request. This is sometimes caused by too large TCP MSS values on the
14527 client side for PPPoE networks which cannot transport full-sized
14528 packets, or by clients sending requests by hand and not typing fast
14529 enough, or forgetting to enter the empty line at the end of the
Willy Tarreau2705a612014-05-23 17:38:34 +020014530 request. The HTTP status code is likely a 408 here. Note: recently,
Willy Tarreau0f228a02015-05-01 15:37:53 +020014531 some browsers started to implement a "pre-connect" feature consisting
14532 in speculatively connecting to some recently visited web sites just
14533 in case the user would like to visit them. This results in many
14534 connections being established to web sites, which end up in 408
14535 Request Timeout if the timeout strikes first, or 400 Bad Request when
14536 the browser decides to close them first. These ones pollute the log
14537 and feed the error counters. Some versions of some browsers have even
14538 been reported to display the error code. It is possible to work
14539 around the undesirable effects of this behaviour by adding "option
14540 http-ignore-probes" in the frontend, resulting in connections with
14541 zero data transfer to be totally ignored. This will definitely hide
14542 the errors of people experiencing connectivity issues though.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014543
14544 CT The client aborted while its session was tarpitted. It is important to
14545 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +020014546 wrong tarpit rules have been written. If a lot of them happen, it
14547 might make sense to lower the "timeout tarpit" value to something
14548 closer to the average reported "Tw" timer, in order not to consume
14549 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014550
Willy Tarreau570f2212013-06-10 16:42:09 +020014551 LR The request was intercepted and locally handled by haproxy. Generally
14552 it means that this was a redirect or a stats request.
14553
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010014554 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014555 the TCP connection (the proxy received a TCP RST or an ICMP message
14556 in return). Under some circumstances, it can also be the network
14557 stack telling the proxy that the server is unreachable (eg: no route,
14558 or no ARP response on local network). When this happens in HTTP mode,
14559 the status code is likely a 502 or 503 here.
14560
14561 sC The "timeout connect" stroke before a connection to the server could
14562 complete. When this happens in HTTP mode, the status code is likely a
14563 503 or 504 here.
14564
14565 SD The connection to the server died with an error during the data
14566 transfer. This usually means that haproxy has received an RST from
14567 the server or an ICMP message from an intermediate equipment while
14568 exchanging data with the server. This can be caused by a server crash
14569 or by a network issue on an intermediate equipment.
14570
14571 sD The server did not send nor acknowledge any data for as long as the
14572 "timeout server" setting during the data phase. This is often caused
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010014573 by too short timeouts on L4 equipments before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014574 load-balancers, ...), as well as keep-alive sessions maintained
14575 between the client and the server expiring first on haproxy.
14576
14577 SH The server aborted before sending its full HTTP response headers, or
14578 it crashed while processing the request. Since a server aborting at
14579 this moment is very rare, it would be wise to inspect its logs to
14580 control whether it crashed and why. The logged request may indicate a
14581 small set of faulty requests, demonstrating bugs in the application.
14582 Sometimes this might also be caused by an IDS killing the connection
14583 between haproxy and the server.
14584
14585 sH The "timeout server" stroke before the server could return its
14586 response headers. This is the most common anomaly, indicating too
14587 long transactions, probably caused by server or database saturation.
14588 The immediate workaround consists in increasing the "timeout server"
14589 setting, but it is important to keep in mind that the user experience
14590 will suffer from these long response times. The only long term
14591 solution is to fix the application.
14592
14593 sQ The session spent too much time in queue and has been expired. See
14594 the "timeout queue" and "timeout connect" settings to find out how to
14595 fix this if it happens too often. If it often happens massively in
14596 short periods, it may indicate general problems on the affected
14597 servers due to I/O or database congestion, or saturation caused by
14598 external attacks.
14599
14600 PC The proxy refused to establish a connection to the server because the
14601 process' socket limit has been reached while attempting to connect.
Cyril Bontédc4d9032012-04-08 21:57:39 +020014602 The global "maxconn" parameter may be increased in the configuration
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014603 so that it does not happen anymore. This status is very rare and
14604 might happen when the global "ulimit-n" parameter is forced by hand.
14605
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010014606 PD The proxy blocked an incorrectly formatted chunked encoded message in
14607 a request or a response, after the server has emitted its headers. In
14608 most cases, this will indicate an invalid message from the server to
Willy Tarreauf3a3e132013-08-31 08:16:26 +020014609 the client. Haproxy supports chunk sizes of up to 2GB - 1 (2147483647
14610 bytes). Any larger size will be considered as an error.
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010014611
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014612 PH The proxy blocked the server's response, because it was invalid,
14613 incomplete, dangerous (cache control), or matched a security filter.
14614 In any case, an HTTP 502 error is sent to the client. One possible
14615 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010014616 containing unauthorized characters. It is also possible but quite
14617 rare, that the proxy blocked a chunked-encoding request from the
14618 client due to an invalid syntax, before the server responded. In this
14619 case, an HTTP 400 error is sent to the client and reported in the
14620 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014621
14622 PR The proxy blocked the client's HTTP request, either because of an
14623 invalid HTTP syntax, in which case it returned an HTTP 400 error to
14624 the client, or because a deny filter matched, in which case it
14625 returned an HTTP 403 error.
14626
14627 PT The proxy blocked the client's request and has tarpitted its
14628 connection before returning it a 500 server error. Nothing was sent
14629 to the server. The connection was maintained open for as long as
14630 reported by the "Tw" timer field.
14631
14632 RC A local resource has been exhausted (memory, sockets, source ports)
14633 preventing the connection to the server from establishing. The error
14634 logs will tell precisely what was missing. This is very rare and can
14635 only be solved by proper system tuning.
14636
Willy Tarreau996a92c2010-10-13 19:30:47 +020014637The combination of the two last flags gives a lot of information about how
14638persistence was handled by the client, the server and by haproxy. This is very
14639important to troubleshoot disconnections, when users complain they have to
14640re-authenticate. The commonly encountered flags are :
14641
14642 -- Persistence cookie is not enabled.
14643
14644 NN No cookie was provided by the client, none was inserted in the
14645 response. For instance, this can be in insert mode with "postonly"
14646 set on a GET request.
14647
14648 II A cookie designating an invalid server was provided by the client,
14649 a valid one was inserted in the response. This typically happens when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040014650 a "server" entry is removed from the configuration, since its cookie
Willy Tarreau996a92c2010-10-13 19:30:47 +020014651 value can be presented by a client when no other server knows it.
14652
14653 NI No cookie was provided by the client, one was inserted in the
14654 response. This typically happens for first requests from every user
14655 in "insert" mode, which makes it an easy way to count real users.
14656
14657 VN A cookie was provided by the client, none was inserted in the
14658 response. This happens for most responses for which the client has
14659 already got a cookie.
14660
14661 VU A cookie was provided by the client, with a last visit date which is
14662 not completely up-to-date, so an updated cookie was provided in
14663 response. This can also happen if there was no date at all, or if
14664 there was a date but the "maxidle" parameter was not set, so that the
14665 cookie can be switched to unlimited time.
14666
14667 EI A cookie was provided by the client, with a last visit date which is
14668 too old for the "maxidle" parameter, so the cookie was ignored and a
14669 new cookie was inserted in the response.
14670
14671 OI A cookie was provided by the client, with a first visit date which is
14672 too old for the "maxlife" parameter, so the cookie was ignored and a
14673 new cookie was inserted in the response.
14674
14675 DI The server designated by the cookie was down, a new server was
14676 selected and a new cookie was emitted in the response.
14677
14678 VI The server designated by the cookie was not marked dead but could not
14679 be reached. A redispatch happened and selected another one, which was
14680 then advertised in the response.
14681
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014682
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200146838.6. Non-printable characters
14684-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014685
14686In order not to cause trouble to log analysis tools or terminals during log
14687consulting, non-printable characters are not sent as-is into log files, but are
14688converted to the two-digits hexadecimal representation of their ASCII code,
14689prefixed by the character '#'. The only characters that can be logged without
14690being escaped are comprised between 32 and 126 (inclusive). Obviously, the
14691escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
14692is the same for the character '"' which becomes "#22", as well as '{', '|' and
14693'}' when logging headers.
14694
14695Note that the space character (' ') is not encoded in headers, which can cause
14696issues for tools relying on space count to locate fields. A typical header
14697containing spaces is "User-Agent".
14698
14699Last, it has been observed that some syslog daemons such as syslog-ng escape
14700the quote ('"') with a backslash ('\'). The reverse operation can safely be
14701performed since no quote may appear anywhere else in the logs.
14702
14703
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200147048.7. Capturing HTTP cookies
14705---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014706
14707Cookie capture simplifies the tracking a complete user session. This can be
14708achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014709section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014710cookie will simultaneously be checked in the request ("Cookie:" header) and in
14711the response ("Set-Cookie:" header). The respective values will be reported in
14712the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014713locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014714not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
14715user switches to a new session for example, because the server will reassign it
14716a new cookie. It is also possible to detect if a server unexpectedly sets a
14717wrong cookie to a client, leading to session crossing.
14718
14719 Examples :
14720 # capture the first cookie whose name starts with "ASPSESSION"
14721 capture cookie ASPSESSION len 32
14722
14723 # capture the first cookie whose name is exactly "vgnvisitor"
14724 capture cookie vgnvisitor= len 32
14725
14726
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200147278.8. Capturing HTTP headers
14728---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014729
14730Header captures are useful to track unique request identifiers set by an upper
14731proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
14732the response, one can search for information about the response length, how the
14733server asked the cache to behave, or an object location during a redirection.
14734
14735Header captures are performed using the "capture request header" and "capture
14736response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014737section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014738
14739It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010014740time. Non-existent headers are logged as empty strings, and if one header
14741appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014742are grouped within braces '{' and '}' in the same order as they were declared,
14743and delimited with a vertical bar '|' without any space. Response headers
14744follow the same representation, but are displayed after a space following the
14745request headers block. These blocks are displayed just before the HTTP request
14746in the logs.
14747
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020014748As a special case, it is possible to specify an HTTP header capture in a TCP
14749frontend. The purpose is to enable logging of headers which will be parsed in
14750an HTTP backend if the request is then switched to this HTTP backend.
14751
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014752 Example :
14753 # This instance chains to the outgoing proxy
14754 listen proxy-out
14755 mode http
14756 option httplog
14757 option logasap
14758 log global
14759 server cache1 192.168.1.1:3128
14760
14761 # log the name of the virtual server
14762 capture request header Host len 20
14763
14764 # log the amount of data uploaded during a POST
14765 capture request header Content-Length len 10
14766
14767 # log the beginning of the referrer
14768 capture request header Referer len 20
14769
14770 # server name (useful for outgoing proxies only)
14771 capture response header Server len 20
14772
14773 # logging the content-length is useful with "option logasap"
14774 capture response header Content-Length len 10
14775
14776 # log the expected cache behaviour on the response
14777 capture response header Cache-Control len 8
14778
14779 # the Via header will report the next proxy's name
14780 capture response header Via len 20
14781
14782 # log the URL location during a redirection
14783 capture response header Location len 20
14784
14785 >>> Aug 9 20:26:09 localhost \
14786 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
14787 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
14788 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
14789 "GET http://fr.adserver.yahoo.com/"
14790
14791 >>> Aug 9 20:30:46 localhost \
14792 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
14793 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
14794 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010014795 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014796
14797 >>> Aug 9 20:30:46 localhost \
14798 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
14799 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
14800 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
14801 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010014802 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014803
14804
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200148058.9. Examples of logs
14806---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014807
14808These are real-world examples of logs accompanied with an explanation. Some of
14809them have been made up by hand. The syslog part has been removed for better
14810reading. Their sole purpose is to explain how to decipher them.
14811
14812 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
14813 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
14814 "HEAD / HTTP/1.0"
14815
14816 => long request (6.5s) entered by hand through 'telnet'. The server replied
14817 in 147 ms, and the session ended normally ('----')
14818
14819 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
14820 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
14821 0/9 "HEAD / HTTP/1.0"
14822
14823 => Idem, but the request was queued in the global queue behind 9 other
14824 requests, and waited there for 1230 ms.
14825
14826 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
14827 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
14828 "GET /image.iso HTTP/1.0"
14829
14830 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010014831 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014832 14 ms, 243 bytes of headers were sent to the client, and total time from
14833 accept to first data byte is 30 ms.
14834
14835 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
14836 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
14837 "GET /cgi-bin/bug.cgi? HTTP/1.0"
14838
14839 => the proxy blocked a server response either because of an "rspdeny" or
14840 "rspideny" filter, or because the response was improperly formatted and
Willy Tarreau3c92c5f2011-08-28 09:45:47 +020014841 not HTTP-compliant, or because it blocked sensitive information which
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014842 risked being cached. In this case, the response is replaced with a "502
14843 bad gateway". The flags ("PH--") tell us that it was haproxy who decided
14844 to return the 502 and not the server.
14845
14846 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +010014847 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 +010014848
14849 => the client never completed its request and aborted itself ("C---") after
14850 8.5s, while the proxy was waiting for the request headers ("-R--").
14851 Nothing was sent to any server.
14852
14853 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
14854 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
14855
14856 => The client never completed its request, which was aborted by the
14857 time-out ("c---") after 50s, while the proxy was waiting for the request
14858 headers ("-R--"). Nothing was sent to any server, but the proxy could
14859 send a 408 return code to the client.
14860
14861 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
14862 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
14863
14864 => This log was produced with "option tcplog". The client timed out after
14865 5 seconds ("c----").
14866
14867 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
14868 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +010014869 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014870
14871 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014872 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +010014873 (config says 'retries 3'), and no redispatch (otherwise we would have
14874 seen "/+3"). Status code 503 was returned to the client. There were 115
14875 connections on this server, 202 connections on this proxy, and 205 on
14876 the global process. It is possible that the server refused the
14877 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +010014878
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010014879
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200148809. Statistics and monitoring
14881----------------------------
14882
14883It is possible to query HAProxy about its status. The most commonly used
14884mechanism is the HTTP statistics page. This page also exposes an alternative
14885CSV output format for monitoring tools. The same format is provided on the
14886Unix socket.
14887
14888
148899.1. CSV format
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010014890---------------
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010014891
Willy Tarreau7f062c42009-03-05 18:43:00 +010014892The statistics may be consulted either from the unix socket or from the HTTP
Willy Tarreaua3310dc2014-06-16 15:43:21 +020014893page. Both means provide a CSV format whose fields follow. The first line
14894begins with a sharp ('#') and has one word per comma-delimited field which
14895represents the title of the column. All other lines starting at the second one
14896use a classical CSV format using a comma as the delimiter, and the double quote
14897('"') as an optional text delimiter, but only if the enclosed text is ambiguous
14898(if it contains a quote or a comma). The double-quote character ('"') in the
14899text is doubled ('""'), which is the format that most tools recognize. Please
14900do not insert any column before these ones in order not to break tools which
14901use hard-coded column positions.
Willy Tarreau7f062c42009-03-05 18:43:00 +010014902
James Westbyebe62d62014-07-08 10:14:57 -040014903In brackets after each field name are the types which may have a value for
14904that field. The types are L (Listeners), F (Frontends), B (Backends), and
14905S (Servers).
14906
14907 0. pxname [LFBS]: proxy name
14908 1. svname [LFBS]: service name (FRONTEND for frontend, BACKEND for backend,
14909 any name for server/listener)
14910 2. qcur [..BS]: current queued requests. For the backend this reports the
14911 number queued without a server assigned.
14912 3. qmax [..BS]: max value of qcur
14913 4. scur [LFBS]: current sessions
14914 5. smax [LFBS]: max sessions
14915 6. slim [LFBS]: configured session limit
14916 7. stot [LFBS]: cumulative number of connections
14917 8. bin [LFBS]: bytes in
14918 9. bout [LFBS]: bytes out
14919 10. dreq [LFB.]: requests denied because of security concerns.
14920 - For tcp this is because of a matched tcp-request content rule.
14921 - For http this is because of a matched http-request or tarpit rule.
14922 11. dresp [LFBS]: responses denied because of security concerns.
14923 - For http this is because of a matched http-request rule, or
14924 "option checkcache".
14925 12. ereq [LF..]: request errors. Some of the possible causes are:
14926 - early termination from the client, before the request has been sent.
14927 - read error from the client
14928 - client timeout
14929 - client closed connection
14930 - various bad requests from the client.
14931 - request was tarpitted.
14932 13. econ [..BS]: number of requests that encountered an error trying to
14933 connect to a backend server. The backend stat is the sum of the stat
14934 for all servers of that backend, plus any connection errors not
14935 associated with a particular server (such as the backend having no
14936 active servers).
14937 14. eresp [..BS]: response errors. srv_abrt will be counted here also.
14938 Some other errors are:
14939 - write error on the client socket (won't be counted for the server stat)
14940 - failure applying filters to the response.
14941 15. wretr [..BS]: number of times a connection to a server was retried.
14942 16. wredis [..BS]: number of times a request was redispatched to another
14943 server. The server value counts the number of times that server was
14944 switched away from.
14945 17. status [LFBS]: status (UP/DOWN/NOLB/MAINT/MAINT(via)...)
Pavlos Parissis1f673c72015-05-02 20:30:44 +020014946 18. weight [..BS]: total weight (backend), server weight (server)
14947 19. act [..BS]: number of active servers (backend), server is active (server)
14948 20. bck [..BS]: number of backup servers (backend), server is backup (server)
James Westbyebe62d62014-07-08 10:14:57 -040014949 21. chkfail [...S]: number of failed checks. (Only counts checks failed when
14950 the server is up.)
14951 22. chkdown [..BS]: number of UP->DOWN transitions. The backend counter counts
14952 transitions to the whole backend being down, rather than the sum of the
14953 counters for each server.
14954 23. lastchg [..BS]: number of seconds since the last UP<->DOWN transition
14955 24. downtime [..BS]: total downtime (in seconds). The value for the backend
14956 is the downtime for the whole backend, not the sum of the server downtime.
14957 25. qlimit [...S]: configured maxqueue for the server, or nothing in the
14958 value is 0 (default, meaning no limit)
14959 26. pid [LFBS]: process id (0 for first instance, 1 for second, ...)
14960 27. iid [LFBS]: unique proxy id
14961 28. sid [L..S]: server id (unique inside a proxy)
14962 29. throttle [...S]: current throttle percentage for the server, when
14963 slowstart is active, or no value if not in slowstart.
14964 30. lbtot [..BS]: total number of times a server was selected, either for new
14965 sessions, or when re-dispatching. The server counter is the number
14966 of times that server was selected.
14967 31. tracked [...S]: id of proxy/server if tracking is enabled.
14968 32. type [LFBS]: (0=frontend, 1=backend, 2=server, 3=socket/listener)
14969 33. rate [.FBS]: number of sessions per second over last elapsed second
14970 34. rate_lim [.F..]: configured limit on new sessions per second
14971 35. rate_max [.FBS]: max number of new sessions per second
14972 36. check_status [...S]: status of last health check, one of:
Cyril Bontéf0c60612010-02-06 14:44:47 +010014973 UNK -> unknown
14974 INI -> initializing
14975 SOCKERR -> socket error
14976 L4OK -> check passed on layer 4, no upper layers testing enabled
Jason Harvey83104802015-04-16 11:13:21 -080014977 L4TOUT -> layer 1-4 timeout
Cyril Bontéf0c60612010-02-06 14:44:47 +010014978 L4CON -> layer 1-4 connection problem, for example
14979 "Connection refused" (tcp rst) or "No route to host" (icmp)
14980 L6OK -> check passed on layer 6
14981 L6TOUT -> layer 6 (SSL) timeout
14982 L6RSP -> layer 6 invalid response - protocol error
14983 L7OK -> check passed on layer 7
14984 L7OKC -> check conditionally passed on layer 7, for example 404 with
14985 disable-on-404
14986 L7TOUT -> layer 7 (HTTP/SMTP) timeout
14987 L7RSP -> layer 7 invalid response - protocol error
14988 L7STS -> layer 7 response error, for example HTTP 5xx
James Westbyebe62d62014-07-08 10:14:57 -040014989 37. check_code [...S]: layer5-7 code, if available
14990 38. check_duration [...S]: time in ms took to finish last health check
14991 39. hrsp_1xx [.FBS]: http responses with 1xx code
14992 40. hrsp_2xx [.FBS]: http responses with 2xx code
14993 41. hrsp_3xx [.FBS]: http responses with 3xx code
14994 42. hrsp_4xx [.FBS]: http responses with 4xx code
14995 43. hrsp_5xx [.FBS]: http responses with 5xx code
14996 44. hrsp_other [.FBS]: http responses with other codes (protocol error)
14997 45. hanafail [...S]: failed health checks details
14998 46. req_rate [.F..]: HTTP requests per second over last elapsed second
14999 47. req_rate_max [.F..]: max number of HTTP requests per second observed
15000 48. req_tot [.F..]: total number of HTTP requests received
15001 49. cli_abrt [..BS]: number of data transfers aborted by the client
15002 50. srv_abrt [..BS]: number of data transfers aborted by the server
15003 (inc. in eresp)
15004 51. comp_in [.FB.]: number of HTTP response bytes fed to the compressor
15005 52. comp_out [.FB.]: number of HTTP response bytes emitted by the compressor
15006 53. comp_byp [.FB.]: number of bytes that bypassed the HTTP compressor
15007 (CPU/BW limit)
15008 54. comp_rsp [.FB.]: number of HTTP responses that were compressed
15009 55. lastsess [..BS]: number of seconds since last session assigned to
15010 server/backend
15011 56. last_chk [...S]: last health check contents or textual error
15012 57. last_agt [...S]: last agent check contents or textual error
15013 58. qtime [..BS]: the average queue time in ms over the 1024 last requests
15014 59. ctime [..BS]: the average connect time in ms over the 1024 last requests
15015 60. rtime [..BS]: the average response time in ms over the 1024 last requests
15016 (0 for TCP)
15017 61. ttime [..BS]: the average total session time in ms over the 1024 last
15018 requests
Willy Tarreau844e3c52008-01-11 16:28:18 +010015019
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010015020
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200150219.2. Unix Socket commands
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010015022-------------------------
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010015023
Willy Tarreau468f4932013-08-01 16:50:16 +020015024The stats socket is not enabled by default. In order to enable it, it is
15025necessary to add one line in the global section of the haproxy configuration.
15026A second line is recommended to set a larger timeout, always appreciated when
15027issuing commands by hand :
15028
15029 global
15030 stats socket /var/run/haproxy.sock mode 600 level admin
15031 stats timeout 2m
15032
15033It is also possible to add multiple instances of the stats socket by repeating
15034the line, and make them listen to a TCP port instead of a UNIX socket. This is
15035never done by default because this is dangerous, but can be handy in some
15036situations :
15037
15038 global
15039 stats socket /var/run/haproxy.sock mode 600 level admin
15040 stats socket ipv4@192.168.0.1:9999 level admin
15041 stats timeout 2m
15042
15043To access the socket, an external utility such as "socat" is required. Socat is a
15044swiss-army knife to connect anything to anything. We use it to connect terminals
15045to the socket, or a couple of stdin/stdout pipes to it for scripts. The two main
15046syntaxes we'll use are the following :
15047
15048 # socat /var/run/haproxy.sock stdio
15049 # socat /var/run/haproxy.sock readline
15050
15051The first one is used with scripts. It is possible to send the output of a
15052script to haproxy, and pass haproxy's output to another script. That's useful
15053for retrieving counters or attack traces for example.
15054
15055The second one is only useful for issuing commands by hand. It has the benefit
15056that the terminal is handled by the readline library which supports line
15057editing and history, which is very convenient when issuing repeated commands
15058(eg: watch a counter).
15059
15060The socket supports two operation modes :
15061 - interactive
15062 - non-interactive
15063
15064The non-interactive mode is the default when socat connects to the socket. In
15065this mode, a single line may be sent. It is processed as a whole, responses are
15066sent back, and the connection closes after the end of the response. This is the
15067mode that scripts and monitoring tools use. It is possible to send multiple
15068commands in this mode, they need to be delimited by a semi-colon (';'). For
15069example :
15070
15071 # echo "show info;show stat;show table" | socat /var/run/haproxy stdio
15072
15073The interactive mode displays a prompt ('>') and waits for commands to be
15074entered on the line, then processes them, and displays the prompt again to wait
15075for a new command. This mode is entered via the "prompt" command which must be
15076sent on the first line in non-interactive mode. The mode is a flip switch, if
15077"prompt" is sent in interactive mode, it is disabled and the connection closes
15078after processing the last command of the same line.
15079
15080For this reason, when debugging by hand, it's quite common to start with the
15081"prompt" command :
15082
15083 # socat /var/run/haproxy readline
15084 prompt
15085 > show info
15086 ...
15087 >
15088
15089Since multiple commands may be issued at once, haproxy uses the empty line as a
15090delimiter to mark an end of output for each command, and takes care of ensuring
15091that no command can emit an empty line on output. A script can thus easily
15092parse the output even when multiple commands were pipelined on a single line.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010015093
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020015094It is important to understand that when multiple haproxy processes are started
15095on the same sockets, any process may pick up the request and will output its
15096own stats.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010015097
Willy Tarreau468f4932013-08-01 16:50:16 +020015098The list of commands currently supported on the stats socket is provided below.
15099If an unknown command is sent, haproxy displays the usage message which reminds
15100all supported commands. Some commands support a more complex syntax, generally
15101it will explain what part of the command is invalid when this happens.
15102
Thierry FOURNIERd32079e2014-01-29 20:02:04 +010015103add acl <acl> <pattern>
Thierry FOURNIER65ce6132014-03-20 11:42:45 +010015104 Add an entry into the acl <acl>. <acl> is the #<id> or the <file> returned by
15105 "show acl". This command does not verify if the entry already exists. This
15106 command cannot be used if the reference <acl> is a file also used with a map.
15107 In this case, you must use the command "add map" in place of "add acl".
Thierry FOURNIERd32079e2014-01-29 20:02:04 +010015108
Thierry FOURNIERc0e0d7b2013-12-11 16:55:52 +010015109add map <map> <key> <value>
15110 Add an entry into the map <map> to associate the value <value> to the key
15111 <key>. This command does not verify if the entry already exists. It is
Thierry FOURNIERd32079e2014-01-29 20:02:04 +010015112 mainly used to fill a map after a clear operation. Note that if the reference
15113 <map> is a file and is shared with a map, this map will contain also a new
15114 pattern entry.
Thierry FOURNIERc0e0d7b2013-12-11 16:55:52 +010015115
Willy Tarreaud63335a2010-02-26 12:56:52 +010015116clear counters
15117 Clear the max values of the statistics counters in each proxy (frontend &
15118 backend) and in each server. The cumulated counters are not affected. This
15119 can be used to get clean counters after an incident, without having to
15120 restart nor to clear traffic counters. This command is restricted and can
15121 only be issued on sockets configured for levels "operator" or "admin".
15122
15123clear counters all
15124 Clear all statistics counters in each proxy (frontend & backend) and in each
15125 server. This has the same effect as restarting. This command is restricted
15126 and can only be issued on sockets configured for level "admin".
15127
Thierry FOURNIERd32079e2014-01-29 20:02:04 +010015128clear acl <acl>
Thierry FOURNIER65ce6132014-03-20 11:42:45 +010015129 Remove all entries from the acl <acl>. <acl> is the #<id> or the <file>
15130 returned by "show acl". Note that if the reference <acl> is a file and is
15131 shared with a map, this map will be also cleared.
Thierry FOURNIERd32079e2014-01-29 20:02:04 +010015132
Thierry FOURNIERc0e0d7b2013-12-11 16:55:52 +010015133clear map <map>
Thierry FOURNIER65ce6132014-03-20 11:42:45 +010015134 Remove all entries from the map <map>. <map> is the #<id> or the <file>
15135 returned by "show map". Note that if the reference <map> is a file and is
15136 shared with a acl, this acl will be also cleared.
Thierry FOURNIERc0e0d7b2013-12-11 16:55:52 +010015137
Simon Hormanc88b8872011-06-15 15:18:49 +090015138clear table <table> [ data.<type> <operator> <value> ] | [ key <key> ]
15139 Remove entries from the stick-table <table>.
15140
15141 This is typically used to unblock some users complaining they have been
15142 abusively denied access to a service, but this can also be used to clear some
15143 stickiness entries matching a server that is going to be replaced (see "show
15144 table" below for details). Note that sometimes, removal of an entry will be
15145 refused because it is currently tracked by a session. Retrying a few seconds
15146 later after the session ends is usual enough.
15147
15148 In the case where no options arguments are given all entries will be removed.
15149
15150 When the "data." form is used entries matching a filter applied using the
15151 stored data (see "stick-table" in section 4.2) are removed. A stored data
15152 type must be specified in <type>, and this data type must be stored in the
15153 table otherwise an error is reported. The data is compared according to
15154 <operator> with the 64-bit integer <value>. Operators are the same as with
15155 the ACLs :
15156
15157 - eq : match entries whose data is equal to this value
15158 - ne : match entries whose data is not equal to this value
15159 - le : match entries whose data is less than or equal to this value
15160 - ge : match entries whose data is greater than or equal to this value
15161 - lt : match entries whose data is less than this value
15162 - gt : match entries whose data is greater than this value
15163
15164 When the key form is used the entry <key> is removed. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +090015165 same type as the table, which currently is limited to IPv4, IPv6, integer and
15166 string.
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015167
15168 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020015169 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +020015170 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020015171 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
15172 bytes_out_rate(60000)=187
15173 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
15174 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015175
15176 $ echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1
15177
15178 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +020015179 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau62a36c42010-08-17 15:53:10 +020015180 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
15181 bytes_out_rate(60000)=191
Simon Hormanc88b8872011-06-15 15:18:49 +090015182 $ echo "clear table http_proxy data.gpc0 eq 1" | socat stdio /tmp/sock1
15183 $ echo "show table http_proxy" | socat stdio /tmp/sock1
15184 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015185
Thierry FOURNIERd32079e2014-01-29 20:02:04 +010015186del acl <acl> [<key>|#<ref>]
15187 Delete all the acl entries from the acl <acl> corresponding to the key <key>.
Thierry FOURNIER65ce6132014-03-20 11:42:45 +010015188 <acl> is the #<id> or the <file> returned by "show acl". If the <ref> is used,
15189 this command delete only the listed reference. The reference can be found with
15190 listing the content of the acl. Note that if the reference <acl> is a file and
15191 is shared with a map, the entry will be also deleted in the map.
Thierry FOURNIERd32079e2014-01-29 20:02:04 +010015192
15193del map <map> [<key>|#<ref>]
Thierry FOURNIER0b90f312014-01-29 20:40:18 +010015194 Delete all the map entries from the map <map> corresponding to the key <key>.
Thierry FOURNIER65ce6132014-03-20 11:42:45 +010015195 <map> is the #<id> or the <file> returned by "show map". If the <ref> is used,
15196 this command delete only the listed reference. The reference can be found with
15197 listing the content of the map. Note that if the reference <map> is a file and
15198 is shared with a acl, the entry will be also deleted in the map.
Thierry FOURNIER0b90f312014-01-29 20:40:18 +010015199
15200disable agent <backend>/<server>
Simon Horman671b6f02013-11-25 10:46:39 +090015201 Mark the auxiliary agent check as temporarily stopped.
15202
15203 In the case where an agent check is being run as a auxiliary check, due
15204 to the agent-check parameter of a server directive, new checks are only
15205 initialised when the agent is in the enabled. Thus, disable agent will
15206 prevent any new agent checks from begin initiated until the agent
15207 re-enabled using enable agent.
15208
15209 When an agent is disabled the processing of an auxiliary agent check that
15210 was initiated while the agent was set as enabled is as follows: All
15211 results that would alter the weight, specifically "drain" or a weight
15212 returned by the agent, are ignored. The processing of agent check is
15213 otherwise unchanged.
15214
15215 The motivation for this feature is to allow the weight changing effects
15216 of the agent checks to be paused to allow the weight of a server to be
15217 configured using set weight without being overridden by the agent.
15218
15219 This command is restricted and can only be issued on sockets configured for
15220 level "admin".
15221
Willy Tarreau532a4502011-09-07 22:37:44 +020015222disable frontend <frontend>
15223 Mark the frontend as temporarily stopped. This corresponds to the mode which
15224 is used during a soft restart : the frontend releases the port but can be
15225 enabled again if needed. This should be used with care as some non-Linux OSes
15226 are unable to enable it back. This is intended to be used in environments
15227 where stopping a proxy is not even imaginable but a misconfigured proxy must
15228 be fixed. That way it's possible to release the port and bind it into another
15229 process to restore operations. The frontend will appear with status "STOP"
15230 on the stats page.
15231
15232 The frontend may be specified either by its name or by its numeric ID,
15233 prefixed with a sharp ('#').
15234
15235 This command is restricted and can only be issued on sockets configured for
15236 level "admin".
15237
Willy Tarreau9b5aecd2014-05-23 11:53:10 +020015238disable health <backend>/<server>
15239 Mark the primary health check as temporarily stopped. This will disable
15240 sending of health checks, and the last health check result will be ignored.
15241 The server will be in unchecked state and considered UP unless an auxiliary
15242 agent check forces it down.
15243
15244 This command is restricted and can only be issued on sockets configured for
15245 level "admin".
15246
Willy Tarreaud63335a2010-02-26 12:56:52 +010015247disable server <backend>/<server>
15248 Mark the server DOWN for maintenance. In this mode, no more checks will be
15249 performed on the server until it leaves maintenance.
15250 If the server is tracked by other servers, those servers will be set to DOWN
15251 during the maintenance.
15252
15253 In the statistics page, a server DOWN for maintenance will appear with a
15254 "MAINT" status, its tracking servers with the "MAINT(via)" one.
15255
15256 Both the backend and the server may be specified either by their name or by
Willy Tarreauf5f31922011-08-02 11:32:07 +020015257 their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010015258
15259 This command is restricted and can only be issued on sockets configured for
15260 level "admin".
15261
Simon Horman671b6f02013-11-25 10:46:39 +090015262enable agent <backend>/<server>
15263 Resume auxiliary agent check that was temporarily stopped.
15264
15265 See "disable agent" for details of the effect of temporarily starting
15266 and stopping an auxiliary agent.
15267
15268 This command is restricted and can only be issued on sockets configured for
15269 level "admin".
15270
Willy Tarreau532a4502011-09-07 22:37:44 +020015271enable frontend <frontend>
15272 Resume a frontend which was temporarily stopped. It is possible that some of
15273 the listening ports won't be able to bind anymore (eg: if another process
15274 took them since the 'disable frontend' operation). If this happens, an error
15275 is displayed. Some operating systems might not be able to resume a frontend
15276 which was disabled.
15277
15278 The frontend may be specified either by its name or by its numeric ID,
15279 prefixed with a sharp ('#').
15280
15281 This command is restricted and can only be issued on sockets configured for
15282 level "admin".
15283
Willy Tarreau9b5aecd2014-05-23 11:53:10 +020015284enable health <backend>/<server>
15285 Resume a primary health check that was temporarily stopped. This will enable
15286 sending of health checks again. Please see "disable health" for details.
15287
15288 This command is restricted and can only be issued on sockets configured for
15289 level "admin".
15290
Willy Tarreaud63335a2010-02-26 12:56:52 +010015291enable server <backend>/<server>
15292 If the server was previously marked as DOWN for maintenance, this marks the
15293 server UP and checks are re-enabled.
15294
15295 Both the backend and the server may be specified either by their name or by
Willy Tarreauf5f31922011-08-02 11:32:07 +020015296 their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010015297
15298 This command is restricted and can only be issued on sockets configured for
15299 level "admin".
15300
Thierry FOURNIER5b16df72014-02-26 18:07:38 +010015301get map <map> <value>
Thierry FOURNIER65ce6132014-03-20 11:42:45 +010015302get acl <acl> <value>
15303 Lookup the value <value> in the map <map> or in the ACL <acl>. <map> or <acl>
15304 are the #<id> or the <file> returned by "show map" or "show acl". This command
15305 returns all the matching patterns associated with this map. This is useful for
15306 debugging maps and ACLs. The output format is composed by one line par
15307 matching type. Each line is composed by space-delimited series of words.
Thierry FOURNIER5b16df72014-02-26 18:07:38 +010015308
15309 The first two words are:
15310
15311 <match method>: The match method applied. It can be "found", "bool",
15312 "int", "ip", "bin", "len", "str", "beg", "sub", "dir",
15313 "dom", "end" or "reg".
15314
15315 <match result>: The result. Can be "match" or "no-match".
15316
15317 The following words are returned only if the pattern matches an entry.
15318
15319 <index type>: "tree" or "list". The internal lookup algorithm.
15320
15321 <case>: "case-insensitive" or "case-sensitive". The
15322 interpretation of the case.
15323
15324 <entry matched>: match="<entry>". Return the matched pattern. It is
15325 useful with regular expressions.
15326
15327 The two last word are used to show the returned value and its type. With the
15328 "acl" case, the pattern doesn't exist.
15329
15330 return=nothing: No return because there are no "map".
15331 return="<value>": The value returned in the string format.
15332 return=cannot-display: The value cannot be converted as string.
15333
15334 type="<type>": The type of the returned sample.
15335
Willy Tarreaud63335a2010-02-26 12:56:52 +010015336get weight <backend>/<server>
15337 Report the current weight and the initial weight of server <server> in
15338 backend <backend> or an error if either doesn't exist. The initial weight is
15339 the one that appears in the configuration file. Both are normally equal
15340 unless the current weight has been changed. Both the backend and the server
15341 may be specified either by their name or by their numeric ID, prefixed with a
Willy Tarreauf5f31922011-08-02 11:32:07 +020015342 sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010015343
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020015344help
15345 Print the list of known keywords and their basic usage. The same help screen
15346 is also displayed for unknown commands.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010015347
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020015348prompt
15349 Toggle the prompt at the beginning of the line and enter or leave interactive
15350 mode. In interactive mode, the connection is not closed after a command
15351 completes. Instead, the prompt will appear again, indicating the user that
15352 the interpreter is waiting for a new command. The prompt consists in a right
15353 angle bracket followed by a space "> ". This mode is particularly convenient
15354 when one wants to periodically check information such as stats or errors.
15355 It is also a good idea to enter interactive mode before issuing a "help"
15356 command.
15357
15358quit
15359 Close the connection when in interactive mode.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010015360
Thierry FOURNIERd32079e2014-01-29 20:02:04 +010015361set map <map> [<key>|#<ref>] <value>
Thierry FOURNIER65ce6132014-03-20 11:42:45 +010015362 Modify the value corresponding to each key <key> in a map <map>. <map> is the
15363 #<id> or <file> returned by "show map". If the <ref> is used in place of
15364 <key>, only the entry pointed by <ref> is changed. The new value is <value>.
Thierry FOURNIERc0e0d7b2013-12-11 16:55:52 +010015365
Willy Tarreau2a0f4d22011-08-02 11:49:05 +020015366set maxconn frontend <frontend> <value>
Willy Tarreau3c7a79d2012-09-26 21:07:15 +020015367 Dynamically change the specified frontend's maxconn setting. Any positive
15368 value is allowed including zero, but setting values larger than the global
15369 maxconn does not make much sense. If the limit is increased and connections
15370 were pending, they will immediately be accepted. If it is lowered to a value
15371 below the current number of connections, new connections acceptation will be
Willy Tarreau2a0f4d22011-08-02 11:49:05 +020015372 delayed until the threshold is reached. The frontend might be specified by
15373 either its name or its numeric ID prefixed with a sharp ('#').
15374
Willy Tarreau91886b62011-09-07 14:38:31 +020015375set maxconn global <maxconn>
15376 Dynamically change the global maxconn setting within the range defined by the
15377 initial global maxconn setting. If it is increased and connections were
15378 pending, they will immediately be accepted. If it is lowered to a value below
15379 the current number of connections, new connections acceptation will be
15380 delayed until the threshold is reached. A value of zero restores the initial
15381 setting.
15382
Willy Tarreauf5b22872011-09-07 16:13:44 +020015383set rate-limit connections global <value>
15384 Change the process-wide connection rate limit, which is set by the global
15385 'maxconnrate' setting. A value of zero disables the limitation. This limit
15386 applies to all frontends and the change has an immediate effect. The value
15387 is passed in number of connections per second.
15388
William Lallemandd85f9172012-11-09 17:05:39 +010015389set rate-limit http-compression global <value>
15390 Change the maximum input compression rate, which is set by the global
15391 'maxcomprate' setting. A value of zero disables the limitation. The value is
William Lallemand096f5542012-11-19 17:26:05 +010015392 passed in number of kilobytes per second. The value is available in the "show
15393 info" on the line "CompressBpsRateLim" in bytes.
William Lallemandd85f9172012-11-09 17:05:39 +010015394
Willy Tarreau93e7c002013-10-07 18:51:07 +020015395set rate-limit sessions global <value>
15396 Change the process-wide session rate limit, which is set by the global
15397 'maxsessrate' setting. A value of zero disables the limitation. This limit
15398 applies to all frontends and the change has an immediate effect. The value
15399 is passed in number of sessions per second.
15400
Willy Tarreaue43d5322013-10-07 20:01:52 +020015401set rate-limit ssl-sessions global <value>
15402 Change the process-wide SSL session rate limit, which is set by the global
15403 'maxsslrate' setting. A value of zero disables the limitation. This limit
15404 applies to all frontends and the change has an immediate effect. The value
15405 is passed in number of sessions per second sent to the SSL stack. It applies
15406 before the handshake in order to protect the stack against handshake abuses.
15407
Baptiste Assmann3d8f8312015-04-13 22:54:33 +020015408set server <backend>/<server> addr <ip4 or ip6 address>
15409 Replace the current IP address of a server by the one provided.
15410
Willy Tarreau2a4b70f2014-05-22 18:42:35 +020015411set server <backend>/<server> agent [ up | down ]
15412 Force a server's agent to a new state. This can be useful to immediately
15413 switch a server's state regardless of some slow agent checks for example.
15414 Note that the change is propagated to tracking servers if any.
15415
15416set server <backend>/<server> health [ up | stopping | down ]
15417 Force a server's health to a new state. This can be useful to immediately
15418 switch a server's state regardless of some slow health checks for example.
15419 Note that the change is propagated to tracking servers if any.
15420
15421set server <backend>/<server> state [ ready | drain | maint ]
15422 Force a server's administrative state to a new state. This can be useful to
15423 disable load balancing and/or any traffic to a server. Setting the state to
15424 "ready" puts the server in normal mode, and the command is the equivalent of
15425 the "enable server" command. Setting the state to "maint" disables any traffic
15426 to the server as well as any health checks. This is the equivalent of the
15427 "disable server" command. Setting the mode to "drain" only removes the server
15428 from load balancing but still allows it to be checked and to accept new
15429 persistent connections. Changes are propagated to tracking servers if any.
15430
15431set server <backend>/<server> weight <weight>[%]
15432 Change a server's weight to the value passed in argument. This is the exact
15433 equivalent of the "set weight" command below.
15434
Emeric Brun4147b2e2014-06-16 18:36:30 +020015435set ssl ocsp-response <response>
15436 This command is used to update an OCSP Response for a certificate (see "crt"
15437 on "bind" lines). Same controls are performed as during the initial loading of
15438 the response. The <response> must be passed as a base64 encoded string of the
15439 DER encoded response from the OCSP server.
15440
15441 Example:
15442 openssl ocsp -issuer issuer.pem -cert server.pem \
15443 -host ocsp.issuer.com:80 -respout resp.der
15444 echo "set ssl ocsp-response $(base64 -w 10000 resp.der)" | \
15445 socat stdio /var/run/haproxy.stat
15446
Nenad Merdanovicc6985f02015-05-09 08:46:02 +020015447set ssl tls-key <id> <tlskey>
15448 Set the next TLS key for the <id> listener to <tlskey>. This key becomes the
15449 ultimate key, while the penultimate one is used for encryption (others just
15450 decrypt). The oldest TLS key present is overwritten. <id> is either a numeric
15451 #<id> or <file> returned by "show tls-keys". <tlskey> is a base64 encoded 48
15452 bit TLS ticket key (ex. openssl rand -base64 48).
15453
Willy Tarreau47060b62013-08-01 21:11:42 +020015454set table <table> key <key> [data.<data_type> <value>]*
Willy Tarreau654694e2012-06-07 01:03:16 +020015455 Create or update a stick-table entry in the table. If the key is not present,
15456 an entry is inserted. See stick-table in section 4.2 to find all possible
15457 values for <data_type>. The most likely use consists in dynamically entering
15458 entries for source IP addresses, with a flag in gpc0 to dynamically block an
Willy Tarreau47060b62013-08-01 21:11:42 +020015459 IP address or affect its quality of service. It is possible to pass multiple
15460 data_types in a single call.
Willy Tarreau654694e2012-06-07 01:03:16 +020015461
Willy Tarreaud63335a2010-02-26 12:56:52 +010015462set timeout cli <delay>
15463 Change the CLI interface timeout for current connection. This can be useful
15464 during long debugging sessions where the user needs to constantly inspect
15465 some indicators without being disconnected. The delay is passed in seconds.
15466
15467set weight <backend>/<server> <weight>[%]
15468 Change a server's weight to the value passed in argument. If the value ends
15469 with the '%' sign, then the new weight will be relative to the initially
Simon Horman58b5d292013-02-12 10:45:52 +090015470 configured weight. Absolute weights are permitted between 0 and 256.
15471 Relative weights must be positive with the resulting absolute weight is
15472 capped at 256. Servers which are part of a farm running a static
15473 load-balancing algorithm have stricter limitations because the weight
15474 cannot change once set. Thus for these servers, the only accepted values
15475 are 0 and 100% (or 0 and the initial weight). Changes take effect
15476 immediately, though certain LB algorithms require a certain amount of
15477 requests to consider changes. A typical usage of this command is to
15478 disable a server during an update by setting its weight to zero, then to
15479 enable it again after the update by setting it back to 100%. This command
15480 is restricted and can only be issued on sockets configured for level
15481 "admin". Both the backend and the server may be specified either by their
15482 name or by their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010015483
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010015484show errors [<iid>]
15485 Dump last known request and response errors collected by frontends and
15486 backends. If <iid> is specified, the limit the dump to errors concerning
Willy Tarreau6162db22009-10-10 17:13:00 +020015487 either frontend or backend whose ID is <iid>. This command is restricted
15488 and can only be issued on sockets configured for levels "operator" or
15489 "admin".
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010015490
15491 The errors which may be collected are the last request and response errors
15492 caused by protocol violations, often due to invalid characters in header
15493 names. The report precisely indicates what exact character violated the
15494 protocol. Other important information such as the exact date the error was
15495 detected, frontend and backend names, the server name (when known), the
15496 internal session ID and the source address which has initiated the session
15497 are reported too.
15498
15499 All characters are returned, and non-printable characters are encoded. The
15500 most common ones (\t = 9, \n = 10, \r = 13 and \e = 27) are encoded as one
15501 letter following a backslash. The backslash itself is encoded as '\\' to
15502 avoid confusion. Other non-printable characters are encoded '\xNN' where
15503 NN is the two-digits hexadecimal representation of the character's ASCII
15504 code.
15505
15506 Lines are prefixed with the position of their first character, starting at 0
15507 for the beginning of the buffer. At most one input line is printed per line,
15508 and large lines will be broken into multiple consecutive output lines so that
15509 the output never goes beyond 79 characters wide. It is easy to detect if a
15510 line was broken, because it will not end with '\n' and the next line's offset
15511 will be followed by a '+' sign, indicating it is a continuation of previous
15512 line.
15513
15514 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020015515 $ echo "show errors" | socat stdio /tmp/sock1
15516 >>> [04/Mar/2009:15:46:56.081] backend http-in (#2) : invalid response
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010015517 src 127.0.0.1, session #54, frontend fe-eth0 (#1), server s2 (#1)
15518 response length 213 bytes, error at position 23:
15519
15520 00000 HTTP/1.0 200 OK\r\n
15521 00017 header/bizarre:blah\r\n
15522 00038 Location: blah\r\n
15523 00054 Long-line: this is a very long line which should b
15524 00104+ e broken into multiple lines on the output buffer,
15525 00154+ otherwise it would be too large to print in a ter
15526 00204+ minal\r\n
15527 00211 \r\n
15528
Willy Tarreauc57f0e22009-05-10 13:12:33 +020015529 In the example above, we see that the backend "http-in" which has internal
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010015530 ID 2 has blocked an invalid response from its server s2 which has internal
15531 ID 1. The request was on session 54 initiated by source 127.0.0.1 and
15532 received by frontend fe-eth0 whose ID is 1. The total response length was
15533 213 bytes when the error was detected, and the error was at byte 23. This
15534 is the slash ('/') in header name "header/bizarre", which is not a valid
15535 HTTP character for a header name.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010015536
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020015537show info
15538 Dump info about haproxy status on current process.
15539
Thierry FOURNIERc0e0d7b2013-12-11 16:55:52 +010015540show map [<map>]
15541 Dump info about map converters. Without argument, the list of all available
Thierry FOURNIER65ce6132014-03-20 11:42:45 +010015542 maps is returned. If a <map> is specified, its contents are dumped. <map> is
15543 the #<id> or <file>. The first column is a unique identifier. It can be used
15544 as reference for the operation "del map" and "set map". The second column is
15545 the pattern and the third column is the sample if available. The data returned
15546 are not directly a list of available maps, but are the list of all patterns
15547 composing any map. Many of these patterns can be shared with ACL.
Thierry FOURNIERd32079e2014-01-29 20:02:04 +010015548
15549show acl [<acl>]
15550 Dump info about acl converters. Without argument, the list of all available
Thierry FOURNIER65ce6132014-03-20 11:42:45 +010015551 acls is returned. If a <acl> is specified, its contents are dumped. <acl> if
15552 the #<id> or <file>. The dump format is the same than the map even for the
15553 sample value. The data returned are not a list of available ACL, but are the
15554 list of all patterns composing any ACL. Many of these patterns can be shared
15555 with maps.
Thierry FOURNIERc0e0d7b2013-12-11 16:55:52 +010015556
Willy Tarreau12833bb2014-01-28 16:49:56 +010015557show pools
15558 Dump the status of internal memory pools. This is useful to track memory
15559 usage when suspecting a memory leak for example. It does exactly the same
15560 as the SIGQUIT when running in foreground except that it does not flush
15561 the pools.
15562
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020015563show sess
15564 Dump all known sessions. Avoid doing this on slow connections as this can
Willy Tarreau6162db22009-10-10 17:13:00 +020015565 be huge. This command is restricted and can only be issued on sockets
15566 configured for levels "operator" or "admin".
15567
Willy Tarreau66dc20a2010-03-05 17:53:32 +010015568show sess <id>
15569 Display a lot of internal information about the specified session identifier.
15570 This identifier is the first field at the beginning of the lines in the dumps
15571 of "show sess" (it corresponds to the session pointer). Those information are
15572 useless to most users but may be used by haproxy developers to troubleshoot a
15573 complex bug. The output format is intentionally not documented so that it can
Olivierce31e6e2014-09-05 18:49:10 +020015574 freely evolve depending on demands. You may find a description of all fields
15575 returned in src/dumpstats.c
15576
15577 The special id "all" dumps the states of all sessions, which must be avoided
15578 as much as possible as it is highly CPU intensive and can take a lot of time.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020015579
15580show stat [<iid> <type> <sid>]
15581 Dump statistics in the CSV format. By passing <id>, <type> and <sid>, it is
15582 possible to dump only selected items :
15583 - <iid> is a proxy ID, -1 to dump everything
15584 - <type> selects the type of dumpable objects : 1 for frontends, 2 for
15585 backends, 4 for servers, -1 for everything. These values can be ORed,
15586 for example:
15587 1 + 2 = 3 -> frontend + backend.
15588 1 + 2 + 4 = 7 -> frontend + backend + server.
15589 - <sid> is a server ID, -1 to dump everything from the selected proxy.
15590
15591 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020015592 $ echo "show info;show stat" | socat stdio unix-connect:/tmp/sock1
15593 >>> Name: HAProxy
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020015594 Version: 1.4-dev2-49
15595 Release_date: 2009/09/23
15596 Nbproc: 1
15597 Process_num: 1
15598 (...)
15599
15600 # pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,dreq, (...)
15601 stats,FRONTEND,,,0,0,1000,0,0,0,0,0,0,,,,,OPEN,,,,,,,,,1,1,0, (...)
15602 stats,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,0,0,0,,0,250,(...)
15603 (...)
15604 www1,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,1,1,0,,0,250, (...)
15605
15606 $
15607
15608 Here, two commands have been issued at once. That way it's easy to find
15609 which process the stats apply to in multi-process mode. Notice the empty
15610 line after the information output which marks the end of the first block.
15611 A similar empty line appears at the end of the second block (stats) so that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010015612 the reader knows the output has not been truncated.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020015613
Baptiste Assmann3863f972015-05-17 00:33:24 +020015614show stat resolvers <resolvers section id>
15615 Dump statistics for the given resolvers section.
15616 For each name server, the following counters are reported:
15617 sent: number of DNS requests sent to this server
15618 valid: number of DNS valid responses received from this server
15619 update: number of DNS responses used to update the server's IP address
15620 cname: number of CNAME responses
15621 cname_error: CNAME errors encountered with this server
15622 any_err: number of empty response (IE: server does not support ANY type)
15623 nx: non existent domain response received from this server
15624 timeout: how many time this server did not answer in time
15625 refused: number of requests refused by this server
15626 other: any other DNS errors
15627 invalid: invalid DNS response (from a protocol point of view)
15628 too_big: too big response
15629 outdated: number of response arrived too late (after an other name server)
15630
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015631show table
15632 Dump general information on all known stick-tables. Their name is returned
15633 (the name of the proxy which holds them), their type (currently zero, always
15634 IP), their size in maximum possible number of entries, and the number of
15635 entries currently in use.
15636
15637 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020015638 $ echo "show table" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090015639 >>> # table: front_pub, type: ip, size:204800, used:171454
15640 >>> # table: back_rdp, type: ip, size:204800, used:0
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015641
Simon Horman17bce342011-06-15 15:18:47 +090015642show table <name> [ data.<type> <operator> <value> ] | [ key <key> ]
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015643 Dump contents of stick-table <name>. In this mode, a first line of generic
15644 information about the table is reported as with "show table", then all
15645 entries are dumped. Since this can be quite heavy, it is possible to specify
Simon Horman17bce342011-06-15 15:18:47 +090015646 a filter in order to specify what entries to display.
15647
15648 When the "data." form is used the filter applies to the stored data (see
15649 "stick-table" in section 4.2). A stored data type must be specified
15650 in <type>, and this data type must be stored in the table otherwise an
15651 error is reported. The data is compared according to <operator> with the
15652 64-bit integer <value>. Operators are the same as with the ACLs :
15653
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015654 - eq : match entries whose data is equal to this value
15655 - ne : match entries whose data is not equal to this value
15656 - le : match entries whose data is less than or equal to this value
15657 - ge : match entries whose data is greater than or equal to this value
15658 - lt : match entries whose data is less than this value
15659 - gt : match entries whose data is greater than this value
15660
Simon Hormanc88b8872011-06-15 15:18:49 +090015661
15662 When the key form is used the entry <key> is shown. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +090015663 same type as the table, which currently is limited to IPv4, IPv6, integer,
15664 and string.
Simon Horman17bce342011-06-15 15:18:47 +090015665
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015666 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020015667 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090015668 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020015669 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
15670 bytes_out_rate(60000)=187
15671 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
15672 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015673
Willy Tarreau62a36c42010-08-17 15:53:10 +020015674 $ echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090015675 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020015676 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
15677 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015678
Willy Tarreau62a36c42010-08-17 15:53:10 +020015679 $ echo "show table http_proxy data.conn_rate gt 5" | \
15680 socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090015681 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020015682 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
15683 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015684
Simon Horman17bce342011-06-15 15:18:47 +090015685 $ echo "show table http_proxy key 127.0.0.2" | \
15686 socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090015687 >>> # table: http_proxy, type: ip, size:204800, used:2
Simon Horman17bce342011-06-15 15:18:47 +090015688 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
15689 bytes_out_rate(60000)=191
15690
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015691 When the data criterion applies to a dynamic value dependent on time such as
15692 a bytes rate, the value is dynamically computed during the evaluation of the
15693 entry in order to decide whether it has to be dumped or not. This means that
15694 such a filter could match for some time then not match anymore because as
15695 time goes, the average event rate drops.
15696
15697 It is possible to use this to extract lists of IP addresses abusing the
15698 service, in order to monitor them or even blacklist them in a firewall.
15699 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020015700 $ echo "show table http_proxy data.gpc0 gt 0" \
15701 | socat stdio /tmp/sock1 \
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020015702 | fgrep 'key=' | cut -d' ' -f2 | cut -d= -f2 > abusers-ip.txt
15703 ( or | awk '/key/{ print a[split($2,a,"=")]; }' )
Krzysztof Piotr Oledzki719e7262009-10-04 15:02:46 +020015704
Nenad Merdanovicc6985f02015-05-09 08:46:02 +020015705show tls-keys
15706 Dump all loaded TLS ticket keys. The TLS ticket key reference ID and the
15707 file from which the keys have been loaded is shown. Both of those can be
15708 used to update the TLS keys using "set ssl tls-key".
15709
Willy Tarreau532a4502011-09-07 22:37:44 +020015710shutdown frontend <frontend>
15711 Completely delete the specified frontend. All the ports it was bound to will
15712 be released. It will not be possible to enable the frontend anymore after
15713 this operation. This is intended to be used in environments where stopping a
15714 proxy is not even imaginable but a misconfigured proxy must be fixed. That
15715 way it's possible to release the port and bind it into another process to
15716 restore operations. The frontend will not appear at all on the stats page
15717 once it is terminated.
15718
15719 The frontend may be specified either by its name or by its numeric ID,
15720 prefixed with a sharp ('#').
15721
15722 This command is restricted and can only be issued on sockets configured for
15723 level "admin".
15724
Willy Tarreaua295edc2011-09-07 23:21:03 +020015725shutdown session <id>
15726 Immediately terminate the session matching the specified session identifier.
15727 This identifier is the first field at the beginning of the lines in the dumps
15728 of "show sess" (it corresponds to the session pointer). This can be used to
15729 terminate a long-running session without waiting for a timeout or when an
15730 endless transfer is ongoing. Such terminated sessions are reported with a 'K'
15731 flag in the logs.
15732
Cyril Bontée63a1eb2014-07-12 18:22:42 +020015733shutdown sessions server <backend>/<server>
Willy Tarreau52b2d222011-09-07 23:48:48 +020015734 Immediately terminate all the sessions attached to the specified server. This
15735 can be used to terminate long-running sessions after a server is put into
15736 maintenance mode, for instance. Such terminated sessions are reported with a
15737 'K' flag in the logs.
15738
Willy Tarreau0ba27502007-12-24 16:55:16 +010015739/*
15740 * Local variables:
15741 * fill-column: 79
15742 * End:
15743 */