blob: 6b4b74d52d3dbb1cd57c1967bce696e25f2b11c0 [file] [log] [blame]
Willy Tarreau6a06a402007-07-15 20:15:28 +02001 ----------------------
2 HAProxy
3 Configuration Manual
4 ----------------------
Willy Tarreau21475e32010-05-23 08:46:08 +02005 version 1.5
Willy Tarreau6a06a402007-07-15 20:15:28 +02006 willy tarreau
Willy Tarreau16216822012-09-10 09:46:55 +02007 2012/09/10
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
422.2. Time format
Patrick Mezard35da19c2010-06-12 17:02:47 +0200432.3. Examples
Willy Tarreauc57f0e22009-05-10 13:12:33 +020044
453. Global parameters
463.1. Process management and security
473.2. Performance tuning
483.3. Debugging
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100493.4. Userlists
Cyril Bontédc4d9032012-04-08 21:57:39 +0200503.5. Peers
Willy Tarreauc57f0e22009-05-10 13:12:33 +020051
524. Proxies
534.1. Proxy keywords matrix
544.2. Alphabetically sorted keywords reference
55
Willy Tarreau086fbf52012-09-24 20:34:51 +0200565. Bind and Server options
575.1. Bind options
585.2. Server and default-server options
Willy Tarreauc57f0e22009-05-10 13:12:33 +020059
606. HTTP header manipulation
61
Cyril Bonté7d38afb2010-02-03 20:41:26 +0100627. Using ACLs and pattern extraction
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200637.1. Matching integers
647.2. Matching strings
657.3. Matching regular expressions (regexes)
Willy Tarreauceb4ac92012-04-28 00:41:46 +0200667.4. Matching IPv4 and IPv6 addresses
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200677.5. Available matching criteria
687.5.1. Matching at Layer 4 and below
697.5.2. Matching contents at Layer 4
707.5.3. Matching at Layer 7
717.6. Pre-defined ACLs
727.7. Using ACLs to form conditions
Cyril Bonté7d38afb2010-02-03 20:41:26 +0100737.8. Pattern extraction
Willy Tarreauc57f0e22009-05-10 13:12:33 +020074
758. Logging
768.1. Log levels
778.2. Log formats
788.2.1. Default log format
798.2.2. TCP log format
808.2.3. HTTP log format
William Lallemand48940402012-01-30 16:47:22 +0100818.2.4. Custom log format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200828.3. Advanced logging options
838.3.1. Disabling logging of external tests
848.3.2. Logging before waiting for the session to terminate
858.3.3. Raising log level upon errors
868.3.4. Disabling logging of successful connections
878.4. Timing events
888.5. Session state at disconnection
898.6. Non-printable characters
908.7. Capturing HTTP cookies
918.8. Capturing HTTP headers
928.9. Examples of logs
93
949. Statistics and monitoring
959.1. CSV format
969.2. Unix Socket commands
97
98
991. Quick reminder about HTTP
100----------------------------
101
102When haproxy is running in HTTP mode, both the request and the response are
103fully analyzed and indexed, thus it becomes possible to build matching criteria
104on almost anything found in the contents.
105
106However, it is important to understand how HTTP requests and responses are
107formed, and how HAProxy decomposes them. It will then become easier to write
108correct rules and to debug existing configurations.
109
110
1111.1. The HTTP transaction model
112-------------------------------
113
114The HTTP protocol is transaction-driven. This means that each request will lead
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100115to one and only one response. Traditionally, a TCP connection is established
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200116from the client to the server, a request is sent by the client on the
117connection, the server responds and the connection is closed. A new request
118will involve a new connection :
119
120 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
121
122In this mode, called the "HTTP close" mode, there are as many connection
123establishments as there are HTTP transactions. Since the connection is closed
124by the server after the response, the client does not need to know the content
125length.
126
127Due to the transactional nature of the protocol, it was possible to improve it
128to avoid closing a connection between two subsequent transactions. In this mode
129however, it is mandatory that the server indicates the content length for each
130response so that the client does not wait indefinitely. For this, a special
131header is used: "Content-length". This mode is called the "keep-alive" mode :
132
133 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
134
135Its advantages are a reduced latency between transactions, and less processing
136power required on the server side. It is generally better than the close mode,
137but not always because the clients often limit their concurrent connections to
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200138a smaller value.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200139
140A last improvement in the communications is the pipelining mode. It still uses
141keep-alive, but the client does not wait for the first response to send the
142second request. This is useful for fetching large number of images composing a
143page :
144
145 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
146
147This can obviously have a tremendous benefit on performance because the network
148latency is eliminated between subsequent requests. Many HTTP agents do not
149correctly support pipelining since there is no way to associate a response with
150the corresponding request in HTTP. For this reason, it is mandatory for the
Cyril Bonté78caf842010-03-10 22:41:43 +0100151server to reply in the exact same order as the requests were received.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200152
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200153By default HAProxy operates in a tunnel-like mode with regards to persistent
154connections: for each connection it processes the first request and forwards
155everything else (including additional requests) to selected server. Once
156established, the connection is persisted both on the client and server
157sides. Use "option http-server-close" to preserve client persistent connections
158while handling every incoming request individually, dispatching them one after
159another to servers, in HTTP close mode. Use "option httpclose" to switch both
160sides to HTTP close mode. "option forceclose" and "option
161http-pretend-keepalive" help working around servers misbehaving in HTTP close
162mode.
163
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200164
1651.2. HTTP request
166-----------------
167
168First, let's consider this HTTP request :
169
170 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100171 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200172 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
173 2 Host: www.mydomain.com
174 3 User-agent: my small browser
175 4 Accept: image/jpeg, image/gif
176 5 Accept: image/png
177
178
1791.2.1. The Request line
180-----------------------
181
182Line 1 is the "request line". It is always composed of 3 fields :
183
184 - a METHOD : GET
185 - a URI : /serv/login.php?lang=en&profile=2
186 - a version tag : HTTP/1.1
187
188All of them are delimited by what the standard calls LWS (linear white spaces),
189which are commonly spaces, but can also be tabs or line feeds/carriage returns
190followed by spaces/tabs. The method itself cannot contain any colon (':') and
191is limited to alphabetic letters. All those various combinations make it
192desirable that HAProxy performs the splitting itself rather than leaving it to
193the user to write a complex or inaccurate regular expression.
194
195The URI itself can have several forms :
196
197 - A "relative URI" :
198
199 /serv/login.php?lang=en&profile=2
200
201 It is a complete URL without the host part. This is generally what is
202 received by servers, reverse proxies and transparent proxies.
203
204 - An "absolute URI", also called a "URL" :
205
206 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
207
208 It is composed of a "scheme" (the protocol name followed by '://'), a host
209 name or address, optionally a colon (':') followed by a port number, then
210 a relative URI beginning at the first slash ('/') after the address part.
211 This is generally what proxies receive, but a server supporting HTTP/1.1
212 must accept this form too.
213
214 - a star ('*') : this form is only accepted in association with the OPTIONS
215 method and is not relayable. It is used to inquiry a next hop's
216 capabilities.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100217
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200218 - an address:port combination : 192.168.0.12:80
219 This is used with the CONNECT method, which is used to establish TCP
220 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
221 other protocols too.
222
223In a relative URI, two sub-parts are identified. The part before the question
224mark is called the "path". It is typically the relative path to static objects
225on the server. The part after the question mark is called the "query string".
226It is mostly used with GET requests sent to dynamic scripts and is very
227specific to the language, framework or application in use.
228
229
2301.2.2. The request headers
231--------------------------
232
233The headers start at the second line. They are composed of a name at the
234beginning of the line, immediately followed by a colon (':'). Traditionally,
235an LWS is added after the colon but that's not required. Then come the values.
236Multiple identical headers may be folded into one single line, delimiting the
237values with commas, provided that their order is respected. This is commonly
238encountered in the "Cookie:" field. A header may span over multiple lines if
239the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
240define a total of 3 values for the "Accept:" header.
241
242Contrary to a common mis-conception, header names are not case-sensitive, and
243their values are not either if they refer to other header names (such as the
244"Connection:" header).
245
246The end of the headers is indicated by the first empty line. People often say
247that it's a double line feed, which is not exact, even if a double line feed
248is one valid form of empty line.
249
250Fortunately, HAProxy takes care of all these complex combinations when indexing
251headers, checking values and counting them, so there is no reason to worry
252about the way they could be written, but it is important not to accuse an
253application of being buggy if it does unusual, valid things.
254
255Important note:
256 As suggested by RFC2616, HAProxy normalizes headers by replacing line breaks
257 in the middle of headers by LWS in order to join multi-line headers. This
258 is necessary for proper analysis and helps less capable HTTP parsers to work
259 correctly and not to be fooled by such complex constructs.
260
261
2621.3. HTTP response
263------------------
264
265An HTTP response looks very much like an HTTP request. Both are called HTTP
266messages. Let's consider this HTTP response :
267
268 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100269 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200270 1 HTTP/1.1 200 OK
271 2 Content-length: 350
272 3 Content-Type: text/html
273
Willy Tarreau816b9792009-09-15 21:25:21 +0200274As a special case, HTTP supports so called "Informational responses" as status
275codes 1xx. These messages are special in that they don't convey any part of the
276response, they're just used as sort of a signaling message to ask a client to
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100277continue to post its request for instance. In the case of a status 100 response
278the requested information will be carried by the next non-100 response message
279following the informational one. This implies that multiple responses may be
280sent to a single request, and that this only works when keep-alive is enabled
281(1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to
282correctly forward and skip them, and only process the next non-100 response. As
283such, these messages are neither logged nor transformed, unless explicitly
284state otherwise. Status 101 messages indicate that the protocol is changing
285over the same connection and that haproxy must switch to tunnel mode, just as
286if a CONNECT had occurred. Then the Upgrade header would contain additional
287information about the type of protocol the connection is switching to.
Willy Tarreau816b9792009-09-15 21:25:21 +0200288
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200289
2901.3.1. The Response line
291------------------------
292
293Line 1 is the "response line". It is always composed of 3 fields :
294
295 - a version tag : HTTP/1.1
296 - a status code : 200
297 - a reason : OK
298
299The status code is always 3-digit. The first digit indicates a general status :
Willy Tarreau816b9792009-09-15 21:25:21 +0200300 - 1xx = informational message to be skipped (eg: 100, 101)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200301 - 2xx = OK, content is following (eg: 200, 206)
302 - 3xx = OK, no content following (eg: 302, 304)
303 - 4xx = error caused by the client (eg: 401, 403, 404)
304 - 5xx = error caused by the server (eg: 500, 502, 503)
305
306Please refer to RFC2616 for the detailed meaning of all such codes. The
Willy Tarreaud72758d2010-01-12 10:42:19 +0100307"reason" field is just a hint, but is not parsed by clients. Anything can be
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200308found there, but it's a common practice to respect the well-established
309messages. It can be composed of one or multiple words, such as "OK", "Found",
310or "Authentication Required".
311
312Haproxy may emit the following status codes by itself :
313
314 Code When / reason
315 200 access to stats page, and when replying to monitoring requests
316 301 when performing a redirection, depending on the configured code
317 302 when performing a redirection, depending on the configured code
318 303 when performing a redirection, depending on the configured code
319 400 for an invalid or too large request
320 401 when an authentication is required to perform the action (when
321 accessing the stats page)
322 403 when a request is forbidden by a "block" ACL or "reqdeny" filter
323 408 when the request timeout strikes before the request is complete
324 500 when haproxy encounters an unrecoverable internal error, such as a
325 memory allocation failure, which should never happen
326 502 when the server returns an empty, invalid or incomplete response, or
327 when an "rspdeny" filter blocks the response.
328 503 when no server was available to handle the request, or in response to
329 monitoring requests which match the "monitor fail" condition
330 504 when the response timeout strikes before the server responds
331
332The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3334.2).
334
335
3361.3.2. The response headers
337---------------------------
338
339Response headers work exactly like request headers, and as such, HAProxy uses
340the same parsing function for both. Please refer to paragraph 1.2.2 for more
341details.
342
343
3442. Configuring HAProxy
345----------------------
346
3472.1. Configuration file format
348------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200349
350HAProxy's configuration process involves 3 major sources of parameters :
351
352 - the arguments from the command-line, which always take precedence
353 - the "global" section, which sets process-wide parameters
354 - the proxies sections which can take form of "defaults", "listen",
355 "frontend" and "backend".
356
Willy Tarreau0ba27502007-12-24 16:55:16 +0100357The configuration file syntax consists in lines beginning with a keyword
358referenced in this manual, optionally followed by one or several parameters
359delimited by spaces. If spaces have to be entered in strings, then they must be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100360preceded by a backslash ('\') to be escaped. Backslashes also have to be
Willy Tarreau0ba27502007-12-24 16:55:16 +0100361escaped by doubling them.
362
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200363
3642.2. Time format
365----------------
366
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100367Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100368values are generally expressed in milliseconds (unless explicitly stated
369otherwise) but may be expressed in any other unit by suffixing the unit to the
370numeric value. It is important to consider this because it will not be repeated
371for every keyword. Supported units are :
372
373 - us : microseconds. 1 microsecond = 1/1000000 second
374 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
375 - s : seconds. 1s = 1000ms
376 - m : minutes. 1m = 60s = 60000ms
377 - h : hours. 1h = 60m = 3600s = 3600000ms
378 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
379
380
Patrick Mezard35da19c2010-06-12 17:02:47 +02003812.3. Examples
382-------------
383
384 # Simple configuration for an HTTP proxy listening on port 80 on all
385 # interfaces and forwarding requests to a single backend "servers" with a
386 # single server "server1" listening on 127.0.0.1:8000
387 global
388 daemon
389 maxconn 256
390
391 defaults
392 mode http
393 timeout connect 5000ms
394 timeout client 50000ms
395 timeout server 50000ms
396
397 frontend http-in
398 bind *:80
399 default_backend servers
400
401 backend servers
402 server server1 127.0.0.1:8000 maxconn 32
403
404
405 # The same configuration defined with a single listen block. Shorter but
406 # less expressive, especially in HTTP mode.
407 global
408 daemon
409 maxconn 256
410
411 defaults
412 mode http
413 timeout connect 5000ms
414 timeout client 50000ms
415 timeout server 50000ms
416
417 listen http-in
418 bind *:80
419 server server1 127.0.0.1:8000 maxconn 32
420
421
422Assuming haproxy is in $PATH, test these configurations in a shell with:
423
Willy Tarreauccb289d2010-12-11 20:19:38 +0100424 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200425
426
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004273. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200428--------------------
429
430Parameters in the "global" section are process-wide and often OS-specific. They
431are generally set once for all and do not need being changed once correct. Some
432of them have command-line equivalents.
433
434The following keywords are supported in the "global" section :
435
436 * Process management and security
Emeric Brunc8e8d122012-10-02 18:42:10 +0200437 - ca-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200438 - chroot
Emeric Brunc8e8d122012-10-02 18:42:10 +0200439 - crt-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200440 - daemon
441 - gid
442 - group
443 - log
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100444 - log-send-hostname
Willy Tarreau6a06a402007-07-15 20:15:28 +0200445 - nbproc
446 - pidfile
447 - uid
448 - ulimit-n
449 - user
Willy Tarreaufbee7132007-10-18 13:53:22 +0200450 - stats
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200451 - node
452 - description
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100453 - unix-bind
Willy Tarreaud72758d2010-01-12 10:42:19 +0100454
Willy Tarreau6a06a402007-07-15 20:15:28 +0200455 * Performance tuning
456 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +0200457 - maxconnrate
William Lallemandd85f9172012-11-09 17:05:39 +0100458 - maxcomprate
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100459 - maxpipes
Willy Tarreau403edff2012-09-06 11:58:37 +0200460 - maxsslconn
Willy Tarreau6a06a402007-07-15 20:15:28 +0200461 - noepoll
462 - nokqueue
463 - nopoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100464 - nosplice
Willy Tarreaufe255b72007-10-14 23:09:26 +0200465 - spread-checks
Willy Tarreau27a674e2009-08-17 07:23:33 +0200466 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200467 - tune.chksize
William Lallemandf3747832012-11-09 12:33:10 +0100468 - tune.comp.maxlevel
Willy Tarreauac1932d2011-10-24 19:14:41 +0200469 - tune.http.maxhdr
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100470 - tune.maxaccept
471 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200472 - tune.maxrewrite
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200473 - tune.pipesize
Willy Tarreaue803de22010-01-21 17:43:04 +0100474 - tune.rcvbuf.client
475 - tune.rcvbuf.server
476 - tune.sndbuf.client
477 - tune.sndbuf.server
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100478 - tune.ssl.cachesize
William Lallemanda509e4c2012-11-07 16:54:34 +0100479 - tune.zlib.memlevel
480 - tune.zlib.windowsize
Willy Tarreaud72758d2010-01-12 10:42:19 +0100481
Willy Tarreau6a06a402007-07-15 20:15:28 +0200482 * Debugging
483 - debug
484 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200485
486
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004873.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200488------------------------------------
489
Emeric Brunc8e8d122012-10-02 18:42:10 +0200490ca-base <dir>
491 Assigns a default directory to fetch SSL CA certificates and CRLs from when a
Emeric Brunfd33a262012-10-11 16:28:27 +0200492 relative path is used with "ca-file" or "crl-file" directives. Absolute
493 locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200494
Willy Tarreau6a06a402007-07-15 20:15:28 +0200495chroot <jail dir>
496 Changes current directory to <jail dir> and performs a chroot() there before
497 dropping privileges. This increases the security level in case an unknown
498 vulnerability would be exploited, since it would make it very hard for the
499 attacker to exploit the system. This only works when the process is started
500 with superuser privileges. It is important to ensure that <jail_dir> is both
501 empty and unwritable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100502
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100503cpu-map <"all"|"odd"|"even"|process_num> <cpu-set>...
504 On Linux 2.6 and above, it is possible to bind a process to a specific CPU
505 set. This means that the process will never run on other CPUs. The "cpu-map"
506 directive specifies CPU sets for process sets. The first argument is the
507 process number to bind. This process must have a number between 1 and 32,
508 and any process IDs above nbproc are ignored. It is possible to specify all
509 processes at once using "all", only odd numbers using "odd" or even numbers
510 using "even", just like with the "bind-process" directive. The second and
511 forthcoming arguments are CPU sets. Each CPU set is either a unique number
512 between 0 and 31 or a range with two such numbers delimited by a dash ('-').
513 Multiple CPU numbers or ranges may be specified, and the processes will be
514 allowed to bind to all of them. Obviously, multiple "cpu-map" directives may
515 be specified. Each "cpu-map" directive will replace the previous ones when
516 they overlap.
517
Emeric Brunc8e8d122012-10-02 18:42:10 +0200518crt-base <dir>
519 Assigns a default directory to fetch SSL certificates from when a relative
520 path is used with "crtfile" directives. Absolute locations specified after
521 "crtfile" prevail and ignore "crt-base".
522
Willy Tarreau6a06a402007-07-15 20:15:28 +0200523daemon
524 Makes the process fork into background. This is the recommended mode of
525 operation. It is equivalent to the command line "-D" argument. It can be
526 disabled by the command line "-db" argument.
527
528gid <number>
529 Changes the process' group ID to <number>. It is recommended that the group
530 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
531 be started with a user belonging to this group, or with superuser privileges.
532 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100533
Willy Tarreau6a06a402007-07-15 20:15:28 +0200534group <group name>
535 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
536 See also "gid" and "user".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100537
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200538log <address> <facility> [max level [min level]]
Willy Tarreau6a06a402007-07-15 20:15:28 +0200539 Adds a global syslog server. Up to two global servers can be defined. They
540 will receive logs for startups and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100541 configured with "log global".
542
543 <address> can be one of:
544
Willy Tarreau2769aa02007-12-27 18:26:09 +0100545 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100546 no port is specified, 514 is used by default (the standard syslog
547 port).
548
David du Colombier24bb5f52011-03-17 10:40:23 +0100549 - An IPv6 address followed by a colon and optionally a UDP port. If
550 no port is specified, 514 is used by default (the standard syslog
551 port).
552
Robert Tsai81ae1952007-12-05 10:47:29 +0100553 - A filesystem path to a UNIX domain socket, keeping in mind
554 considerations for chroot (be sure the path is accessible inside
555 the chroot) and uid/gid (be sure the path is appropriately
556 writeable).
557
558 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200559
560 kern user mail daemon auth syslog lpr news
561 uucp cron auth2 ftp ntp audit alert cron2
562 local0 local1 local2 local3 local4 local5 local6 local7
563
564 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200565 all messages are sent. If a maximum level is specified, only messages with a
566 severity at least as important as this level will be sent. An optional minimum
567 level can be specified. If it is set, logs emitted with a more severe level
568 than this one will be capped to this level. This is used to avoid sending
569 "emerg" messages on all terminals on some default syslog configurations.
570 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200571
Cyril Bontédc4d9032012-04-08 21:57:39 +0200572 emerg alert crit err warning notice info debug
Willy Tarreau6a06a402007-07-15 20:15:28 +0200573
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100574log-send-hostname [<string>]
575 Sets the hostname field in the syslog header. If optional "string" parameter
576 is set the header is set to the string contents, otherwise uses the hostname
577 of the system. Generally used if one is not relaying logs through an
578 intermediate syslog server or for simply customizing the hostname printed in
579 the logs.
580
Kevinm48936af2010-12-22 16:08:21 +0000581log-tag <string>
582 Sets the tag field in the syslog header to this string. It defaults to the
583 program name as launched from the command line, which usually is "haproxy".
584 Sometimes it can be useful to differentiate between multiple processes
585 running on the same host.
586
Willy Tarreau6a06a402007-07-15 20:15:28 +0200587nbproc <number>
588 Creates <number> processes when going daemon. This requires the "daemon"
589 mode. By default, only one process is created, which is the recommended mode
590 of operation. For systems limited to small sets of file descriptors per
591 process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES
592 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon".
593
594pidfile <pidfile>
595 Writes pids of all daemons into file <pidfile>. This option is equivalent to
596 the "-p" command line argument. The file must be accessible to the user
597 starting the process. See also "daemon".
598
Willy Tarreau110ecc12012-11-15 17:50:01 +0100599stats bind-process [ all | odd | even | <number 1-32>[-<number 1-32>] ] ...
Willy Tarreau35b7b162012-10-22 23:17:18 +0200600 Limits the stats socket to a certain set of processes numbers. By default the
601 stats socket is bound to all processes, causing a warning to be emitted when
602 nbproc is greater than 1 because there is no way to select the target process
603 when connecting. However, by using this setting, it becomes possible to pin
604 the stats socket to a specific set of processes, typically the first one. The
605 warning will automatically be disabled when this setting is used, whatever
606 the number of processes used.
607
Willy Tarreauabb175f2012-09-24 12:43:26 +0200608stats socket [<address:port>|<path>] [param*]
609 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
610 Connections to this socket will return various statistics outputs and even
611 allow some commands to be issued to change some runtime settings. Please
612 consult section 9.2 "Unix Socket commands" for more details.
Willy Tarreau6162db22009-10-10 17:13:00 +0200613
Willy Tarreauabb175f2012-09-24 12:43:26 +0200614 All parameters supported by "bind" lines are supported, for instance to
615 restrict access to some users or their access rights. Please consult
616 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200617
618stats timeout <timeout, in milliseconds>
619 The default timeout on the stats socket is set to 10 seconds. It is possible
620 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +0100621 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200622
623stats maxconn <connections>
624 By default, the stats socket is limited to 10 concurrent connections. It is
625 possible to change this value with "stats maxconn".
626
Willy Tarreau6a06a402007-07-15 20:15:28 +0200627uid <number>
628 Changes the process' user ID to <number>. It is recommended that the user ID
629 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
630 be started with superuser privileges in order to be able to switch to another
631 one. See also "gid" and "user".
632
633ulimit-n <number>
634 Sets the maximum number of per-process file-descriptors to <number>. By
635 default, it is automatically computed, so it is recommended not to use this
636 option.
637
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100638unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
639 [ group <group> ] [ gid <gid> ]
640
641 Fixes common settings to UNIX listening sockets declared in "bind" statements.
642 This is mainly used to simplify declaration of those UNIX sockets and reduce
643 the risk of errors, since those settings are most commonly required but are
644 also process-specific. The <prefix> setting can be used to force all socket
645 path to be relative to that directory. This might be needed to access another
646 component's chroot. Note that those paths are resolved before haproxy chroots
647 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
648 all have the same meaning as their homonyms used by the "bind" statement. If
649 both are specified, the "bind" statement has priority, meaning that the
650 "unix-bind" settings may be seen as process-wide default settings.
651
Willy Tarreau6a06a402007-07-15 20:15:28 +0200652user <user name>
653 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
654 See also "uid" and "group".
655
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200656node <name>
657 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
658
659 This statement is useful in HA configurations where two or more processes or
660 servers share the same IP address. By setting a different node-name on all
661 nodes, it becomes easy to immediately spot what server is handling the
662 traffic.
663
664description <text>
665 Add a text that describes the instance.
666
667 Please note that it is required to escape certain characters (# for example)
668 and this text is inserted into a html page so you should avoid using
669 "<" and ">" characters.
670
Willy Tarreau6a06a402007-07-15 20:15:28 +0200671
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006723.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +0200673-----------------------
674
675maxconn <number>
676 Sets the maximum per-process number of concurrent connections to <number>. It
677 is equivalent to the command-line argument "-n". Proxies will stop accepting
678 connections when this limit is reached. The "ulimit-n" parameter is
679 automatically adjusted according to this value. See also "ulimit-n".
680
Willy Tarreau81c25d02011-09-07 15:17:21 +0200681maxconnrate <number>
682 Sets the maximum per-process number of connections per second to <number>.
683 Proxies will stop accepting connections when this limit is reached. It can be
684 used to limit the global capacity regardless of each frontend capacity. It is
685 important to note that this can only be used as a service protection measure,
686 as there will not necessarily be a fair share between frontends when the
687 limit is reached, so it's a good idea to also limit each frontend to some
688 value close to its expected share. Also, lowering tune.maxaccept can improve
689 fairness.
690
William Lallemandd85f9172012-11-09 17:05:39 +0100691maxcomprate <number>
692 Sets the maximum per-process input compression rate to <number> kilobytes
693 pers second. For each session, if the maximum is reached, the compression
694 level will be decreased during the session. If the maximum is reached at the
695 beginning of a session, the session will not compress at all. If the maximum
696 is not reached, the compression level will be increased up to
697 tune.comp.maxlevel. A value of zero means there is no limit, this is the
698 default value.
699
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100700maxpipes <number>
701 Sets the maximum per-process number of pipes to <number>. Currently, pipes
702 are only used by kernel-based tcp splicing. Since a pipe contains two file
703 descriptors, the "ulimit-n" value will be increased accordingly. The default
704 value is maxconn/4, which seems to be more than enough for most heavy usages.
705 The splice code dynamically allocates and releases pipes, and can fall back
706 to standard copy, so setting this value too low may only impact performance.
707
Willy Tarreau403edff2012-09-06 11:58:37 +0200708maxsslconn <number>
709 Sets the maximum per-process number of concurrent SSL connections to
710 <number>. By default there is no SSL-specific limit, which means that the
711 global maxconn setting will apply to all connections. Setting this limit
712 avoids having openssl use too much memory and crash when malloc returns NULL
713 (since it unfortunately does not reliably check for such conditions). Note
714 that the limit applies both to incoming and outgoing connections, so one
715 connection which is deciphered then ciphered accounts for 2 SSL connections.
716
William Lallemand9d5f5482012-11-07 16:12:57 +0100717maxzlibmem <number>
718 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
719 When the maximum amount is reached, future sessions will not compress as long
720 as RAM is unavailable. When sets to 0, there is no limit.
721 The default value is 0.
722
Willy Tarreau6a06a402007-07-15 20:15:28 +0200723noepoll
724 Disables the use of the "epoll" event polling system on Linux. It is
725 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100726 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +0200727
728nokqueue
729 Disables the use of the "kqueue" event polling system on BSD. It is
730 equivalent to the command-line argument "-dk". The next polling system
731 used will generally be "poll". See also "nopoll".
732
733nopoll
734 Disables the use of the "poll" event polling system. It is equivalent to the
735 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +0100736 It should never be needed to disable "poll" since it's available on all
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100737 platforms supported by HAProxy. See also "nokqueue" and "noepoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +0200738
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100739nosplice
740 Disables the use of kernel tcp splicing between sockets on Linux. It is
741 equivalent to the command line argument "-dS". Data will then be copied
742 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100743 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100744 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
745 be used. This option makes it easier to globally disable kernel splicing in
746 case of doubt. See also "option splice-auto", "option splice-request" and
747 "option splice-response".
748
Willy Tarreaufe255b72007-10-14 23:09:26 +0200749spread-checks <0..50, in percent>
750 Sometimes it is desirable to avoid sending health checks to servers at exact
751 intervals, for instance when many logical servers are located on the same
752 physical server. With the help of this parameter, it becomes possible to add
753 some randomness in the check interval between 0 and +/- 50%. A value between
754 2 and 5 seems to show good results. The default value remains at 0.
755
Willy Tarreau27a674e2009-08-17 07:23:33 +0200756tune.bufsize <number>
757 Sets the buffer size to this size (in bytes). Lower values allow more
758 sessions to coexist in the same amount of RAM, and higher values allow some
759 applications with very large cookies to work. The default value is 16384 and
760 can be changed at build time. It is strongly recommended not to change this
761 from the default value, as very low values will break some services such as
762 statistics, and values larger than default size will increase memory usage,
763 possibly causing the system to run out of memory. At least the global maxconn
764 parameter should be decreased by the same factor as this one is increased.
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +0400765 If HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will
766 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
767 than this size, haproxy will return HTTP 502 (Bad Gateway).
Willy Tarreau27a674e2009-08-17 07:23:33 +0200768
Willy Tarreau43961d52010-10-04 20:39:20 +0200769tune.chksize <number>
770 Sets the check buffer size to this size (in bytes). Higher values may help
771 find string or regex patterns in very large pages, though doing so may imply
772 more memory and CPU usage. The default value is 16384 and can be changed at
773 build time. It is not recommended to change this value, but to use better
774 checks whenever possible.
775
William Lallemandf3747832012-11-09 12:33:10 +0100776tune.comp.maxlevel <number>
777 Sets the maximum compression level. The compression level affects CPU
778 usage during compression. This value affects CPU usage during compression.
779 Each session using compression initializes the compression algorithm with
780 this value. The default value is 1.
781
Willy Tarreauac1932d2011-10-24 19:14:41 +0200782tune.http.maxhdr <number>
783 Sets the maximum number of headers in a request. When a request comes with a
784 number of headers greater than this value (including the first line), it is
785 rejected with a "400 Bad Request" status code. Similarly, too large responses
786 are blocked with "502 Bad Gateway". The default value is 101, which is enough
787 for all usages, considering that the widely deployed Apache server uses the
788 same limit. It can be useful to push this limit further to temporarily allow
789 a buggy application to work by the time it gets fixed. Keep in mind that each
790 new header consumes 32bits of memory for each session, so don't push this
791 limit too high.
792
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100793tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +0100794 Sets the maximum number of consecutive connections a process may accept in a
795 row before switching to other work. In single process mode, higher numbers
796 give better performance at high connection rates. However in multi-process
797 modes, keeping a bit of fairness between processes generally is better to
798 increase performance. This value applies individually to each listener, so
799 that the number of processes a listener is bound to is taken into account.
800 This value defaults to 64. In multi-process mode, it is divided by twice
801 the number of processes the listener is bound to. Setting this value to -1
802 completely disables the limitation. It should normally not be needed to tweak
803 this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100804
805tune.maxpollevents <number>
806 Sets the maximum amount of events that can be processed at once in a call to
807 the polling system. The default value is adapted to the operating system. It
808 has been noticed that reducing it below 200 tends to slightly decrease
809 latency at the expense of network bandwidth, and increasing it above 200
810 tends to trade latency for slightly increased bandwidth.
811
Willy Tarreau27a674e2009-08-17 07:23:33 +0200812tune.maxrewrite <number>
813 Sets the reserved buffer space to this size in bytes. The reserved space is
814 used for header rewriting or appending. The first reads on sockets will never
815 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
816 bufsize, though that does not make much sense since there are rarely large
817 numbers of headers to add. Setting it too high prevents processing of large
818 requests or responses. Setting it too low prevents addition of new headers
819 to already large requests or to POST requests. It is generally wise to set it
820 to about 1024. It is automatically readjusted to half of bufsize if it is
821 larger than that. This means you don't have to worry about it when changing
822 bufsize.
823
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200824tune.pipesize <number>
825 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
826 are the default size for the system. But sometimes when using TCP splicing,
827 it can improve performance to increase pipe sizes, especially if it is
828 suspected that pipes are not filled and that many calls to splice() are
829 performed. This has an impact on the kernel's memory footprint, so this must
830 not be changed if impacts are not understood.
831
Willy Tarreaue803de22010-01-21 17:43:04 +0100832tune.rcvbuf.client <number>
833tune.rcvbuf.server <number>
834 Forces the kernel socket receive buffer size on the client or the server side
835 to the specified value in bytes. This value applies to all TCP/HTTP frontends
836 and backends. It should normally never be set, and the default size (0) lets
837 the kernel autotune this value depending on the amount of available memory.
838 However it can sometimes help to set it to very low values (eg: 4096) in
839 order to save kernel memory by preventing it from buffering too large amounts
840 of received data. Lower values will significantly increase CPU usage though.
841
842tune.sndbuf.client <number>
843tune.sndbuf.server <number>
844 Forces the kernel socket send buffer size on the client or the server side to
845 the specified value in bytes. This value applies to all TCP/HTTP frontends
846 and backends. It should normally never be set, and the default size (0) lets
847 the kernel autotune this value depending on the amount of available memory.
848 However it can sometimes help to set it to very low values (eg: 4096) in
849 order to save kernel memory by preventing it from buffering too large amounts
850 of received data. Lower values will significantly increase CPU usage though.
851 Another use case is to prevent write timeouts with extremely slow clients due
852 to the kernel waiting for a large part of the buffer to be read before
853 notifying haproxy again.
854
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100855tune.ssl.cachesize <number>
856 Sets the size of the global SSL session cache, in number of sessions. Each
857 entry uses approximately 600 bytes of memory. The default value may be forced
858 at build time, otherwise defaults to 20000. When the cache is full, the most
859 idle entries are purged and reassigned. Higher values reduce the occurrence
860 of such a purge, hence the number of CPU-intensive SSL handshakes by ensuring
861 that all users keep their session as long as possible. All entries are pre-
862 allocated upon startup and are shared between all processes if "nbproc" is
863 greater than 1.
864
Emeric Brun4f65bff2012-11-16 15:11:00 +0100865tune.ssl.lifetime <timeout>
866 Sets how long a cached SSL session may remain valid. This time is expressed
867 in seconds and defaults to 300 (5 mn). It is important to understand that it
868 does not guarantee that sessions will last that long, because if the cache is
869 full, the longest idle sessions will be purged despite their configured
870 lifetime. The real usefulness of this setting is to prevent sessions from
871 being used for too long.
872
William Lallemanda509e4c2012-11-07 16:54:34 +0100873tune.zlib.memlevel <number>
874 Sets the memLevel parameter in zlib initialization for each session. It
875 defines how much memory should be allocated for the intenal compression
876 state. A value of 1 uses minimum memory but is slow and reduces compression
877 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
878 between 1 and 9. The default value is 8.
879
880tune.zlib.windowsize <number>
881 Sets the window size (the size of the history buffer) as a parameter of the
882 zlib initialization for each session. Larger values of this parameter result
883 in better compression at the expense of memory usage. Can be a value between
884 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200885
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008863.3. Debugging
887--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200888
889debug
890 Enables debug mode which dumps to stdout all exchanges, and disables forking
891 into background. It is the equivalent of the command-line argument "-d". It
892 should never be used in a production configuration since it may prevent full
893 system startup.
894
895quiet
896 Do not display any message during startup. It is equivalent to the command-
897 line argument "-q".
898
Emeric Brunf099e792010-09-27 12:05:28 +0200899
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01009003.4. Userlists
901--------------
902It is possible to control access to frontend/backend/listen sections or to
903http stats by allowing only authenticated and authorized users. To do this,
904it is required to create at least one userlist and to define users.
905
906userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +0100907 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100908 used to store authentication & authorization data for independent customers.
909
910group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +0100911 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100912 attach users to this group by using a comma separated list of names
913 proceeded by "users" keyword.
914
Cyril Bontéf0c60612010-02-06 14:44:47 +0100915user <username> [password|insecure-password <password>]
916 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100917 Adds user <username> to the current userlist. Both secure (encrypted) and
918 insecure (unencrypted) passwords can be used. Encrypted passwords are
Cyril Bonté78caf842010-03-10 22:41:43 +0100919 evaluated using the crypt(3) function so depending of the system's
920 capabilities, different algorithms are supported. For example modern Glibc
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100921 based Linux system supports MD5, SHA-256, SHA-512 and of course classic,
922 DES-based method of crypting passwords.
923
924
925 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +0100926 userlist L1
927 group G1 users tiger,scott
928 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100929
Cyril Bontéf0c60612010-02-06 14:44:47 +0100930 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
931 user scott insecure-password elgato
932 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100933
Cyril Bontéf0c60612010-02-06 14:44:47 +0100934 userlist L2
935 group G1
936 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100937
Cyril Bontéf0c60612010-02-06 14:44:47 +0100938 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
939 user scott insecure-password elgato groups G1,G2
940 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100941
942 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200943
Emeric Brunf099e792010-09-27 12:05:28 +0200944
9453.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +0200946----------
Emeric Brunf099e792010-09-27 12:05:28 +0200947It is possible to synchronize server entries in stick tables between several
948haproxy instances over TCP connections in a multi-master fashion. Each instance
949pushes its local updates and insertions to remote peers. Server IDs are used to
950identify servers remotely, so it is important that configurations look similar
951or at least that the same IDs are forced on each server on all participants.
952Interrupted exchanges are automatically detected and recovered from the last
953known point. In addition, during a soft restart, the old process connects to
954the new one using such a TCP connection to push all its entries before the new
955process tries to connect to other peers. That ensures very fast replication
956during a reload, it typically takes a fraction of a second even for large
957tables.
958
959peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -0400960 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +0200961 which is referenced by one or more stick-tables.
962
963peer <peername> <ip>:<port>
964 Defines a peer inside a peers section.
965 If <peername> is set to the local peer name (by default hostname, or forced
966 using "-L" command line option), haproxy will listen for incoming remote peer
967 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
968 to join the remote peer, and <peername> is used at the protocol level to
969 identify and validate the remote peer on the server side.
970
971 During a soft restart, local peer <ip>:<port> is used by the old instance to
972 connect the new one and initiate a complete replication (teaching process).
973
974 It is strongly recommended to have the exact same peers declaration on all
975 peers and to only rely on the "-L" command line argument to change the local
976 peer name. This makes it easier to maintain coherent configuration files
977 across all peers.
978
Cyril Bontédc4d9032012-04-08 21:57:39 +0200979 Example:
Emeric Brunf099e792010-09-27 12:05:28 +0200980 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +0100981 peer haproxy1 192.168.0.1:1024
982 peer haproxy2 192.168.0.2:1024
983 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +0200984
985 backend mybackend
986 mode tcp
987 balance roundrobin
988 stick-table type ip size 20k peers mypeers
989 stick on src
990
Willy Tarreauf7b30a92010-12-06 22:59:17 +0100991 server srv1 192.168.0.30:80
992 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +0200993
994
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009954. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +0200996----------
Willy Tarreau0ba27502007-12-24 16:55:16 +0100997
Willy Tarreau6a06a402007-07-15 20:15:28 +0200998Proxy configuration can be located in a set of sections :
999 - defaults <name>
1000 - frontend <name>
1001 - backend <name>
1002 - listen <name>
1003
1004A "defaults" section sets default parameters for all other sections following
1005its declaration. Those default parameters are reset by the next "defaults"
1006section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +01001007section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001008
1009A "frontend" section describes a set of listening sockets accepting client
1010connections.
1011
1012A "backend" section describes a set of servers to which the proxy will connect
1013to forward incoming connections.
1014
1015A "listen" section defines a complete proxy with its frontend and backend
1016parts combined in one section. It is generally useful for TCP-only traffic.
1017
Willy Tarreau0ba27502007-12-24 16:55:16 +01001018All proxy names must be formed from upper and lower case letters, digits,
1019'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
1020case-sensitive, which means that "www" and "WWW" are two different proxies.
1021
1022Historically, all proxy names could overlap, it just caused troubles in the
1023logs. Since the introduction of content switching, it is mandatory that two
1024proxies with overlapping capabilities (frontend/backend) have different names.
1025However, it is still permitted that a frontend and a backend share the same
1026name, as this configuration seems to be commonly encountered.
1027
1028Right now, two major proxy modes are supported : "tcp", also known as layer 4,
1029and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001030bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01001031protocol, and can interact with it by allowing, blocking, switching, adding,
1032modifying, or removing arbitrary contents in requests or responses, based on
1033arbitrary criteria.
1034
Willy Tarreau0ba27502007-12-24 16:55:16 +01001035
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010364.1. Proxy keywords matrix
1037--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001038
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001039The following list of keywords is supported. Most of them may only be used in a
1040limited set of section types. Some of them are marked as "deprecated" because
1041they are inherited from an old syntax which may be confusing or functionally
1042limited, and there are new recommended keywords to replace them. Keywords
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001043marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001044option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02001045and must be disabled for a specific instance. Such options may also be prefixed
1046with "default" in order to restore default settings regardless of what has been
1047specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001048
Willy Tarreau6a06a402007-07-15 20:15:28 +02001049
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001050 keyword defaults frontend listen backend
1051------------------------------------+----------+----------+---------+---------
1052acl - X X X
1053appsession - - X X
1054backlog X X X -
1055balance X - X X
1056bind - X X -
1057bind-process X X X X
1058block - X X X
1059capture cookie - X X -
1060capture request header - X X -
1061capture response header - X X -
1062clitimeout (deprecated) X X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02001063compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001064contimeout (deprecated) X - X X
1065cookie X - X X
1066default-server X - X X
1067default_backend X X X -
1068description - X X X
1069disabled X X X X
1070dispatch - - X X
1071enabled X X X X
1072errorfile X X X X
1073errorloc X X X X
1074errorloc302 X X X X
1075-- keyword -------------------------- defaults - frontend - listen -- backend -
1076errorloc303 X X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001077force-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001078fullconn X - X X
1079grace X X X X
1080hash-type X - X X
1081http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +01001082http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02001083http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001084http-request - X X X
1085id - X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001086ignore-persist - X X X
William Lallemand0f99e342011-10-12 17:50:54 +02001087log (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001088maxconn X X X -
1089mode X X X X
1090monitor fail - X X -
1091monitor-net X X X -
1092monitor-uri X X X -
1093option abortonclose (*) X - X X
1094option accept-invalid-http-request (*) X X X -
1095option accept-invalid-http-response (*) X - X X
1096option allbackups (*) X - X X
1097option checkcache (*) X - X X
1098option clitcpka (*) X X X -
1099option contstats (*) X X X -
1100option dontlog-normal (*) X X X -
1101option dontlognull (*) X X X -
1102option forceclose (*) X X X X
1103-- keyword -------------------------- defaults - frontend - listen -- backend -
1104option forwardfor X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02001105option http-no-delay (*) X X X X
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02001106option http-pretend-keepalive (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001107option http-server-close (*) X X X X
1108option http-use-proxy-header (*) X X X -
1109option httpchk X - X X
1110option httpclose (*) X X X X
1111option httplog X X X X
1112option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001113option independent-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02001114option ldap-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001115option log-health-checks (*) X - X X
1116option log-separate-errors (*) X X X -
1117option logasap (*) X X X -
1118option mysql-check X - X X
Rauf Kuliyev38b41562011-01-04 15:14:13 +01001119option pgsql-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001120option nolinger (*) X X X X
1121option originalto X X X X
1122option persist (*) X - X X
1123option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02001124option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001125option smtpchk X - X X
1126option socket-stats (*) X X X -
1127option splice-auto (*) X X X X
1128option splice-request (*) X X X X
1129option splice-response (*) X X X X
1130option srvtcpka (*) X - X X
1131option ssl-hello-chk X - X X
1132-- keyword -------------------------- defaults - frontend - listen -- backend -
1133option tcp-smart-accept (*) X X X -
1134option tcp-smart-connect (*) X - X X
1135option tcpka X X X X
1136option tcplog X X X X
1137option transparent (*) X - X X
1138persist rdp-cookie X - X X
1139rate-limit sessions X X X -
1140redirect - X X X
1141redisp (deprecated) X - X X
1142redispatch (deprecated) X - X X
1143reqadd - X X X
1144reqallow - X X X
1145reqdel - X X X
1146reqdeny - X X X
1147reqiallow - X X X
1148reqidel - X X X
1149reqideny - X X X
1150reqipass - X X X
1151reqirep - X X X
1152reqisetbe - X X X
1153reqitarpit - X X X
1154reqpass - X X X
1155reqrep - X X X
1156-- keyword -------------------------- defaults - frontend - listen -- backend -
1157reqsetbe - X X X
1158reqtarpit - X X X
1159retries X - X X
1160rspadd - X X X
1161rspdel - X X X
1162rspdeny - X X X
1163rspidel - X X X
1164rspideny - X X X
1165rspirep - X X X
1166rsprep - X X X
1167server - - X X
1168source X - X X
1169srvtimeout (deprecated) X - X X
Cyril Bonté66c327d2010-10-12 00:14:37 +02001170stats admin - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001171stats auth X - X X
1172stats enable X - X X
1173stats hide-version X - X X
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02001174stats http-request - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001175stats realm X - X X
1176stats refresh X - X X
1177stats scope X - X X
1178stats show-desc X - X X
1179stats show-legends X - X X
1180stats show-node X - X X
1181stats uri X - X X
1182-- keyword -------------------------- defaults - frontend - listen -- backend -
1183stick match - - X X
1184stick on - - X X
1185stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02001186stick store-response - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001187stick-table - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02001188tcp-request connection - X X -
1189tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02001190tcp-request inspect-delay - X X X
Emeric Brun0a3b67f2010-09-24 15:34:53 +02001191tcp-response content - - X X
1192tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001193timeout check X - X X
1194timeout client X X X -
1195timeout clitimeout (deprecated) X X X -
1196timeout connect X - X X
1197timeout contimeout (deprecated) X - X X
1198timeout http-keep-alive X X X X
1199timeout http-request X X X X
1200timeout queue X - X X
1201timeout server X - X X
1202timeout srvtimeout (deprecated) X - X X
1203timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02001204timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001205transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01001206unique-id-format X X X -
1207unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001208use_backend - X X -
Willy Tarreau4a5cade2012-04-05 21:09:48 +02001209use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001210------------------------------------+----------+----------+---------+---------
1211 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02001212
Willy Tarreau0ba27502007-12-24 16:55:16 +01001213
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012144.2. Alphabetically sorted keywords reference
1215---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001216
1217This section provides a description of each keyword and its usage.
1218
1219
1220acl <aclname> <criterion> [flags] [operator] <value> ...
1221 Declare or complete an access list.
1222 May be used in sections : defaults | frontend | listen | backend
1223 no | yes | yes | yes
1224 Example:
1225 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1226 acl invalid_src src_port 0:1023
1227 acl local_dst hdr(host) -i localhost
1228
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001229 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001230
1231
Cyril Bontéb21570a2009-11-29 20:04:48 +01001232appsession <cookie> len <length> timeout <holdtime>
1233 [request-learn] [prefix] [mode <path-parameters|query-string>]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001234 Define session stickiness on an existing application cookie.
1235 May be used in sections : defaults | frontend | listen | backend
1236 no | no | yes | yes
1237 Arguments :
1238 <cookie> this is the name of the cookie used by the application and which
1239 HAProxy will have to learn for each new session.
1240
Cyril Bontéb21570a2009-11-29 20:04:48 +01001241 <length> this is the max number of characters that will be memorized and
Willy Tarreau0ba27502007-12-24 16:55:16 +01001242 checked in each cookie value.
1243
1244 <holdtime> this is the time after which the cookie will be removed from
1245 memory if unused. If no unit is specified, this time is in
1246 milliseconds.
1247
Cyril Bontébf47aeb2009-10-15 00:15:40 +02001248 request-learn
1249 If this option is specified, then haproxy will be able to learn
1250 the cookie found in the request in case the server does not
1251 specify any in response. This is typically what happens with
1252 PHPSESSID cookies, or when haproxy's session expires before
1253 the application's session and the correct server is selected.
1254 It is recommended to specify this option to improve reliability.
1255
Cyril Bontéb21570a2009-11-29 20:04:48 +01001256 prefix When this option is specified, haproxy will match on the cookie
1257 prefix (or URL parameter prefix). The appsession value is the
1258 data following this prefix.
1259
1260 Example :
1261 appsession ASPSESSIONID len 64 timeout 3h prefix
1262
1263 This will match the cookie ASPSESSIONIDXXXX=XXXXX,
1264 the appsession value will be XXXX=XXXXX.
1265
1266 mode This option allows to change the URL parser mode.
1267 2 modes are currently supported :
1268 - path-parameters :
1269 The parser looks for the appsession in the path parameters
1270 part (each parameter is separated by a semi-colon), which is
1271 convenient for JSESSIONID for example.
1272 This is the default mode if the option is not set.
1273 - query-string :
1274 In this mode, the parser will look for the appsession in the
1275 query string.
1276
Willy Tarreau0ba27502007-12-24 16:55:16 +01001277 When an application cookie is defined in a backend, HAProxy will check when
1278 the server sets such a cookie, and will store its value in a table, and
1279 associate it with the server's identifier. Up to <length> characters from
1280 the value will be retained. On each connection, haproxy will look for this
Cyril Bontéb21570a2009-11-29 20:04:48 +01001281 cookie both in the "Cookie:" headers, and as a URL parameter (depending on
1282 the mode used). If a known value is found, the client will be directed to the
1283 server associated with this value. Otherwise, the load balancing algorithm is
Willy Tarreau0ba27502007-12-24 16:55:16 +01001284 applied. Cookies are automatically removed from memory when they have been
1285 unused for a duration longer than <holdtime>.
1286
1287 The definition of an application cookie is limited to one per backend.
1288
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001289 Note : Consider not using this feature in multi-process mode (nbproc > 1)
1290 unless you know what you do : memory is not shared between the
1291 processes, which can result in random behaviours.
1292
Willy Tarreau0ba27502007-12-24 16:55:16 +01001293 Example :
1294 appsession JSESSIONID len 52 timeout 3h
1295
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001296 See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
1297 "ignore-persist", "nbproc" and "bind-process".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001298
1299
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001300backlog <conns>
1301 Give hints to the system about the approximate listen backlog desired size
1302 May be used in sections : defaults | frontend | listen | backend
1303 yes | yes | yes | no
1304 Arguments :
1305 <conns> is the number of pending connections. Depending on the operating
1306 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02001307 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001308
1309 In order to protect against SYN flood attacks, one solution is to increase
1310 the system's SYN backlog size. Depending on the system, sometimes it is just
1311 tunable via a system parameter, sometimes it is not adjustable at all, and
1312 sometimes the system relies on hints given by the application at the time of
1313 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
1314 to the listen() syscall. On systems which can make use of this value, it can
1315 sometimes be useful to be able to specify a different value, hence this
1316 backlog parameter.
1317
1318 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
1319 used as a hint and the system accepts up to the smallest greater power of
1320 two, and never more than some limits (usually 32768).
1321
1322 See also : "maxconn" and the target operating system's tuning guide.
1323
1324
Willy Tarreau0ba27502007-12-24 16:55:16 +01001325balance <algorithm> [ <arguments> ]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001326balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001327 Define the load balancing algorithm to be used in a backend.
1328 May be used in sections : defaults | frontend | listen | backend
1329 yes | no | yes | yes
1330 Arguments :
1331 <algorithm> is the algorithm used to select a server when doing load
1332 balancing. This only applies when no persistence information
1333 is available, or when a connection is redispatched to another
1334 server. <algorithm> may be one of the following :
1335
1336 roundrobin Each server is used in turns, according to their weights.
1337 This is the smoothest and fairest algorithm when the server's
1338 processing time remains equally distributed. This algorithm
1339 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02001340 on the fly for slow starts for instance. It is limited by
1341 design to 4128 active servers per backend. Note that in some
1342 large farms, when a server becomes up after having been down
1343 for a very short time, it may sometimes take a few hundreds
1344 requests for it to be re-integrated into the farm and start
1345 receiving traffic. This is normal, though very rare. It is
1346 indicated here in case you would have the chance to observe
1347 it, so that you don't worry.
1348
1349 static-rr Each server is used in turns, according to their weights.
1350 This algorithm is as similar to roundrobin except that it is
1351 static, which means that changing a server's weight on the
1352 fly will have no effect. On the other hand, it has no design
1353 limitation on the number of servers, and when a server goes
1354 up, it is always immediately reintroduced into the farm, once
1355 the full map is recomputed. It also uses slightly less CPU to
1356 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01001357
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01001358 leastconn The server with the lowest number of connections receives the
1359 connection. Round-robin is performed within groups of servers
1360 of the same load to ensure that all servers will be used. Use
1361 of this algorithm is recommended where very long sessions are
1362 expected, such as LDAP, SQL, TSE, etc... but is not very well
1363 suited for protocols using short sessions such as HTTP. This
1364 algorithm is dynamic, which means that server weights may be
1365 adjusted on the fly for slow starts for instance.
1366
Willy Tarreauf09c6602012-02-13 17:12:08 +01001367 first The first server with available connection slots receives the
1368 connection. The servers are choosen from the lowest numeric
1369 identifier to the highest (see server parameter "id"), which
1370 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02001371 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01001372 not make sense to use this algorithm without setting maxconn.
1373 The purpose of this algorithm is to always use the smallest
1374 number of servers so that extra servers can be powered off
1375 during non-intensive hours. This algorithm ignores the server
1376 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02001377 or IMAP than HTTP, though it can be useful there too. In
1378 order to use this algorithm efficiently, it is recommended
1379 that a cloud controller regularly checks server usage to turn
1380 them off when unused, and regularly checks backend queue to
1381 turn new servers on when the queue inflates. Alternatively,
1382 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01001383
Willy Tarreau0ba27502007-12-24 16:55:16 +01001384 source The source IP address is hashed and divided by the total
1385 weight of the running servers to designate which server will
1386 receive the request. This ensures that the same client IP
1387 address will always reach the same server as long as no
1388 server goes down or up. If the hash result changes due to the
1389 number of running servers changing, many clients will be
1390 directed to a different server. This algorithm is generally
1391 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001392 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01001393 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001394 static by default, which means that changing a server's
1395 weight on the fly will have no effect, but this can be
1396 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001397
Oskar Stolc8dc41842012-05-19 10:19:54 +01001398 uri This algorithm hashes either the left part of the URI (before
1399 the question mark) or the whole URI (if the "whole" parameter
1400 is present) and divides the hash value by the total weight of
1401 the running servers. The result designates which server will
1402 receive the request. This ensures that the same URI will
1403 always be directed to the same server as long as no server
1404 goes up or down. This is used with proxy caches and
1405 anti-virus proxies in order to maximize the cache hit rate.
1406 Note that this algorithm may only be used in an HTTP backend.
1407 This algorithm is static by default, which means that
1408 changing a server's weight on the fly will have no effect,
1409 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001410
Oskar Stolc8dc41842012-05-19 10:19:54 +01001411 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001412 "depth", both followed by a positive integer number. These
1413 options may be helpful when it is needed to balance servers
1414 based on the beginning of the URI only. The "len" parameter
1415 indicates that the algorithm should only consider that many
1416 characters at the beginning of the URI to compute the hash.
1417 Note that having "len" set to 1 rarely makes sense since most
1418 URIs start with a leading "/".
1419
1420 The "depth" parameter indicates the maximum directory depth
1421 to be used to compute the hash. One level is counted for each
1422 slash in the request. If both parameters are specified, the
1423 evaluation stops when either is reached.
1424
Willy Tarreau0ba27502007-12-24 16:55:16 +01001425 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001426 the query string of each HTTP GET request.
1427
1428 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02001429 request entity will be searched for the parameter argument,
1430 when it is not found in a query string after a question mark
1431 ('?') in the URL. Optionally, specify a number of octets to
1432 wait for before attempting to search the message body. If the
1433 entity can not be searched, then round robin is used for each
1434 request. For instance, if your clients always send the LB
1435 parameter in the first 128 bytes, then specify that. The
1436 default is 48. The entity data will not be scanned until the
1437 required number of octets have arrived at the gateway, this
1438 is the minimum of: (default/max_wait, Content-Length or first
1439 chunk length). If Content-Length is missing or zero, it does
1440 not need to wait for more data than the client promised to
1441 send. When Content-Length is present and larger than
1442 <max_wait>, then waiting is limited to <max_wait> and it is
1443 assumed that this will be enough data to search for the
1444 presence of the parameter. In the unlikely event that
1445 Transfer-Encoding: chunked is used, only the first chunk is
1446 scanned. Parameter values separated by a chunk boundary, may
1447 be randomly balanced if at all.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001448
1449 If the parameter is found followed by an equal sign ('=') and
1450 a value, then the value is hashed and divided by the total
1451 weight of the running servers. The result designates which
1452 server will receive the request.
1453
1454 This is used to track user identifiers in requests and ensure
1455 that a same user ID will always be sent to the same server as
1456 long as no server goes up or down. If no value is found or if
1457 the parameter is not found, then a round robin algorithm is
1458 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001459 backend. This algorithm is static by default, which means
1460 that changing a server's weight on the fly will have no
1461 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001462
Cyril Bontédc4d9032012-04-08 21:57:39 +02001463 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
1464 request. Just as with the equivalent ACL 'hdr()' function,
1465 the header name in parenthesis is not case sensitive. If the
1466 header is absent or if it does not contain any value, the
1467 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01001468
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001469 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01001470 reducing the hash algorithm to the main domain part with some
1471 specific headers such as 'Host'. For instance, in the Host
1472 value "haproxy.1wt.eu", only "1wt" will be considered.
1473
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001474 This algorithm is static by default, which means that
1475 changing a server's weight on the fly will have no effect,
1476 but this can be changed using "hash-type".
1477
Emeric Brun736aa232009-06-30 17:56:00 +02001478 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02001479 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02001480 The RDP cookie <name> (or "mstshash" if omitted) will be
1481 looked up and hashed for each incoming TCP request. Just as
1482 with the equivalent ACL 'req_rdp_cookie()' function, the name
1483 is not case-sensitive. This mechanism is useful as a degraded
1484 persistence mode, as it makes it possible to always send the
1485 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001486 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02001487 used instead.
1488
1489 Note that for this to work, the frontend must ensure that an
1490 RDP cookie is already present in the request buffer. For this
1491 you must use 'tcp-request content accept' rule combined with
1492 a 'req_rdp_cookie_cnt' ACL.
1493
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001494 This algorithm is static by default, which means that
1495 changing a server's weight on the fly will have no effect,
1496 but this can be changed using "hash-type".
1497
Cyril Bontédc4d9032012-04-08 21:57:39 +02001498 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09001499
Willy Tarreau0ba27502007-12-24 16:55:16 +01001500 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001501 algorithms. Right now, only "url_param" and "uri" support an
1502 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001503
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001504 balance uri [len <len>] [depth <depth>]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001505 balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001506
Willy Tarreau3cd9af22009-03-15 14:06:41 +01001507 The load balancing algorithm of a backend is set to roundrobin when no other
1508 algorithm, mode nor option have been set. The algorithm may only be set once
1509 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001510
1511 Examples :
1512 balance roundrobin
1513 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001514 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01001515 balance hdr(User-Agent)
1516 balance hdr(host)
1517 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001518
1519 Note: the following caveats and limitations on using the "check_post"
1520 extension with "url_param" must be considered :
1521
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001522 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001523 to determine if the parameters will be found in the body or entity which
1524 may contain binary data. Therefore another method may be required to
1525 restrict consideration of POST requests that have no URL parameters in
1526 the body. (see acl reqideny http_end)
1527
1528 - using a <max_wait> value larger than the request buffer size does not
1529 make sense and is useless. The buffer size is set at build time, and
1530 defaults to 16 kB.
1531
1532 - Content-Encoding is not supported, the parameter search will probably
1533 fail; and load balancing will fall back to Round Robin.
1534
1535 - Expect: 100-continue is not supported, load balancing will fall back to
1536 Round Robin.
1537
1538 - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk.
1539 If the entire parameter value is not present in the first chunk, the
1540 selection of server is undefined (actually, defined by how little
1541 actually appeared in the first chunk).
1542
1543 - This feature does not support generation of a 100, 411 or 501 response.
1544
1545 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001546 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001547 white space or control characters are found, indicating the end of what
1548 might be a URL parameter list. This is probably not a concern with SGML
1549 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001550
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001551 See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and
1552 "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001553
1554
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001555bind [<address>]:<port_range> [, ...] [param*]
1556bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001557 Define one or several listening addresses and/or ports in a frontend.
1558 May be used in sections : defaults | frontend | listen | backend
1559 no | yes | yes | no
1560 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001561 <address> is optional and can be a host name, an IPv4 address, an IPv6
1562 address, or '*'. It designates the address the frontend will
1563 listen on. If unset, all IPv4 addresses of the system will be
1564 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01001565 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001566
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001567 <port_range> is either a unique TCP port, or a port range for which the
1568 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001569 above. The port is mandatory for TCP listeners. Note that in
1570 the case of an IPv6 address, the port is always the number
1571 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001572 - a numerical port (ex: '80')
1573 - a dash-delimited ports range explicitly stating the lower
1574 and upper bounds (ex: '2000-2100') which are included in
1575 the range.
1576
1577 Particular care must be taken against port ranges, because
1578 every <address:port> couple consumes one socket (= a file
1579 descriptor), so it's easy to consume lots of descriptors
1580 with a simple range, and to run out of sockets. Also, each
1581 <address:port> couple must be used only once among all
1582 instances running on a same system. Please note that binding
1583 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001584 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001585 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001586
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001587 <path> is a UNIX socket path beginning with a slash ('/'). This is
1588 alternative to the TCP listening port. Haproxy will then
1589 receive UNIX connections on the socket located at this place.
1590 The path must begin with a slash and by default is absolute.
1591 It can be relative to the prefix defined by "unix-bind" in
1592 the global section. Note that the total length of the prefix
1593 followed by the socket path cannot exceed some system limits
1594 for UNIX sockets, which commonly are set to 107 characters.
1595
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001596 <param*> is a list of parameters common to all sockets declared on the
1597 same line. These numerous parameters depend on OS and build
1598 options and have a complete section dedicated to them. Please
1599 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001600
Willy Tarreau0ba27502007-12-24 16:55:16 +01001601 It is possible to specify a list of address:port combinations delimited by
1602 commas. The frontend will then listen on all of these addresses. There is no
1603 fixed limit to the number of addresses and ports which can be listened on in
1604 a frontend, as well as there is no limit to the number of "bind" statements
1605 in a frontend.
1606
1607 Example :
1608 listen http_proxy
1609 bind :80,:443
1610 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001611 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01001612
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001613 listen http_https_proxy
1614 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02001615 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001616
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001617 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001618 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001619
1620
Willy Tarreau110ecc12012-11-15 17:50:01 +01001621bind-process [ all | odd | even | <number 1-32>[-<number 1-32>] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001622 Limit visibility of an instance to a certain set of processes numbers.
1623 May be used in sections : defaults | frontend | listen | backend
1624 yes | yes | yes | yes
1625 Arguments :
1626 all All process will see this instance. This is the default. It
1627 may be used to override a default value.
1628
1629 odd This instance will be enabled on processes 1,3,5,...31. This
1630 option may be combined with other numbers.
1631
1632 even This instance will be enabled on processes 2,4,6,...32. This
1633 option may be combined with other numbers. Do not use it
1634 with less than 2 processes otherwise some instances might be
1635 missing from all processes.
1636
Willy Tarreau110ecc12012-11-15 17:50:01 +01001637 number The instance will be enabled on this process number or range,
1638 whose values must all be between 1 and 32. You must be
1639 careful not to reference a process number greater than the
1640 configured global.nbproc, otherwise some instances might be
1641 missing from all processes.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001642
1643 This keyword limits binding of certain instances to certain processes. This
1644 is useful in order not to have too many processes listening to the same
1645 ports. For instance, on a dual-core machine, it might make sense to set
1646 'nbproc 2' in the global section, then distributes the listeners among 'odd'
1647 and 'even' instances.
1648
1649 At the moment, it is not possible to reference more than 32 processes using
1650 this keyword, but this should be more than enough for most setups. Please
1651 note that 'all' really means all processes and is not limited to the first
1652 32.
1653
1654 If some backends are referenced by frontends bound to other processes, the
1655 backend automatically inherits the frontend's processes.
1656
1657 Example :
1658 listen app_ip1
1659 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001660 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001661
1662 listen app_ip2
1663 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001664 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001665
1666 listen management
1667 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001668 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001669
Willy Tarreau110ecc12012-11-15 17:50:01 +01001670 listen management
1671 bind 10.0.0.4:80
1672 bind-process 1-4
1673
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001674 See also : "nbproc" in global section.
1675
1676
Willy Tarreau0ba27502007-12-24 16:55:16 +01001677block { if | unless } <condition>
1678 Block a layer 7 request if/unless a condition is matched
1679 May be used in sections : defaults | frontend | listen | backend
1680 no | yes | yes | yes
1681
1682 The HTTP request will be blocked very early in the layer 7 processing
1683 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001684 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02001685 typically used to deny access to certain sensitive resources if some
Willy Tarreau0ba27502007-12-24 16:55:16 +01001686 conditions are met or not met. There is no fixed limit to the number of
1687 "block" statements per instance.
1688
1689 Example:
1690 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1691 acl invalid_src src_port 0:1023
1692 acl local_dst hdr(host) -i localhost
1693 block if invalid_src || local_dst
1694
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001695 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001696
1697
1698capture cookie <name> len <length>
1699 Capture and log a cookie in the request and in the response.
1700 May be used in sections : defaults | frontend | listen | backend
1701 no | yes | yes | no
1702 Arguments :
1703 <name> is the beginning of the name of the cookie to capture. In order
1704 to match the exact name, simply suffix the name with an equal
1705 sign ('='). The full name will appear in the logs, which is
1706 useful with application servers which adjust both the cookie name
1707 and value (eg: ASPSESSIONXXXXX).
1708
1709 <length> is the maximum number of characters to report in the logs, which
1710 include the cookie name, the equal sign and the value, all in the
1711 standard "name=value" form. The string will be truncated on the
1712 right if it exceeds <length>.
1713
1714 Only the first cookie is captured. Both the "cookie" request headers and the
1715 "set-cookie" response headers are monitored. This is particularly useful to
1716 check for application bugs causing session crossing or stealing between
1717 users, because generally the user's cookies can only change on a login page.
1718
1719 When the cookie was not presented by the client, the associated log column
1720 will report "-". When a request does not cause a cookie to be assigned by the
1721 server, a "-" is reported in the response column.
1722
1723 The capture is performed in the frontend only because it is necessary that
1724 the log format does not change for a given frontend depending on the
1725 backends. This may change in the future. Note that there can be only one
1726 "capture cookie" statement in a frontend. The maximum capture length is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001727 configured in the sources by default to 64 characters. It is not possible to
Willy Tarreau0ba27502007-12-24 16:55:16 +01001728 specify a capture in a "defaults" section.
1729
1730 Example:
1731 capture cookie ASPSESSION len 32
1732
1733 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001734 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001735
1736
1737capture request header <name> len <length>
1738 Capture and log the first occurrence of the specified request header.
1739 May be used in sections : defaults | frontend | listen | backend
1740 no | yes | yes | no
1741 Arguments :
1742 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001743 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001744 appear in the requests, with the first letter of each word in
1745 upper case. The header name will not appear in the logs, only the
1746 value is reported, but the position in the logs is respected.
1747
1748 <length> is the maximum number of characters to extract from the value and
1749 report in the logs. The string will be truncated on the right if
1750 it exceeds <length>.
1751
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001752 Only the first value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001753 value will be added to the logs between braces ('{}'). If multiple headers
1754 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001755 in the same order they were declared in the configuration. Non-existent
1756 headers will be logged just as an empty string. Common uses for request
1757 header captures include the "Host" field in virtual hosting environments, the
1758 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001759 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001760 environments to find where the request came from.
1761
1762 Note that when capturing headers such as "User-agent", some spaces may be
1763 logged, making the log analysis more difficult. Thus be careful about what
1764 you log if you know your log parser is not smart enough to rely on the
1765 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001766
1767 There is no limit to the number of captured request headers, but each capture
1768 is limited to 64 characters. In order to keep log format consistent for a
1769 same frontend, header captures can only be declared in a frontend. It is not
1770 possible to specify a capture in a "defaults" section.
1771
1772 Example:
1773 capture request header Host len 15
1774 capture request header X-Forwarded-For len 15
1775 capture request header Referrer len 15
1776
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001777 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001778 about logging.
1779
1780
1781capture response header <name> len <length>
1782 Capture and log the first occurrence of the specified response header.
1783 May be used in sections : defaults | frontend | listen | backend
1784 no | yes | yes | no
1785 Arguments :
1786 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001787 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001788 appear in the response, with the first letter of each word in
1789 upper case. The header name will not appear in the logs, only the
1790 value is reported, but the position in the logs is respected.
1791
1792 <length> is the maximum number of characters to extract from the value and
1793 report in the logs. The string will be truncated on the right if
1794 it exceeds <length>.
1795
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001796 Only the first value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001797 result will be added to the logs between braces ('{}') after the captured
1798 request headers. If multiple headers are captured, they will be delimited by
1799 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001800 the configuration. Non-existent headers will be logged just as an empty
1801 string. Common uses for response header captures include the "Content-length"
1802 header which indicates how many bytes are expected to be returned, the
1803 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001804
1805 There is no limit to the number of captured response headers, but each
1806 capture is limited to 64 characters. In order to keep log format consistent
1807 for a same frontend, header captures can only be declared in a frontend. It
1808 is not possible to specify a capture in a "defaults" section.
1809
1810 Example:
1811 capture response header Content-length len 9
1812 capture response header Location len 15
1813
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001814 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001815 about logging.
1816
1817
Cyril Bontéf0c60612010-02-06 14:44:47 +01001818clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01001819 Set the maximum inactivity time on the client side.
1820 May be used in sections : defaults | frontend | listen | backend
1821 yes | yes | yes | no
1822 Arguments :
1823 <timeout> is the timeout value is specified in milliseconds by default, but
1824 can be in any other unit if the number is suffixed by the unit,
1825 as explained at the top of this document.
1826
1827 The inactivity timeout applies when the client is expected to acknowledge or
1828 send data. In HTTP mode, this timeout is particularly important to consider
1829 during the first phase, when the client sends the request, and during the
1830 response while it is reading data sent by the server. The value is specified
1831 in milliseconds by default, but can be in any other unit if the number is
1832 suffixed by the unit, as specified at the top of this document. In TCP mode
1833 (and to a lesser extent, in HTTP mode), it is highly recommended that the
1834 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001835 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01001836 losses by specifying timeouts that are slightly above multiples of 3 seconds
1837 (eg: 4 or 5 seconds).
1838
1839 This parameter is specific to frontends, but can be specified once for all in
1840 "defaults" sections. This is in fact one of the easiest solutions not to
1841 forget about it. An unspecified timeout results in an infinite timeout, which
1842 is not recommended. Such a usage is accepted and works but reports a warning
1843 during startup because it may results in accumulation of expired sessions in
1844 the system if the system's timeouts are not configured either.
1845
1846 This parameter is provided for compatibility but is currently deprecated.
1847 Please use "timeout client" instead.
1848
Willy Tarreau036fae02008-01-06 13:24:40 +01001849 See also : "timeout client", "timeout http-request", "timeout server", and
1850 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001851
Cyril Bonté316a8cf2012-11-11 13:38:27 +01001852compression algo <algorithm> ...
1853compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02001854compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02001855 Enable HTTP compression.
1856 May be used in sections : defaults | frontend | listen | backend
1857 yes | yes | yes | yes
1858 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01001859 algo is followed by the list of supported compression algorithms.
1860 type is followed by the list of MIME types that will be compressed.
1861 offload makes haproxy work as a compression offloader only (see notes).
1862
1863 The currently supported algorithms are :
1864 identity this is mostly for debugging, and it was useful for developping
1865 the compression feature. Identity does not apply any change on
1866 data.
1867
1868 gzip applies gzip compression. This setting is only available when
1869 support for zlib was built in.
1870
1871 deflate same as gzip, but with deflate algorithm and zlib format.
1872 Note that this algorithm has ambiguous support on many browsers
1873 and no support at all from recent ones. It is strongly
1874 recommended not to use it for anything else than experimentation.
1875 This setting is only available when support for zlib was built
1876 in.
1877
1878 Compression will be activated depending of the Accept-Encoding request
1879 header. With identity, it does not take care of that header.
Willy Tarreau70737d12012-10-27 00:34:28 +02001880
1881 The "offload" setting makes haproxy remove the Accept-Encoding header to
1882 prevent backend servers from compressing responses. It is strongly
1883 recommended not to do this because this means that all the compression work
1884 will be done on the single point where haproxy is located. However in some
1885 deployment scenarios, haproxy may be installed in front of a buggy gateway
1886 and need to prevent it from emitting invalid payloads. In this case, simply
1887 removing the header in the configuration does not work because it applies
1888 before the header is parsed, so that prevents haproxy from compressing. The
1889 "offload" setting should then be used for such scenarios.
William Lallemand82fe75c2012-10-23 10:25:10 +02001890
1891 Examples :
1892 compression algo gzip
1893 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01001894
Cyril Bontéf0c60612010-02-06 14:44:47 +01001895contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01001896 Set the maximum time to wait for a connection attempt to a server to succeed.
1897 May be used in sections : defaults | frontend | listen | backend
1898 yes | no | yes | yes
1899 Arguments :
1900 <timeout> is the timeout value is specified in milliseconds by default, but
1901 can be in any other unit if the number is suffixed by the unit,
1902 as explained at the top of this document.
1903
1904 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001905 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01001906 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01001907 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
1908 connect timeout also presets the queue timeout to the same value if this one
1909 has not been specified. Historically, the contimeout was also used to set the
1910 tarpit timeout in a listen section, which is not possible in a pure frontend.
1911
1912 This parameter is specific to backends, but can be specified once for all in
1913 "defaults" sections. This is in fact one of the easiest solutions not to
1914 forget about it. An unspecified timeout results in an infinite timeout, which
1915 is not recommended. Such a usage is accepted and works but reports a warning
1916 during startup because it may results in accumulation of failed sessions in
1917 the system if the system's timeouts are not configured either.
1918
1919 This parameter is provided for backwards compatibility but is currently
1920 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
1921 instead.
1922
1923 See also : "timeout connect", "timeout queue", "timeout tarpit",
1924 "timeout server", "contimeout".
1925
1926
Willy Tarreau55165fe2009-05-10 12:02:55 +02001927cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02001928 [ postonly ] [ preserve ] [ httponly ] [ secure ]
1929 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001930 Enable cookie-based persistence in a backend.
1931 May be used in sections : defaults | frontend | listen | backend
1932 yes | no | yes | yes
1933 Arguments :
1934 <name> is the name of the cookie which will be monitored, modified or
1935 inserted in order to bring persistence. This cookie is sent to
1936 the client via a "Set-Cookie" header in the response, and is
1937 brought back by the client in a "Cookie" header in all requests.
1938 Special care should be taken to choose a name which does not
1939 conflict with any likely application cookie. Also, if the same
1940 backends are subject to be used by the same clients (eg:
1941 HTTP/HTTPS), care should be taken to use different cookie names
1942 between all backends if persistence between them is not desired.
1943
1944 rewrite This keyword indicates that the cookie will be provided by the
1945 server and that haproxy will have to modify its value to set the
1946 server's identifier in it. This mode is handy when the management
1947 of complex combinations of "Set-cookie" and "Cache-control"
1948 headers is left to the application. The application can then
1949 decide whether or not it is appropriate to emit a persistence
1950 cookie. Since all responses should be monitored, this mode only
1951 works in HTTP close mode. Unless the application behaviour is
1952 very complex and/or broken, it is advised not to start with this
1953 mode for new deployments. This keyword is incompatible with
1954 "insert" and "prefix".
1955
1956 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02001957 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001958
Willy Tarreaua79094d2010-08-31 22:54:15 +02001959 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001960 server. When used without the "preserve" option, if the server
1961 emits a cookie with the same name, it will be remove before
1962 processing. For this reason, this mode can be used to upgrade
1963 existing configurations running in the "rewrite" mode. The cookie
1964 will only be a session cookie and will not be stored on the
1965 client's disk. By default, unless the "indirect" option is added,
1966 the server will see the cookies emitted by the client. Due to
1967 caching effects, it is generally wise to add the "nocache" or
1968 "postonly" keywords (see below). The "insert" keyword is not
1969 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001970
1971 prefix This keyword indicates that instead of relying on a dedicated
1972 cookie for the persistence, an existing one will be completed.
1973 This may be needed in some specific environments where the client
1974 does not support more than one single cookie and the application
1975 already needs it. In this case, whenever the server sets a cookie
1976 named <name>, it will be prefixed with the server's identifier
1977 and a delimiter. The prefix will be removed from all client
1978 requests so that the server still finds the cookie it emitted.
1979 Since all requests and responses are subject to being modified,
1980 this mode requires the HTTP close mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02001981 not compatible with "rewrite" and "insert". Note: it is highly
1982 recommended not to use "indirect" with "prefix", otherwise server
1983 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001984
Willy Tarreaua79094d2010-08-31 22:54:15 +02001985 indirect When this option is specified, no cookie will be emitted to a
1986 client which already has a valid one for the server which has
1987 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02001988 it will be removed, unless the "preserve" option is also set. In
1989 "insert" mode, this will additionally remove cookies from the
1990 requests transmitted to the server, making the persistence
1991 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02001992 Note: it is highly recommended not to use "indirect" with
1993 "prefix", otherwise server cookie updates would not be sent to
1994 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001995
1996 nocache This option is recommended in conjunction with the insert mode
1997 when there is a cache between the client and HAProxy, as it
1998 ensures that a cacheable response will be tagged non-cacheable if
1999 a cookie needs to be inserted. This is important because if all
2000 persistence cookies are added on a cacheable home page for
2001 instance, then all customers will then fetch the page from an
2002 outer cache and will all share the same persistence cookie,
2003 leading to one server receiving much more traffic than others.
2004 See also the "insert" and "postonly" options.
2005
2006 postonly This option ensures that cookie insertion will only be performed
2007 on responses to POST requests. It is an alternative to the
2008 "nocache" option, because POST responses are not cacheable, so
2009 this ensures that the persistence cookie will never get cached.
2010 Since most sites do not need any sort of persistence before the
2011 first POST which generally is a login request, this is a very
2012 efficient method to optimize caching without risking to find a
2013 persistence cookie in the cache.
2014 See also the "insert" and "nocache" options.
2015
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002016 preserve This option may only be used with "insert" and/or "indirect". It
2017 allows the server to emit the persistence cookie itself. In this
2018 case, if a cookie is found in the response, haproxy will leave it
2019 untouched. This is useful in order to end persistence after a
2020 logout request for instance. For this, the server just has to
2021 emit a cookie with an invalid value (eg: empty) or with a date in
2022 the past. By combining this mechanism with the "disable-on-404"
2023 check option, it is possible to perform a completely graceful
2024 shutdown because users will definitely leave the server after
2025 they logout.
2026
Willy Tarreau4992dd22012-05-31 21:02:17 +02002027 httponly This option tells haproxy to add an "HttpOnly" cookie attribute
2028 when a cookie is inserted. This attribute is used so that a
2029 user agent doesn't share the cookie with non-HTTP components.
2030 Please check RFC6265 for more information on this attribute.
2031
2032 secure This option tells haproxy to add a "Secure" cookie attribute when
2033 a cookie is inserted. This attribute is used so that a user agent
2034 never emits this cookie over non-secure channels, which means
2035 that a cookie learned with this flag will be presented only over
2036 SSL/TLS connections. Please check RFC6265 for more information on
2037 this attribute.
2038
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002039 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002040 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01002041 name. If the domain begins with a dot, the browser is allowed to
2042 use it for any host ending with that name. It is also possible to
2043 specify several domain names by invoking this option multiple
2044 times. Some browsers might have small limits on the number of
2045 domains, so be careful when doing that. For the record, sending
2046 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002047
Willy Tarreau996a92c2010-10-13 19:30:47 +02002048 maxidle This option allows inserted cookies to be ignored after some idle
2049 time. It only works with insert-mode cookies. When a cookie is
2050 sent to the client, the date this cookie was emitted is sent too.
2051 Upon further presentations of this cookie, if the date is older
2052 than the delay indicated by the parameter (in seconds), it will
2053 be ignored. Otherwise, it will be refreshed if needed when the
2054 response is sent to the client. This is particularly useful to
2055 prevent users who never close their browsers from remaining for
2056 too long on the same server (eg: after a farm size change). When
2057 this option is set and a cookie has no date, it is always
2058 accepted, but gets refreshed in the response. This maintains the
2059 ability for admins to access their sites. Cookies that have a
2060 date in the future further than 24 hours are ignored. Doing so
2061 lets admins fix timezone issues without risking kicking users off
2062 the site.
2063
2064 maxlife This option allows inserted cookies to be ignored after some life
2065 time, whether they're in use or not. It only works with insert
2066 mode cookies. When a cookie is first sent to the client, the date
2067 this cookie was emitted is sent too. Upon further presentations
2068 of this cookie, if the date is older than the delay indicated by
2069 the parameter (in seconds), it will be ignored. If the cookie in
2070 the request has no date, it is accepted and a date will be set.
2071 Cookies that have a date in the future further than 24 hours are
2072 ignored. Doing so lets admins fix timezone issues without risking
2073 kicking users off the site. Contrary to maxidle, this value is
2074 not refreshed, only the first visit date counts. Both maxidle and
2075 maxlife may be used at the time. This is particularly useful to
2076 prevent users who never close their browsers from remaining for
2077 too long on the same server (eg: after a farm size change). This
2078 is stronger than the maxidle method in that it forces a
2079 redispatch after some absolute delay.
2080
Willy Tarreau0ba27502007-12-24 16:55:16 +01002081 There can be only one persistence cookie per HTTP backend, and it can be
2082 declared in a defaults section. The value of the cookie will be the value
2083 indicated after the "cookie" keyword in a "server" statement. If no cookie
2084 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002085
Willy Tarreau0ba27502007-12-24 16:55:16 +01002086 Examples :
2087 cookie JSESSIONID prefix
2088 cookie SRV insert indirect nocache
2089 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02002090 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01002091
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002092 See also : "appsession", "balance source", "capture cookie", "server"
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002093 and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002094
Willy Tarreau983e01e2010-01-11 18:42:06 +01002095
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002096default-server [param*]
2097 Change default options for a server in a backend
2098 May be used in sections : defaults | frontend | listen | backend
2099 yes | no | yes | yes
2100 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01002101 <param*> is a list of parameters for this server. The "default-server"
2102 keyword accepts an important number of options and has a complete
2103 section dedicated to it. Please refer to section 5 for more
2104 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002105
Willy Tarreau983e01e2010-01-11 18:42:06 +01002106 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002107 default-server inter 1000 weight 13
2108
2109 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01002110
Willy Tarreau983e01e2010-01-11 18:42:06 +01002111
Willy Tarreau0ba27502007-12-24 16:55:16 +01002112default_backend <backend>
2113 Specify the backend to use when no "use_backend" rule has been matched.
2114 May be used in sections : defaults | frontend | listen | backend
2115 yes | yes | yes | no
2116 Arguments :
2117 <backend> is the name of the backend to use.
2118
2119 When doing content-switching between frontend and backends using the
2120 "use_backend" keyword, it is often useful to indicate which backend will be
2121 used when no rule has matched. It generally is the dynamic backend which
2122 will catch all undetermined requests.
2123
Willy Tarreau0ba27502007-12-24 16:55:16 +01002124 Example :
2125
2126 use_backend dynamic if url_dyn
2127 use_backend static if url_css url_img extension_img
2128 default_backend dynamic
2129
Willy Tarreau2769aa02007-12-27 18:26:09 +01002130 See also : "use_backend", "reqsetbe", "reqisetbe"
2131
Willy Tarreau0ba27502007-12-24 16:55:16 +01002132
2133disabled
2134 Disable a proxy, frontend or backend.
2135 May be used in sections : defaults | frontend | listen | backend
2136 yes | yes | yes | yes
2137 Arguments : none
2138
2139 The "disabled" keyword is used to disable an instance, mainly in order to
2140 liberate a listening port or to temporarily disable a service. The instance
2141 will still be created and its configuration will be checked, but it will be
2142 created in the "stopped" state and will appear as such in the statistics. It
2143 will not receive any traffic nor will it send any health-checks or logs. It
2144 is possible to disable many instances at once by adding the "disabled"
2145 keyword in a "defaults" section.
2146
2147 See also : "enabled"
2148
2149
Willy Tarreau5ce94572010-06-07 14:35:41 +02002150dispatch <address>:<port>
2151 Set a default server address
2152 May be used in sections : defaults | frontend | listen | backend
2153 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002154 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02002155
2156 <address> is the IPv4 address of the default server. Alternatively, a
2157 resolvable hostname is supported, but this name will be resolved
2158 during start-up.
2159
2160 <ports> is a mandatory port specification. All connections will be sent
2161 to this port, and it is not permitted to use port offsets as is
2162 possible with normal servers.
2163
Willy Tarreau787aed52011-04-15 06:45:37 +02002164 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02002165 server can take the connection. In the past it was used to forward non
2166 persistent connections to an auxiliary load balancer. Due to its simple
2167 syntax, it has also been used for simple TCP relays. It is recommended not to
2168 use it for more clarity, and to use the "server" directive instead.
2169
2170 See also : "server"
2171
2172
Willy Tarreau0ba27502007-12-24 16:55:16 +01002173enabled
2174 Enable a proxy, frontend or backend.
2175 May be used in sections : defaults | frontend | listen | backend
2176 yes | yes | yes | yes
2177 Arguments : none
2178
2179 The "enabled" keyword is used to explicitly enable an instance, when the
2180 defaults has been set to "disabled". This is very rarely used.
2181
2182 See also : "disabled"
2183
2184
2185errorfile <code> <file>
2186 Return a file contents instead of errors generated by HAProxy
2187 May be used in sections : defaults | frontend | listen | backend
2188 yes | yes | yes | yes
2189 Arguments :
2190 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002191 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002192
2193 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002194 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01002195 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01002196 error pages, and to use absolute paths, since files are read
2197 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002198
2199 It is important to understand that this keyword is not meant to rewrite
2200 errors returned by the server, but errors detected and returned by HAProxy.
2201 This is why the list of supported errors is limited to a small set.
2202
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002203 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2204
Willy Tarreau0ba27502007-12-24 16:55:16 +01002205 The files are returned verbatim on the TCP socket. This allows any trick such
2206 as redirections to another URL or site, as well as tricks to clean cookies,
2207 force enable or disable caching, etc... The package provides default error
2208 files returning the same contents as default errors.
2209
Willy Tarreau59140a22009-02-22 12:02:30 +01002210 The files should not exceed the configured buffer size (BUFSIZE), which
2211 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
2212 not to put any reference to local contents (eg: images) in order to avoid
2213 loops between the client and HAProxy when all servers are down, causing an
2214 error to be returned instead of an image. For better HTTP compliance, it is
2215 recommended that all header lines end with CR-LF and not LF alone.
2216
Willy Tarreau0ba27502007-12-24 16:55:16 +01002217 The files are read at the same time as the configuration and kept in memory.
2218 For this reason, the errors continue to be returned even when the process is
2219 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01002220 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002221 403 status code and interrogating a blocked URL.
2222
2223 See also : "errorloc", "errorloc302", "errorloc303"
2224
Willy Tarreau59140a22009-02-22 12:02:30 +01002225 Example :
2226 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
2227 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
2228 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
2229
Willy Tarreau2769aa02007-12-27 18:26:09 +01002230
2231errorloc <code> <url>
2232errorloc302 <code> <url>
2233 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2234 May be used in sections : defaults | frontend | listen | backend
2235 yes | yes | yes | yes
2236 Arguments :
2237 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002238 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002239
2240 <url> it is the exact contents of the "Location" header. It may contain
2241 either a relative URI to an error page hosted on the same site,
2242 or an absolute URI designating an error page on another site.
2243 Special care should be given to relative URIs to avoid redirect
2244 loops if the URI itself may generate the same error (eg: 500).
2245
2246 It is important to understand that this keyword is not meant to rewrite
2247 errors returned by the server, but errors detected and returned by HAProxy.
2248 This is why the list of supported errors is limited to a small set.
2249
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002250 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2251
Willy Tarreau2769aa02007-12-27 18:26:09 +01002252 Note that both keyword return the HTTP 302 status code, which tells the
2253 client to fetch the designated URL using the same HTTP method. This can be
2254 quite problematic in case of non-GET methods such as POST, because the URL
2255 sent to the client might not be allowed for something other than GET. To
2256 workaround this problem, please use "errorloc303" which send the HTTP 303
2257 status code, indicating to the client that the URL must be fetched with a GET
2258 request.
2259
2260 See also : "errorfile", "errorloc303"
2261
2262
2263errorloc303 <code> <url>
2264 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2265 May be used in sections : defaults | frontend | listen | backend
2266 yes | yes | yes | yes
2267 Arguments :
2268 <code> is the HTTP status code. Currently, HAProxy is capable of
2269 generating codes 400, 403, 408, 500, 502, 503, and 504.
2270
2271 <url> it is the exact contents of the "Location" header. It may contain
2272 either a relative URI to an error page hosted on the same site,
2273 or an absolute URI designating an error page on another site.
2274 Special care should be given to relative URIs to avoid redirect
2275 loops if the URI itself may generate the same error (eg: 500).
2276
2277 It is important to understand that this keyword is not meant to rewrite
2278 errors returned by the server, but errors detected and returned by HAProxy.
2279 This is why the list of supported errors is limited to a small set.
2280
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002281 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2282
Willy Tarreau2769aa02007-12-27 18:26:09 +01002283 Note that both keyword return the HTTP 303 status code, which tells the
2284 client to fetch the designated URL using the same HTTP GET method. This
2285 solves the usual problems associated with "errorloc" and the 302 code. It is
2286 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002287 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002288
2289 See also : "errorfile", "errorloc", "errorloc302"
2290
2291
Willy Tarreau4de91492010-01-22 19:10:05 +01002292force-persist { if | unless } <condition>
2293 Declare a condition to force persistence on down servers
2294 May be used in sections: defaults | frontend | listen | backend
2295 no | yes | yes | yes
2296
2297 By default, requests are not dispatched to down servers. It is possible to
2298 force this using "option persist", but it is unconditional and redispatches
2299 to a valid server if "option redispatch" is set. That leaves with very little
2300 possibilities to force some requests to reach a server which is artificially
2301 marked down for maintenance operations.
2302
2303 The "force-persist" statement allows one to declare various ACL-based
2304 conditions which, when met, will cause a request to ignore the down status of
2305 a server and still try to connect to it. That makes it possible to start a
2306 server, still replying an error to the health checks, and run a specially
2307 configured browser to test the service. Among the handy methods, one could
2308 use a specific source IP address, or a specific cookie. The cookie also has
2309 the advantage that it can easily be added/removed on the browser from a test
2310 page. Once the service is validated, it is then possible to open the service
2311 to the world by returning a valid response to health checks.
2312
2313 The forced persistence is enabled when an "if" condition is met, or unless an
2314 "unless" condition is met. The final redispatch is always disabled when this
2315 is used.
2316
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002317 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002318 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01002319
2320
Willy Tarreau2769aa02007-12-27 18:26:09 +01002321fullconn <conns>
2322 Specify at what backend load the servers will reach their maxconn
2323 May be used in sections : defaults | frontend | listen | backend
2324 yes | no | yes | yes
2325 Arguments :
2326 <conns> is the number of connections on the backend which will make the
2327 servers use the maximal number of connections.
2328
Willy Tarreau198a7442008-01-17 12:05:32 +01002329 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01002330 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01002331 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01002332 load. The server will then always accept at least <minconn> connections,
2333 never more than <maxconn>, and the limit will be on the ramp between both
2334 values when the backend has less than <conns> concurrent connections. This
2335 makes it possible to limit the load on the servers during normal loads, but
2336 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002337 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002338
Willy Tarreaufbb78422011-06-05 15:38:35 +02002339 Since it's hard to get this value right, haproxy automatically sets it to
2340 10% of the sum of the maxconns of all frontends that may branch to this
2341 backend. That way it's safe to leave it unset.
2342
Willy Tarreau2769aa02007-12-27 18:26:09 +01002343 Example :
2344 # The servers will accept between 100 and 1000 concurrent connections each
2345 # and the maximum of 1000 will be reached when the backend reaches 10000
2346 # connections.
2347 backend dynamic
2348 fullconn 10000
2349 server srv1 dyn1:80 minconn 100 maxconn 1000
2350 server srv2 dyn2:80 minconn 100 maxconn 1000
2351
2352 See also : "maxconn", "server"
2353
2354
2355grace <time>
2356 Maintain a proxy operational for some time after a soft stop
2357 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01002358 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01002359 Arguments :
2360 <time> is the time (by default in milliseconds) for which the instance
2361 will remain operational with the frontend sockets still listening
2362 when a soft-stop is received via the SIGUSR1 signal.
2363
2364 This may be used to ensure that the services disappear in a certain order.
2365 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002366 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01002367 needed by the equipment to detect the failure.
2368
2369 Note that currently, there is very little benefit in using this parameter,
2370 and it may in fact complicate the soft-reconfiguration process more than
2371 simplify it.
2372
Willy Tarreau0ba27502007-12-24 16:55:16 +01002373
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002374hash-type <method>
2375 Specify a method to use for mapping hashes to servers
2376 May be used in sections : defaults | frontend | listen | backend
2377 yes | no | yes | yes
2378 Arguments :
2379 map-based the hash table is a static array containing all alive servers.
2380 The hashes will be very smooth, will consider weights, but will
2381 be static in that weight changes while a server is up will be
2382 ignored. This means that there will be no slow start. Also,
2383 since a server is selected by its position in the array, most
2384 mappings are changed when the server count changes. This means
2385 that when a server goes up or down, or when a server is added
2386 to a farm, most connections will be redistributed to different
2387 servers. This can be inconvenient with caches for instance.
2388
Willy Tarreau798a39c2010-11-24 15:04:29 +01002389 avalanche this mechanism uses the default map-based hashing described
2390 above but applies a full avalanche hash before performing the
2391 mapping. The result is a slightly less smooth hash for most
2392 situations, but the hash becomes better than pure map-based
2393 hashes when the number of servers is a multiple of the size of
2394 the input set. When using URI hash with a number of servers
2395 multiple of 64, it's desirable to change the hash type to
2396 this value.
2397
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002398 consistent the hash table is a tree filled with many occurrences of each
2399 server. The hash key is looked up in the tree and the closest
2400 server is chosen. This hash is dynamic, it supports changing
2401 weights while the servers are up, so it is compatible with the
2402 slow start feature. It has the advantage that when a server
2403 goes up or down, only its associations are moved. When a server
2404 is added to the farm, only a few part of the mappings are
2405 redistributed, making it an ideal algorithm for caches.
2406 However, due to its principle, the algorithm will never be very
2407 smooth and it may sometimes be necessary to adjust a server's
2408 weight or its ID to get a more balanced distribution. In order
2409 to get the same distribution on multiple load balancers, it is
2410 important that all servers have the same IDs.
2411
2412 The default hash type is "map-based" and is recommended for most usages.
2413
2414 See also : "balance", "server"
2415
2416
Willy Tarreau0ba27502007-12-24 16:55:16 +01002417http-check disable-on-404
2418 Enable a maintenance mode upon HTTP/404 response to health-checks
2419 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01002420 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01002421 Arguments : none
2422
2423 When this option is set, a server which returns an HTTP code 404 will be
2424 excluded from further load-balancing, but will still receive persistent
2425 connections. This provides a very convenient method for Web administrators
2426 to perform a graceful shutdown of their servers. It is also important to note
2427 that a server which is detected as failed while it was in this mode will not
2428 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
2429 will immediately be reinserted into the farm. The status on the stats page
2430 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01002431 option only works in conjunction with the "httpchk" option. If this option
2432 is used with "http-check expect", then it has precedence over it so that 404
2433 responses will still be considered as soft-stop.
2434
2435 See also : "option httpchk", "http-check expect"
2436
2437
2438http-check expect [!] <match> <pattern>
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002439 Make HTTP health checks consider response contents or specific status codes
Willy Tarreaubd741542010-03-16 18:46:54 +01002440 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau1ee51a62011-08-19 20:04:17 +02002441 yes | no | yes | yes
Willy Tarreaubd741542010-03-16 18:46:54 +01002442 Arguments :
2443 <match> is a keyword indicating how to look for a specific pattern in the
2444 response. The keyword may be one of "status", "rstatus",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002445 "string", or "rstring". The keyword may be preceded by an
Willy Tarreaubd741542010-03-16 18:46:54 +01002446 exclamation mark ("!") to negate the match. Spaces are allowed
2447 between the exclamation mark and the keyword. See below for more
2448 details on the supported keywords.
2449
2450 <pattern> is the pattern to look for. It may be a string or a regular
2451 expression. If the pattern contains spaces, they must be escaped
2452 with the usual backslash ('\').
2453
2454 By default, "option httpchk" considers that response statuses 2xx and 3xx
2455 are valid, and that others are invalid. When "http-check expect" is used,
2456 it defines what is considered valid or invalid. Only one "http-check"
2457 statement is supported in a backend. If a server fails to respond or times
2458 out, the check obviously fails. The available matches are :
2459
2460 status <string> : test the exact string match for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002461 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002462 response's status code is exactly this string. If the
2463 "status" keyword is prefixed with "!", then the response
2464 will be considered invalid if the status code matches.
2465
2466 rstatus <regex> : test a regular expression for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002467 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002468 response's status code matches the expression. If the
2469 "rstatus" keyword is prefixed with "!", then the response
2470 will be considered invalid if the status code matches.
2471 This is mostly used to check for multiple codes.
2472
2473 string <string> : test the exact string match in the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002474 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002475 response's body contains this exact string. If the
2476 "string" keyword is prefixed with "!", then the response
2477 will be considered invalid if the body contains this
2478 string. This can be used to look for a mandatory word at
2479 the end of a dynamic page, or to detect a failure when a
2480 specific error appears on the check page (eg: a stack
2481 trace).
2482
2483 rstring <regex> : test a regular expression on the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002484 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002485 response's body matches this expression. If the "rstring"
2486 keyword is prefixed with "!", then the response will be
2487 considered invalid if the body matches the expression.
2488 This can be used to look for a mandatory word at the end
2489 of a dynamic page, or to detect a failure when a specific
2490 error appears on the check page (eg: a stack trace).
2491
2492 It is important to note that the responses will be limited to a certain size
2493 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
2494 Thus, too large responses may not contain the mandatory pattern when using
2495 "string" or "rstring". If a large response is absolutely required, it is
2496 possible to change the default max size by setting the global variable.
2497 However, it is worth keeping in mind that parsing very large responses can
2498 waste some CPU cycles, especially when regular expressions are used, and that
2499 it is always better to focus the checks on smaller resources.
2500
2501 Last, if "http-check expect" is combined with "http-check disable-on-404",
2502 then this last one has precedence when the server responds with 404.
2503
2504 Examples :
2505 # only accept status 200 as valid
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002506 http-check expect status 200
Willy Tarreaubd741542010-03-16 18:46:54 +01002507
2508 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002509 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01002510
2511 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002512 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01002513
2514 # check that we have a correct hexadecimal tag before /html
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002515 http-check expect rstring <!--tag:[0-9a-f]*</html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01002516
Willy Tarreaubd741542010-03-16 18:46:54 +01002517 See also : "option httpchk", "http-check disable-on-404"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002518
2519
Willy Tarreauef781042010-01-27 11:53:01 +01002520http-check send-state
2521 Enable emission of a state header with HTTP health checks
2522 May be used in sections : defaults | frontend | listen | backend
2523 yes | no | yes | yes
2524 Arguments : none
2525
2526 When this option is set, haproxy will systematically send a special header
2527 "X-Haproxy-Server-State" with a list of parameters indicating to each server
2528 how they are seen by haproxy. This can be used for instance when a server is
2529 manipulated without access to haproxy and the operator needs to know whether
2530 haproxy still sees it up or not, or if the server is the last one in a farm.
2531
2532 The header is composed of fields delimited by semi-colons, the first of which
2533 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
2534 checks on the total number before transition, just as appears in the stats
2535 interface. Next headers are in the form "<variable>=<value>", indicating in
2536 no specific order some values available in the stats interface :
2537 - a variable "name", containing the name of the backend followed by a slash
2538 ("/") then the name of the server. This can be used when a server is
2539 checked in multiple backends.
2540
2541 - a variable "node" containing the name of the haproxy node, as set in the
2542 global "node" variable, otherwise the system's hostname if unspecified.
2543
2544 - a variable "weight" indicating the weight of the server, a slash ("/")
2545 and the total weight of the farm (just counting usable servers). This
2546 helps to know if other servers are available to handle the load when this
2547 one fails.
2548
2549 - a variable "scur" indicating the current number of concurrent connections
2550 on the server, followed by a slash ("/") then the total number of
2551 connections on all servers of the same backend.
2552
2553 - a variable "qcur" indicating the current number of requests in the
2554 server's queue.
2555
2556 Example of a header received by the application server :
2557 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
2558 scur=13/22; qcur=0
2559
2560 See also : "option httpchk", "http-check disable-on-404"
2561
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002562http-request { allow | deny | auth [realm <realm>] }
Cyril Bontéf0c60612010-02-06 14:44:47 +01002563 [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002564 Access control for Layer 7 requests
2565
2566 May be used in sections: defaults | frontend | listen | backend
2567 no | yes | yes | yes
2568
2569 These set of options allow to fine control access to a
2570 frontend/listen/backend. Each option may be followed by if/unless and acl.
2571 First option with matched condition (or option without condition) is final.
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002572 For "deny" a 403 error will be returned, for "allow" normal processing is
2573 performed, for "auth" a 401/407 error code is returned so the client
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002574 should be asked to enter a username and password.
2575
2576 There is no fixed limit to the number of http-request statements per
2577 instance.
2578
2579 Example:
Cyril Bonté78caf842010-03-10 22:41:43 +01002580 acl nagios src 192.168.129.3
2581 acl local_net src 192.168.0.0/16
2582 acl auth_ok http_auth(L1)
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002583
Cyril Bonté78caf842010-03-10 22:41:43 +01002584 http-request allow if nagios
2585 http-request allow if local_net auth_ok
2586 http-request auth realm Gimme if local_net auth_ok
2587 http-request deny
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002588
Cyril Bonté78caf842010-03-10 22:41:43 +01002589 Example:
2590 acl auth_ok http_auth_group(L1) G1
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002591
Cyril Bonté78caf842010-03-10 22:41:43 +01002592 http-request auth unless auth_ok
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002593
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002594 See also : "stats http-request", section 3.4 about userlists and section 7
2595 about ACL usage.
Willy Tarreauef781042010-01-27 11:53:01 +01002596
Mark Lamourinec2247f02012-01-04 13:02:01 -05002597http-send-name-header [<header>]
2598 Add the server name to a request. Use the header string given by <header>
2599
2600 May be used in sections: defaults | frontend | listen | backend
2601 yes | no | yes | yes
2602
2603 Arguments :
2604
2605 <header> The header string to use to send the server name
2606
2607 The "http-send-name-header" statement causes the name of the target
2608 server to be added to the headers of an HTTP request. The name
2609 is added with the header string proved.
2610
2611 See also : "server"
2612
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01002613id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02002614 Set a persistent ID to a proxy.
2615 May be used in sections : defaults | frontend | listen | backend
2616 no | yes | yes | yes
2617 Arguments : none
2618
2619 Set a persistent ID for the proxy. This ID must be unique and positive.
2620 An unused ID will automatically be assigned if unset. The first assigned
2621 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01002622
2623
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002624ignore-persist { if | unless } <condition>
2625 Declare a condition to ignore persistence
2626 May be used in sections: defaults | frontend | listen | backend
2627 no | yes | yes | yes
2628
2629 By default, when cookie persistence is enabled, every requests containing
2630 the cookie are unconditionally persistent (assuming the target server is up
2631 and running).
2632
2633 The "ignore-persist" statement allows one to declare various ACL-based
2634 conditions which, when met, will cause a request to ignore persistence.
2635 This is sometimes useful to load balance requests for static files, which
2636 oftenly don't require persistence. This can also be used to fully disable
2637 persistence for a specific User-Agent (for example, some web crawler bots).
2638
2639 Combined with "appsession", it can also help reduce HAProxy memory usage, as
2640 the appsession table won't grow if persistence is ignored.
2641
2642 The persistence is ignored when an "if" condition is met, or unless an
2643 "unless" condition is met.
2644
2645 See also : "force-persist", "cookie", and section 7 about ACL usage.
2646
2647
Willy Tarreau2769aa02007-12-27 18:26:09 +01002648log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002649log <address> <facility> [<level> [<minlevel>]]
William Lallemand0f99e342011-10-12 17:50:54 +02002650no log
Willy Tarreau2769aa02007-12-27 18:26:09 +01002651 Enable per-instance logging of events and traffic.
2652 May be used in sections : defaults | frontend | listen | backend
2653 yes | yes | yes | yes
William Lallemand0f99e342011-10-12 17:50:54 +02002654
2655 Prefix :
2656 no should be used when the logger list must be flushed. For example,
2657 if you don't want to inherit from the default logger list. This
2658 prefix does not allow arguments.
2659
Willy Tarreau2769aa02007-12-27 18:26:09 +01002660 Arguments :
2661 global should be used when the instance's logging parameters are the
2662 same as the global ones. This is the most common usage. "global"
2663 replaces <address>, <facility> and <level> with those of the log
2664 entries found in the "global" section. Only one "log global"
2665 statement may be used per instance, and this form takes no other
2666 parameter.
2667
2668 <address> indicates where to send the logs. It takes the same format as
2669 for the "global" section's logs, and can be one of :
2670
2671 - An IPv4 address optionally followed by a colon (':') and a UDP
2672 port. If no port is specified, 514 is used by default (the
2673 standard syslog port).
2674
David du Colombier24bb5f52011-03-17 10:40:23 +01002675 - An IPv6 address followed by a colon (':') and optionally a UDP
2676 port. If no port is specified, 514 is used by default (the
2677 standard syslog port).
2678
Willy Tarreau2769aa02007-12-27 18:26:09 +01002679 - A filesystem path to a UNIX domain socket, keeping in mind
2680 considerations for chroot (be sure the path is accessible
2681 inside the chroot) and uid/gid (be sure the path is
2682 appropriately writeable).
2683
2684 <facility> must be one of the 24 standard syslog facilities :
2685
2686 kern user mail daemon auth syslog lpr news
2687 uucp cron auth2 ftp ntp audit alert cron2
2688 local0 local1 local2 local3 local4 local5 local6 local7
2689
2690 <level> is optional and can be specified to filter outgoing messages. By
2691 default, all messages are sent. If a level is specified, only
2692 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002693 will be sent. An optional minimum level can be specified. If it
2694 is set, logs emitted with a more severe level than this one will
2695 be capped to this level. This is used to avoid sending "emerg"
2696 messages on all terminals on some default syslog configurations.
2697 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01002698
2699 emerg alert crit err warning notice info debug
2700
William Lallemand0f99e342011-10-12 17:50:54 +02002701 It is important to keep in mind that it is the frontend which decides what to
2702 log from a connection, and that in case of content switching, the log entries
2703 from the backend will be ignored. Connections are logged at level "info".
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002704
2705 However, backend log declaration define how and where servers status changes
2706 will be logged. Level "notice" will be used to indicate a server going up,
2707 "warning" will be used for termination signals and definitive service
2708 termination, and "alert" will be used for when a server goes down.
2709
2710 Note : According to RFC3164, messages are truncated to 1024 bytes before
2711 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002712
2713 Example :
2714 log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002715 log 127.0.0.1:514 local0 notice # only send important events
2716 log 127.0.0.1:514 local0 notice notice # same but limit output level
Willy Tarreau2769aa02007-12-27 18:26:09 +01002717
William Lallemand48940402012-01-30 16:47:22 +01002718log-format <string>
2719 Allows you to custom a log line.
2720
2721 See also : Custom Log Format (8.2.4)
2722
Willy Tarreau2769aa02007-12-27 18:26:09 +01002723
2724maxconn <conns>
2725 Fix the maximum number of concurrent connections on a frontend
2726 May be used in sections : defaults | frontend | listen | backend
2727 yes | yes | yes | no
2728 Arguments :
2729 <conns> is the maximum number of concurrent connections the frontend will
2730 accept to serve. Excess connections will be queued by the system
2731 in the socket's listen queue and will be served once a connection
2732 closes.
2733
2734 If the system supports it, it can be useful on big sites to raise this limit
2735 very high so that haproxy manages connection queues, instead of leaving the
2736 clients with unanswered connection attempts. This value should not exceed the
2737 global maxconn. Also, keep in mind that a connection contains two buffers
2738 of 8kB each, as well as some other data resulting in about 17 kB of RAM being
2739 consumed per established connection. That means that a medium system equipped
2740 with 1GB of RAM can withstand around 40000-50000 concurrent connections if
2741 properly tuned.
2742
2743 Also, when <conns> is set to large values, it is possible that the servers
2744 are not sized to accept such loads, and for this reason it is generally wise
2745 to assign them some reasonable connection limits.
2746
Vincent Bernat6341be52012-06-27 17:18:30 +02002747 By default, this value is set to 2000.
2748
Willy Tarreau2769aa02007-12-27 18:26:09 +01002749 See also : "server", global section's "maxconn", "fullconn"
2750
2751
2752mode { tcp|http|health }
2753 Set the running mode or protocol of the instance
2754 May be used in sections : defaults | frontend | listen | backend
2755 yes | yes | yes | yes
2756 Arguments :
2757 tcp The instance will work in pure TCP mode. A full-duplex connection
2758 will be established between clients and servers, and no layer 7
2759 examination will be performed. This is the default mode. It
2760 should be used for SSL, SSH, SMTP, ...
2761
2762 http The instance will work in HTTP mode. The client request will be
2763 analyzed in depth before connecting to any server. Any request
2764 which is not RFC-compliant will be rejected. Layer 7 filtering,
2765 processing and switching will be possible. This is the mode which
2766 brings HAProxy most of its value.
2767
2768 health The instance will work in "health" mode. It will just reply "OK"
Willy Tarreau82569f92012-09-27 23:48:56 +02002769 to incoming connections and close the connection. Alternatively,
2770 If the "httpchk" option is set, "HTTP/1.0 200 OK" will be sent
2771 instead. Nothing will be logged in either case. This mode is used
2772 to reply to external components health checks. This mode is
2773 deprecated and should not be used anymore as it is possible to do
2774 the same and even better by combining TCP or HTTP modes with the
2775 "monitor" keyword.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002776
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002777 When doing content switching, it is mandatory that the frontend and the
2778 backend are in the same mode (generally HTTP), otherwise the configuration
2779 will be refused.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002780
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002781 Example :
Willy Tarreau2769aa02007-12-27 18:26:09 +01002782 defaults http_instances
2783 mode http
2784
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002785 See also : "monitor", "monitor-net"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002786
Willy Tarreau0ba27502007-12-24 16:55:16 +01002787
Cyril Bontéf0c60612010-02-06 14:44:47 +01002788monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01002789 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002790 May be used in sections : defaults | frontend | listen | backend
2791 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01002792 Arguments :
2793 if <cond> the monitor request will fail if the condition is satisfied,
2794 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002795 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01002796 are met, for instance a low number of servers both in a
2797 backend and its backup.
2798
2799 unless <cond> the monitor request will succeed only if the condition is
2800 satisfied, and will fail otherwise. Such a condition may be
2801 based on a test on the presence of a minimum number of active
2802 servers in a list of backends.
2803
2804 This statement adds a condition which can force the response to a monitor
2805 request to report a failure. By default, when an external component queries
2806 the URI dedicated to monitoring, a 200 response is returned. When one of the
2807 conditions above is met, haproxy will return 503 instead of 200. This is
2808 very useful to report a site failure to an external component which may base
2809 routing advertisements between multiple sites on the availability reported by
2810 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002811 criterion. Note that "monitor fail" only works in HTTP mode. Both status
2812 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002813
2814 Example:
2815 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01002816 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01002817 acl site_dead nbsrv(dynamic) lt 2
2818 acl site_dead nbsrv(static) lt 2
2819 monitor-uri /site_alive
2820 monitor fail if site_dead
2821
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002822 See also : "monitor-net", "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002823
2824
2825monitor-net <source>
2826 Declare a source network which is limited to monitor requests
2827 May be used in sections : defaults | frontend | listen | backend
2828 yes | yes | yes | no
2829 Arguments :
2830 <source> is the source IPv4 address or network which will only be able to
2831 get monitor responses to any request. It can be either an IPv4
2832 address, a host name, or an address followed by a slash ('/')
2833 followed by a mask.
2834
2835 In TCP mode, any connection coming from a source matching <source> will cause
2836 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002837 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01002838 forwarding the connection to a remote server.
2839
2840 In HTTP mode, a connection coming from a source matching <source> will be
2841 accepted, the following response will be sent without waiting for a request,
2842 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
2843 enough for any front-end HTTP probe to detect that the service is UP and
Willy Tarreau82569f92012-09-27 23:48:56 +02002844 running without forwarding the request to a backend server. Note that this
2845 response is sent in raw format, without any transformation. This is important
2846 as it means that it will not be SSL-encrypted on SSL listeners.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002847
Willy Tarreau82569f92012-09-27 23:48:56 +02002848 Monitor requests are processed very early, just after tcp-request connection
2849 ACLs which are the only ones able to block them. These connections are short
2850 lived and never wait for any data from the client. They cannot be logged, and
2851 it is the intended purpose. They are only used to report HAProxy's health to
2852 an upper component, nothing more. Please note that "monitor fail" rules do
2853 not apply to connections intercepted by "monitor-net".
Willy Tarreau2769aa02007-12-27 18:26:09 +01002854
Willy Tarreau95cd2832010-03-04 23:36:33 +01002855 Last, please note that only one "monitor-net" statement can be specified in
2856 a frontend. If more than one is found, only the last one will be considered.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002857
Willy Tarreau2769aa02007-12-27 18:26:09 +01002858 Example :
2859 # addresses .252 and .253 are just probing us.
2860 frontend www
2861 monitor-net 192.168.0.252/31
2862
2863 See also : "monitor fail", "monitor-uri"
2864
2865
2866monitor-uri <uri>
2867 Intercept a URI used by external components' monitor requests
2868 May be used in sections : defaults | frontend | listen | backend
2869 yes | yes | yes | no
2870 Arguments :
2871 <uri> is the exact URI which we want to intercept to return HAProxy's
2872 health status instead of forwarding the request.
2873
2874 When an HTTP request referencing <uri> will be received on a frontend,
2875 HAProxy will not forward it nor log it, but instead will return either
2876 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
2877 conditions defined with "monitor fail". This is normally enough for any
2878 front-end HTTP probe to detect that the service is UP and running without
2879 forwarding the request to a backend server. Note that the HTTP method, the
2880 version and all headers are ignored, but the request must at least be valid
2881 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
2882
2883 Monitor requests are processed very early. It is not possible to block nor
2884 divert them using ACLs. They cannot be logged either, and it is the intended
2885 purpose. They are only used to report HAProxy's health to an upper component,
2886 nothing more. However, it is possible to add any number of conditions using
2887 "monitor fail" and ACLs so that the result can be adjusted to whatever check
2888 can be imagined (most often the number of available servers in a backend).
2889
2890 Example :
2891 # Use /haproxy_test to report haproxy's status
2892 frontend www
2893 mode http
2894 monitor-uri /haproxy_test
2895
2896 See also : "monitor fail", "monitor-net"
2897
Willy Tarreau0ba27502007-12-24 16:55:16 +01002898
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002899option abortonclose
2900no option abortonclose
2901 Enable or disable early dropping of aborted requests pending in queues.
2902 May be used in sections : defaults | frontend | listen | backend
2903 yes | no | yes | yes
2904 Arguments : none
2905
2906 In presence of very high loads, the servers will take some time to respond.
2907 The per-instance connection queue will inflate, and the response time will
2908 increase respective to the size of the queue times the average per-session
2909 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01002910 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002911 the queue, and slowing down other users, and the servers as well, because the
2912 request will eventually be served, then aborted at the first error
2913 encountered while delivering the response.
2914
2915 As there is no way to distinguish between a full STOP and a simple output
2916 close on the client side, HTTP agents should be conservative and consider
2917 that the client might only have closed its output channel while waiting for
2918 the response. However, this introduces risks of congestion when lots of users
2919 do the same, and is completely useless nowadays because probably no client at
2920 all will close the session while waiting for the response. Some HTTP agents
Willy Tarreaud72758d2010-01-12 10:42:19 +01002921 support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002922 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01002923 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002924 of being the single component to break rare but valid traffic is extremely
2925 low, which adds to the temptation to be able to abort a session early while
2926 still not served and not pollute the servers.
2927
2928 In HAProxy, the user can choose the desired behaviour using the option
2929 "abortonclose". By default (without the option) the behaviour is HTTP
2930 compliant and aborted requests will be served. But when the option is
2931 specified, a session with an incoming channel closed will be aborted while
2932 it is still possible, either pending in the queue for a connection slot, or
2933 during the connection establishment if the server has not yet acknowledged
2934 the connection request. This considerably reduces the queue size and the load
2935 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01002936 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002937
2938 If this option has been enabled in a "defaults" section, it can be disabled
2939 in a specific instance by prepending the "no" keyword before it.
2940
2941 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
2942
2943
Willy Tarreau4076a152009-04-02 15:18:36 +02002944option accept-invalid-http-request
2945no option accept-invalid-http-request
2946 Enable or disable relaxing of HTTP request parsing
2947 May be used in sections : defaults | frontend | listen | backend
2948 yes | yes | yes | no
2949 Arguments : none
2950
2951 By default, HAProxy complies with RFC2616 in terms of message parsing. This
2952 means that invalid characters in header names are not permitted and cause an
2953 error to be returned to the client. This is the desired behaviour as such
2954 forbidden characters are essentially used to build attacks exploiting server
2955 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
2956 server will emit invalid header names for whatever reason (configuration,
2957 implementation) and the issue will not be immediately fixed. In such a case,
2958 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau422246e2012-01-07 23:54:13 +01002959 even if that does not make sense, by specifying this option. Similarly, the
2960 list of characters allowed to appear in a URI is well defined by RFC3986, and
2961 chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
2962 ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
2963 not allowed at all. Haproxy always blocks a number of them (0..32, 127). The
2964 remaining ones are blocked by default unless this option is enabled.
Willy Tarreau4076a152009-04-02 15:18:36 +02002965
2966 This option should never be enabled by default as it hides application bugs
2967 and open security breaches. It should only be deployed after a problem has
2968 been confirmed.
2969
2970 When this option is enabled, erroneous header names will still be accepted in
2971 requests, but the complete request will be captured in order to permit later
Willy Tarreau422246e2012-01-07 23:54:13 +01002972 analysis using the "show errors" request on the UNIX stats socket. Similarly,
2973 requests containing invalid chars in the URI part will be logged. Doing this
Willy Tarreau4076a152009-04-02 15:18:36 +02002974 also helps confirming that the issue has been solved.
2975
2976 If this option has been enabled in a "defaults" section, it can be disabled
2977 in a specific instance by prepending the "no" keyword before it.
2978
2979 See also : "option accept-invalid-http-response" and "show errors" on the
2980 stats socket.
2981
2982
2983option accept-invalid-http-response
2984no option accept-invalid-http-response
2985 Enable or disable relaxing of HTTP response parsing
2986 May be used in sections : defaults | frontend | listen | backend
2987 yes | no | yes | yes
2988 Arguments : none
2989
2990 By default, HAProxy complies with RFC2616 in terms of message parsing. This
2991 means that invalid characters in header names are not permitted and cause an
2992 error to be returned to the client. This is the desired behaviour as such
2993 forbidden characters are essentially used to build attacks exploiting server
2994 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
2995 server will emit invalid header names for whatever reason (configuration,
2996 implementation) and the issue will not be immediately fixed. In such a case,
2997 it is possible to relax HAProxy's header name parser to accept any character
2998 even if that does not make sense, by specifying this option.
2999
3000 This option should never be enabled by default as it hides application bugs
3001 and open security breaches. It should only be deployed after a problem has
3002 been confirmed.
3003
3004 When this option is enabled, erroneous header names will still be accepted in
3005 responses, but the complete response will be captured in order to permit
3006 later analysis using the "show errors" request on the UNIX stats socket.
3007 Doing this also helps confirming that the issue has been solved.
3008
3009 If this option has been enabled in a "defaults" section, it can be disabled
3010 in a specific instance by prepending the "no" keyword before it.
3011
3012 See also : "option accept-invalid-http-request" and "show errors" on the
3013 stats socket.
3014
3015
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003016option allbackups
3017no option allbackups
3018 Use either all backup servers at a time or only the first one
3019 May be used in sections : defaults | frontend | listen | backend
3020 yes | no | yes | yes
3021 Arguments : none
3022
3023 By default, the first operational backup server gets all traffic when normal
3024 servers are all down. Sometimes, it may be preferred to use multiple backups
3025 at once, because one will not be enough. When "option allbackups" is enabled,
3026 the load balancing will be performed among all backup servers when all normal
3027 ones are unavailable. The same load balancing algorithm will be used and the
3028 servers' weights will be respected. Thus, there will not be any priority
3029 order between the backup servers anymore.
3030
3031 This option is mostly used with static server farms dedicated to return a
3032 "sorry" page when an application is completely offline.
3033
3034 If this option has been enabled in a "defaults" section, it can be disabled
3035 in a specific instance by prepending the "no" keyword before it.
3036
3037
3038option checkcache
3039no option checkcache
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003040 Analyze all server responses and block requests with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003041 May be used in sections : defaults | frontend | listen | backend
3042 yes | no | yes | yes
3043 Arguments : none
3044
3045 Some high-level frameworks set application cookies everywhere and do not
3046 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003047 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003048 high risk of session crossing or stealing between users traversing the same
3049 caches. In some situations, it is better to block the response than to let
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02003050 some sensitive session information go in the wild.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003051
3052 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003053 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01003054 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003055 response to check if there's a risk of caching a cookie on a client-side
3056 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01003057 to the client are :
3058 - all those without "Set-Cookie" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003059 - all those with a return code other than 200, 203, 206, 300, 301, 410,
Willy Tarreau198a7442008-01-17 12:05:32 +01003060 provided that the server has not set a "Cache-control: public" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003061 - all those that come from a POST request, provided that the server has not
3062 set a 'Cache-Control: public' header ;
3063 - those with a 'Pragma: no-cache' header
3064 - those with a 'Cache-control: private' header
3065 - those with a 'Cache-control: no-store' header
3066 - those with a 'Cache-control: max-age=0' header
3067 - those with a 'Cache-control: s-maxage=0' header
3068 - those with a 'Cache-control: no-cache' header
3069 - those with a 'Cache-control: no-cache="set-cookie"' header
3070 - those with a 'Cache-control: no-cache="set-cookie,' header
3071 (allowing other fields after set-cookie)
3072
3073 If a response doesn't respect these requirements, then it will be blocked
Willy Tarreau198a7442008-01-17 12:05:32 +01003074 just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003075 The session state shows "PH--" meaning that the proxy blocked the response
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003076 during headers processing. Additionally, an alert will be sent in the logs so
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003077 that admins are informed that there's something to be fixed.
3078
3079 Due to the high impact on the application, the application should be tested
3080 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003081 good practice to always activate it during tests, even if it is not used in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003082 production, as it will report potentially dangerous application behaviours.
3083
3084 If this option has been enabled in a "defaults" section, it can be disabled
3085 in a specific instance by prepending the "no" keyword before it.
3086
3087
3088option clitcpka
3089no option clitcpka
3090 Enable or disable the sending of TCP keepalive packets on the client side
3091 May be used in sections : defaults | frontend | listen | backend
3092 yes | yes | yes | no
3093 Arguments : none
3094
3095 When there is a firewall or any session-aware component between a client and
3096 a server, and when the protocol involves very long sessions with long idle
3097 periods (eg: remote desktops), there is a risk that one of the intermediate
3098 components decides to expire a session which has remained idle for too long.
3099
3100 Enabling socket-level TCP keep-alives makes the system regularly send packets
3101 to the other end of the connection, leaving it active. The delay between
3102 keep-alive probes is controlled by the system only and depends both on the
3103 operating system and its tuning parameters.
3104
3105 It is important to understand that keep-alive packets are neither emitted nor
3106 received at the application level. It is only the network stacks which sees
3107 them. For this reason, even if one side of the proxy already uses keep-alives
3108 to maintain its connection alive, those keep-alive packets will not be
3109 forwarded to the other side of the proxy.
3110
3111 Please note that this has nothing to do with HTTP keep-alive.
3112
3113 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
3114 client side of a connection, which should help when session expirations are
3115 noticed between HAProxy and a client.
3116
3117 If this option has been enabled in a "defaults" section, it can be disabled
3118 in a specific instance by prepending the "no" keyword before it.
3119
3120 See also : "option srvtcpka", "option tcpka"
3121
3122
Willy Tarreau0ba27502007-12-24 16:55:16 +01003123option contstats
3124 Enable continuous traffic statistics updates
3125 May be used in sections : defaults | frontend | listen | backend
3126 yes | yes | yes | no
3127 Arguments : none
3128
3129 By default, counters used for statistics calculation are incremented
3130 only when a session finishes. It works quite well when serving small
3131 objects, but with big ones (for example large images or archives) or
3132 with A/V streaming, a graph generated from haproxy counters looks like
3133 a hedgehog. With this option enabled counters get incremented continuously,
3134 during a whole session. Recounting touches a hotpath directly so
3135 it is not enabled by default, as it has small performance impact (~0.5%).
3136
3137
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003138option dontlog-normal
3139no option dontlog-normal
3140 Enable or disable logging of normal, successful connections
3141 May be used in sections : defaults | frontend | listen | backend
3142 yes | yes | yes | no
3143 Arguments : none
3144
3145 There are large sites dealing with several thousand connections per second
3146 and for which logging is a major pain. Some of them are even forced to turn
3147 logs off and cannot debug production issues. Setting this option ensures that
3148 normal connections, those which experience no error, no timeout, no retry nor
3149 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
3150 mode, the response status code is checked and return codes 5xx will still be
3151 logged.
3152
3153 It is strongly discouraged to use this option as most of the time, the key to
3154 complex issues is in the normal logs which will not be logged here. If you
3155 need to separate logs, see the "log-separate-errors" option instead.
3156
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003157 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003158 logging.
3159
3160
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003161option dontlognull
3162no option dontlognull
3163 Enable or disable logging of null connections
3164 May be used in sections : defaults | frontend | listen | backend
3165 yes | yes | yes | no
3166 Arguments : none
3167
3168 In certain environments, there are components which will regularly connect to
3169 various systems to ensure that they are still alive. It can be the case from
3170 another load balancer as well as from monitoring systems. By default, even a
3171 simple port probe or scan will produce a log. If those connections pollute
3172 the logs too much, it is possible to enable option "dontlognull" to indicate
3173 that a connection on which no data has been transferred will not be logged,
3174 which typically corresponds to those probes.
3175
3176 It is generally recommended not to use this option in uncontrolled
3177 environments (eg: internet), otherwise scans and other malicious activities
3178 would not be logged.
3179
3180 If this option has been enabled in a "defaults" section, it can be disabled
3181 in a specific instance by prepending the "no" keyword before it.
3182
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003183 See also : "log", "monitor-net", "monitor-uri" and section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003184
3185
3186option forceclose
3187no option forceclose
3188 Enable or disable active connection closing after response is transferred.
3189 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaua31e5df2009-12-30 01:10:35 +01003190 yes | yes | yes | yes
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003191 Arguments : none
3192
3193 Some HTTP servers do not necessarily close the connections when they receive
3194 the "Connection: close" set by "option httpclose", and if the client does not
3195 close either, then the connection remains open till the timeout expires. This
3196 causes high number of simultaneous connections on the servers and shows high
3197 global session times in the logs.
3198
3199 When this happens, it is possible to use "option forceclose". It will
Willy Tarreau82eeaf22009-12-29 12:09:05 +01003200 actively close the outgoing server channel as soon as the server has finished
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003201 to respond. This option implicitly enables the "httpclose" option. Note that
3202 this option also enables the parsing of the full request and response, which
3203 means we can close the connection to the server very quickly, releasing some
3204 resources earlier than with httpclose.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003205
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003206 This option may also be combined with "option http-pretend-keepalive", which
3207 will disable sending of the "Connection: close" header, but will still cause
3208 the connection to be closed once the whole response is received.
3209
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003210 If this option has been enabled in a "defaults" section, it can be disabled
3211 in a specific instance by prepending the "no" keyword before it.
3212
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003213 See also : "option httpclose" and "option http-pretend-keepalive"
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003214
3215
Willy Tarreau87cf5142011-08-19 22:57:24 +02003216option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003217 Enable insertion of the X-Forwarded-For header to requests sent to servers
3218 May be used in sections : defaults | frontend | listen | backend
3219 yes | yes | yes | yes
3220 Arguments :
3221 <network> is an optional argument used to disable this option for sources
3222 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02003223 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01003224 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003225
3226 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
3227 their client address. This is sometimes annoying when the client's IP address
3228 is expected in server logs. To solve this problem, the well-known HTTP header
3229 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
3230 This header contains a value representing the client's IP address. Since this
3231 header is always appended at the end of the existing header list, the server
3232 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02003233 the server's manual to find how to enable use of this standard header. Note
3234 that only the last occurrence of the header must be used, since it is really
3235 possible that the client has already brought one.
3236
Willy Tarreaud72758d2010-01-12 10:42:19 +01003237 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02003238 the default "X-Forwarded-For". This can be useful where you might already
Willy Tarreaud72758d2010-01-12 10:42:19 +01003239 have a "X-Forwarded-For" header from a different application (eg: stunnel),
3240 and you need preserve it. Also if your backend server doesn't use the
Ross Westaf72a1d2008-08-03 10:51:45 +02003241 "X-Forwarded-For" header and requires different one (eg: Zeus Web Servers
3242 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01003243
3244 Sometimes, a same HAProxy instance may be shared between a direct client
3245 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
3246 used to decrypt HTTPS traffic). It is possible to disable the addition of the
3247 header for a known source address or network by adding the "except" keyword
3248 followed by the network address. In this case, any source IP matching the
3249 network will not cause an addition of this header. Most common uses are with
3250 private networks or 127.0.0.1.
3251
Willy Tarreau87cf5142011-08-19 22:57:24 +02003252 Alternatively, the keyword "if-none" states that the header will only be
3253 added if it is not present. This should only be used in perfectly trusted
3254 environment, as this might cause a security issue if headers reaching haproxy
3255 are under the control of the end-user.
3256
Willy Tarreauc27debf2008-01-06 08:57:02 +01003257 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02003258 least one of them uses it, the header will be added. Note that the backend's
3259 setting of the header subargument takes precedence over the frontend's if
Willy Tarreau87cf5142011-08-19 22:57:24 +02003260 both are defined. In the case of the "if-none" argument, if at least one of
3261 the frontend or the backend does not specify it, it wants the addition to be
3262 mandatory, so it wins.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003263
Willy Tarreau87cf5142011-08-19 22:57:24 +02003264 It is important to note that by default, HAProxy works in tunnel mode and
3265 only inspects the first request of a connection, meaning that only the first
3266 request will have the header appended, which is certainly not what you want.
3267 In order to fix this, ensure that any of the "httpclose", "forceclose" or
3268 "http-server-close" options is set when using this option.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003269
Ross Westaf72a1d2008-08-03 10:51:45 +02003270 Examples :
Willy Tarreauc27debf2008-01-06 08:57:02 +01003271 # Public HTTP address also used by stunnel on the same machine
3272 frontend www
3273 mode http
3274 option forwardfor except 127.0.0.1 # stunnel already adds the header
3275
Ross Westaf72a1d2008-08-03 10:51:45 +02003276 # Those servers want the IP Address in X-Client
3277 backend www
3278 mode http
3279 option forwardfor header X-Client
3280
Willy Tarreau87cf5142011-08-19 22:57:24 +02003281 See also : "option httpclose", "option http-server-close",
3282 "option forceclose"
Willy Tarreauc27debf2008-01-06 08:57:02 +01003283
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003284
Willy Tarreau96e31212011-05-30 18:10:30 +02003285option http-no-delay
3286no option http-no-delay
3287 Instruct the system to favor low interactive delays over performance in HTTP
3288 May be used in sections : defaults | frontend | listen | backend
3289 yes | yes | yes | yes
3290 Arguments : none
3291
3292 In HTTP, each payload is unidirectional and has no notion of interactivity.
3293 Any agent is expected to queue data somewhat for a reasonably low delay.
3294 There are some very rare server-to-server applications that abuse the HTTP
3295 protocol and expect the payload phase to be highly interactive, with many
3296 interleaved data chunks in both directions within a single request. This is
3297 absolutely not supported by the HTTP specification and will not work across
3298 most proxies or servers. When such applications attempt to do this through
3299 haproxy, it works but they will experience high delays due to the network
3300 optimizations which favor performance by instructing the system to wait for
3301 enough data to be available in order to only send full packets. Typical
3302 delays are around 200 ms per round trip. Note that this only happens with
3303 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
3304 affected.
3305
3306 When "option http-no-delay" is present in either the frontend or the backend
3307 used by a connection, all such optimizations will be disabled in order to
3308 make the exchanges as fast as possible. Of course this offers no guarantee on
3309 the functionality, as it may break at any other place. But if it works via
3310 HAProxy, it will work as fast as possible. This option should never be used
3311 by default, and should never be used at all unless such a buggy application
3312 is discovered. The impact of using this option is an increase of bandwidth
3313 usage and CPU usage, which may significantly lower performance in high
3314 latency environments.
3315
3316
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003317option http-pretend-keepalive
3318no option http-pretend-keepalive
3319 Define whether haproxy will announce keepalive to the server or not
3320 May be used in sections : defaults | frontend | listen | backend
3321 yes | yes | yes | yes
3322 Arguments : none
3323
3324 When running with "option http-server-close" or "option forceclose", haproxy
3325 adds a "Connection: close" header to the request forwarded to the server.
3326 Unfortunately, when some servers see this header, they automatically refrain
3327 from using the chunked encoding for responses of unknown length, while this
3328 is totally unrelated. The immediate effect is that this prevents haproxy from
3329 maintaining the client connection alive. A second effect is that a client or
3330 a cache could receive an incomplete response without being aware of it, and
3331 consider the response complete.
3332
3333 By setting "option http-pretend-keepalive", haproxy will make the server
3334 believe it will keep the connection alive. The server will then not fall back
3335 to the abnormal undesired above. When haproxy gets the whole response, it
3336 will close the connection with the server just as it would do with the
3337 "forceclose" option. That way the client gets a normal response and the
3338 connection is correctly closed on the server side.
3339
3340 It is recommended not to enable this option by default, because most servers
3341 will more efficiently close the connection themselves after the last packet,
3342 and release its buffers slightly earlier. Also, the added packet on the
3343 network could slightly reduce the overall peak performance. However it is
3344 worth noting that when this option is enabled, haproxy will have slightly
3345 less work to do. So if haproxy is the bottleneck on the whole architecture,
3346 enabling this option might save a few CPU cycles.
3347
3348 This option may be set both in a frontend and in a backend. It is enabled if
3349 at least one of the frontend or backend holding a connection has it enabled.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003350 This option may be combined with "option httpclose", which will cause
Willy Tarreau22a95342010-09-29 14:31:41 +02003351 keepalive to be announced to the server and close to be announced to the
3352 client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003353
3354 If this option has been enabled in a "defaults" section, it can be disabled
3355 in a specific instance by prepending the "no" keyword before it.
3356
3357 See also : "option forceclose" and "option http-server-close"
3358
Willy Tarreauc27debf2008-01-06 08:57:02 +01003359
Willy Tarreaub608feb2010-01-02 22:47:18 +01003360option http-server-close
3361no option http-server-close
3362 Enable or disable HTTP connection closing on the server side
3363 May be used in sections : defaults | frontend | listen | backend
3364 yes | yes | yes | yes
3365 Arguments : none
3366
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003367 By default, when a client communicates with a server, HAProxy will only
3368 analyze, log, and process the first request of each connection. Setting
3369 "option http-server-close" enables HTTP connection-close mode on the server
3370 side while keeping the ability to support HTTP keep-alive and pipelining on
3371 the client side. This provides the lowest latency on the client side (slow
3372 network) and the fastest session reuse on the server side to save server
3373 resources, similarly to "option forceclose". It also permits non-keepalive
3374 capable servers to be served in keep-alive mode to the clients if they
3375 conform to the requirements of RFC2616. Please note that some servers do not
3376 always conform to those requirements when they see "Connection: close" in the
3377 request. The effect will be that keep-alive will never be used. A workaround
3378 consists in enabling "option http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003379
3380 At the moment, logs will not indicate whether requests came from the same
3381 session or not. The accept date reported in the logs corresponds to the end
3382 of the previous request, and the request time corresponds to the time spent
3383 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01003384 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
3385 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01003386
3387 This option may be set both in a frontend and in a backend. It is enabled if
3388 at least one of the frontend or backend holding a connection has it enabled.
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003389 It is worth noting that "option forceclose" has precedence over "option
3390 http-server-close" and that combining "http-server-close" with "httpclose"
3391 basically achieve the same result as "forceclose".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003392
3393 If this option has been enabled in a "defaults" section, it can be disabled
3394 in a specific instance by prepending the "no" keyword before it.
3395
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003396 See also : "option forceclose", "option http-pretend-keepalive",
3397 "option httpclose" and "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003398
3399
Willy Tarreau88d349d2010-01-25 12:15:43 +01003400option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01003401no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01003402 Make use of non-standard Proxy-Connection header instead of Connection
3403 May be used in sections : defaults | frontend | listen | backend
3404 yes | yes | yes | no
3405 Arguments : none
3406
3407 While RFC2616 explicitly states that HTTP/1.1 agents must use the
3408 Connection header to indicate their wish of persistent or non-persistent
3409 connections, both browsers and proxies ignore this header for proxied
3410 connections and make use of the undocumented, non-standard Proxy-Connection
3411 header instead. The issue begins when trying to put a load balancer between
3412 browsers and such proxies, because there will be a difference between what
3413 haproxy understands and what the client and the proxy agree on.
3414
3415 By setting this option in a frontend, haproxy can automatically switch to use
3416 that non-standard header if it sees proxied requests. A proxied request is
3417 defined here as one where the URI begins with neither a '/' nor a '*'. The
3418 choice of header only affects requests passing through proxies making use of
3419 one of the "httpclose", "forceclose" and "http-server-close" options. Note
3420 that this option can only be specified in a frontend and will affect the
3421 request along its whole life.
3422
Willy Tarreau844a7e72010-01-31 21:46:18 +01003423 Also, when this option is set, a request which requires authentication will
3424 automatically switch to use proxy authentication headers if it is itself a
3425 proxied request. That makes it possible to check or enforce authentication in
3426 front of an existing proxy.
3427
Willy Tarreau88d349d2010-01-25 12:15:43 +01003428 This option should normally never be used, except in front of a proxy.
3429
3430 See also : "option httpclose", "option forceclose" and "option
3431 http-server-close".
3432
3433
Willy Tarreaud63335a2010-02-26 12:56:52 +01003434option httpchk
3435option httpchk <uri>
3436option httpchk <method> <uri>
3437option httpchk <method> <uri> <version>
3438 Enable HTTP protocol to check on the servers health
3439 May be used in sections : defaults | frontend | listen | backend
3440 yes | no | yes | yes
3441 Arguments :
3442 <method> is the optional HTTP method used with the requests. When not set,
3443 the "OPTIONS" method is used, as it generally requires low server
3444 processing and is easy to filter out from the logs. Any method
3445 may be used, though it is not recommended to invent non-standard
3446 ones.
3447
3448 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
3449 which is accessible by default on almost any server, but may be
3450 changed to any other URI. Query strings are permitted.
3451
3452 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
3453 but some servers might behave incorrectly in HTTP 1.0, so turning
3454 it to HTTP/1.1 may sometimes help. Note that the Host field is
3455 mandatory in HTTP/1.1, and as a trick, it is possible to pass it
3456 after "\r\n" following the version string.
3457
3458 By default, server health checks only consist in trying to establish a TCP
3459 connection. When "option httpchk" is specified, a complete HTTP request is
3460 sent once the TCP connection is established, and responses 2xx and 3xx are
3461 considered valid, while all other ones indicate a server failure, including
3462 the lack of any response.
3463
3464 The port and interval are specified in the server configuration.
3465
3466 This option does not necessarily require an HTTP backend, it also works with
3467 plain TCP backends. This is particularly useful to check simple scripts bound
3468 to some dedicated ports using the inetd daemon.
3469
3470 Examples :
3471 # Relay HTTPS traffic to Apache instance and check service availability
3472 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
3473 backend https_relay
3474 mode tcp
3475 option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www
3476 server apache1 192.168.1.1:443 check port 80
3477
3478 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003479 "option pgsql-check", "http-check" and the "check", "port" and
3480 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01003481
3482
Willy Tarreauc27debf2008-01-06 08:57:02 +01003483option httpclose
3484no option httpclose
3485 Enable or disable passive HTTP connection closing
3486 May be used in sections : defaults | frontend | listen | backend
3487 yes | yes | yes | yes
3488 Arguments : none
3489
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003490 By default, when a client communicates with a server, HAProxy will only
3491 analyze, log, and process the first request of each connection. If "option
3492 httpclose" is set, it will check if a "Connection: close" header is already
3493 set in each direction, and will add one if missing. Each end should react to
3494 this by actively closing the TCP connection after each transfer, thus
3495 resulting in a switch to the HTTP close mode. Any "Connection" header
3496 different from "close" will also be removed.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003497
3498 It seldom happens that some servers incorrectly ignore this header and do not
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003499 close the connection even though they reply "Connection: close". For this
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003500 reason, they are not compatible with older HTTP 1.0 browsers. If this happens
3501 it is possible to use the "option forceclose" which actively closes the
3502 request connection once the server responds. Option "forceclose" also
3503 releases the server connection earlier because it does not have to wait for
3504 the client to acknowledge it.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003505
3506 This option may be set both in a frontend and in a backend. It is enabled if
3507 at least one of the frontend or backend holding a connection has it enabled.
3508 If "option forceclose" is specified too, it has precedence over "httpclose".
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003509 If "option http-server-close" is enabled at the same time as "httpclose", it
3510 basically achieves the same result as "option forceclose".
Willy Tarreauc27debf2008-01-06 08:57:02 +01003511
3512 If this option has been enabled in a "defaults" section, it can be disabled
3513 in a specific instance by prepending the "no" keyword before it.
3514
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003515 See also : "option forceclose", "option http-server-close" and
3516 "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01003517
3518
Emeric Brun3a058f32009-06-30 18:26:00 +02003519option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003520 Enable logging of HTTP request, session state and timers
3521 May be used in sections : defaults | frontend | listen | backend
3522 yes | yes | yes | yes
Emeric Brun3a058f32009-06-30 18:26:00 +02003523 Arguments :
3524 clf if the "clf" argument is added, then the output format will be
3525 the CLF format instead of HAProxy's default HTTP format. You can
3526 use this when you need to feed HAProxy's logs through a specific
3527 log analyser which only support the CLF format and which is not
3528 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003529
3530 By default, the log output format is very poor, as it only contains the
3531 source and destination addresses, and the instance name. By specifying
3532 "option httplog", each log line turns into a much richer format including,
3533 but not limited to, the HTTP request, the connection timers, the session
3534 status, the connections numbers, the captured headers and cookies, the
3535 frontend, backend and server name, and of course the source address and
3536 ports.
3537
3538 This option may be set either in the frontend or the backend.
3539
Emeric Brun3a058f32009-06-30 18:26:00 +02003540 If this option has been enabled in a "defaults" section, it can be disabled
3541 in a specific instance by prepending the "no" keyword before it. Specifying
3542 only "option httplog" will automatically clear the 'clf' mode if it was set
3543 by default.
3544
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003545 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003546
Willy Tarreau55165fe2009-05-10 12:02:55 +02003547
3548option http_proxy
3549no option http_proxy
3550 Enable or disable plain HTTP proxy mode
3551 May be used in sections : defaults | frontend | listen | backend
3552 yes | yes | yes | yes
3553 Arguments : none
3554
3555 It sometimes happens that people need a pure HTTP proxy which understands
3556 basic proxy requests without caching nor any fancy feature. In this case,
3557 it may be worth setting up an HAProxy instance with the "option http_proxy"
3558 set. In this mode, no server is declared, and the connection is forwarded to
3559 the IP address and port found in the URL after the "http://" scheme.
3560
3561 No host address resolution is performed, so this only works when pure IP
3562 addresses are passed. Since this option's usage perimeter is rather limited,
3563 it will probably be used only by experts who know they need exactly it. Last,
3564 if the clients are susceptible of sending keep-alive requests, it will be
Cyril Bonté2409e682010-12-14 22:47:51 +01003565 needed to add "option httpclose" to ensure that all requests will correctly
Willy Tarreau55165fe2009-05-10 12:02:55 +02003566 be analyzed.
3567
3568 If this option has been enabled in a "defaults" section, it can be disabled
3569 in a specific instance by prepending the "no" keyword before it.
3570
3571 Example :
3572 # this backend understands HTTP proxy requests and forwards them directly.
3573 backend direct_forward
3574 option httpclose
3575 option http_proxy
3576
3577 See also : "option httpclose"
3578
Willy Tarreau211ad242009-10-03 21:45:07 +02003579
Jamie Gloudon801a0a32012-08-25 00:18:33 -04003580option independent-streams
3581no option independent-streams
3582 Enable or disable independent timeout processing for both directions
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02003583 May be used in sections : defaults | frontend | listen | backend
3584 yes | yes | yes | yes
3585 Arguments : none
3586
3587 By default, when data is sent over a socket, both the write timeout and the
3588 read timeout for that socket are refreshed, because we consider that there is
3589 activity on that socket, and we have no other means of guessing if we should
3590 receive data or not.
3591
3592 While this default behaviour is desirable for almost all applications, there
3593 exists a situation where it is desirable to disable it, and only refresh the
3594 read timeout if there are incoming data. This happens on sessions with large
3595 timeouts and low amounts of exchanged data such as telnet session. If the
3596 server suddenly disappears, the output data accumulates in the system's
3597 socket buffers, both timeouts are correctly refreshed, and there is no way
3598 to know the server does not receive them, so we don't timeout. However, when
3599 the underlying protocol always echoes sent data, it would be enough by itself
3600 to detect the issue using the read timeout. Note that this problem does not
3601 happen with more verbose protocols because data won't accumulate long in the
3602 socket buffers.
3603
3604 When this option is set on the frontend, it will disable read timeout updates
3605 on data sent to the client. There probably is little use of this case. When
3606 the option is set on the backend, it will disable read timeout updates on
3607 data sent to the server. Doing so will typically break large HTTP posts from
3608 slow lines, so use it with caution.
3609
Jamie Gloudon801a0a32012-08-25 00:18:33 -04003610 Note: older versions used to call this setting "option independant-streams"
3611 with a spelling mistake. This spelling is still supported but
3612 deprecated.
3613
Willy Tarreauce887fd2012-05-12 12:50:00 +02003614 See also : "timeout client", "timeout server" and "timeout tunnel"
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02003615
3616
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02003617option ldap-check
3618 Use LDAPv3 health checks for server testing
3619 May be used in sections : defaults | frontend | listen | backend
3620 yes | no | yes | yes
3621 Arguments : none
3622
3623 It is possible to test that the server correctly talks LDAPv3 instead of just
3624 testing that it accepts the TCP connection. When this option is set, an
3625 LDAPv3 anonymous simple bind message is sent to the server, and the response
3626 is analyzed to find an LDAPv3 bind response message.
3627
3628 The server is considered valid only when the LDAP response contains success
3629 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
3630
3631 Logging of bind requests is server dependent see your documentation how to
3632 configure it.
3633
3634 Example :
3635 option ldap-check
3636
3637 See also : "option httpchk"
3638
3639
Willy Tarreau211ad242009-10-03 21:45:07 +02003640option log-health-checks
3641no option log-health-checks
3642 Enable or disable logging of health checks
3643 May be used in sections : defaults | frontend | listen | backend
3644 yes | no | yes | yes
3645 Arguments : none
3646
3647 Enable health checks logging so it possible to check for example what
3648 was happening before a server crash. Failed health check are logged if
3649 server is UP and succeeded health checks if server is DOWN, so the amount
3650 of additional information is limited.
3651
3652 If health check logging is enabled no health check status is printed
3653 when servers is set up UP/DOWN/ENABLED/DISABLED.
3654
3655 See also: "log" and section 8 about logging.
3656
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003657
3658option log-separate-errors
3659no option log-separate-errors
3660 Change log level for non-completely successful connections
3661 May be used in sections : defaults | frontend | listen | backend
3662 yes | yes | yes | no
3663 Arguments : none
3664
3665 Sometimes looking for errors in logs is not easy. This option makes haproxy
3666 raise the level of logs containing potentially interesting information such
3667 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
3668 level changes from "info" to "err". This makes it possible to log them
3669 separately to a different file with most syslog daemons. Be careful not to
3670 remove them from the original file, otherwise you would lose ordering which
3671 provides very important information.
3672
3673 Using this option, large sites dealing with several thousand connections per
3674 second may log normal traffic to a rotating buffer and only archive smaller
3675 error logs.
3676
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003677 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003678 logging.
3679
Willy Tarreauc27debf2008-01-06 08:57:02 +01003680
3681option logasap
3682no option logasap
3683 Enable or disable early logging of HTTP requests
3684 May be used in sections : defaults | frontend | listen | backend
3685 yes | yes | yes | no
3686 Arguments : none
3687
3688 By default, HTTP requests are logged upon termination so that the total
3689 transfer time and the number of bytes appear in the logs. When large objects
3690 are being transferred, it may take a while before the request appears in the
3691 logs. Using "option logasap", the request gets logged as soon as the server
3692 sends the complete headers. The only missing information in the logs will be
3693 the total number of bytes which will indicate everything except the amount
3694 of data transferred, and the total time which will not take the transfer
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003695 time into account. In such a situation, it's a good practice to capture the
Willy Tarreauc27debf2008-01-06 08:57:02 +01003696 "Content-Length" response header so that the logs at least indicate how many
3697 bytes are expected to be transferred.
3698
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003699 Examples :
3700 listen http_proxy 0.0.0.0:80
3701 mode http
3702 option httplog
3703 option logasap
3704 log 192.168.2.200 local3
3705
3706 >>> Feb 6 12:14:14 localhost \
3707 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
3708 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
3709 "GET /image.iso HTTP/1.0"
3710
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003711 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01003712 logging.
3713
3714
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003715option mysql-check [ user <username> ]
3716 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003717 May be used in sections : defaults | frontend | listen | backend
3718 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003719 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003720 <username> This is the username which will be used when connecting to MySQL
3721 server.
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003722
3723 If you specify a username, the check consists of sending two MySQL packet,
3724 one Client Authentication packet, and one QUIT packet, to correctly close
3725 MySQL session. We then parse the MySQL Handshake Initialisation packet and/or
3726 Error packet. It is a basic but useful test which does not produce error nor
3727 aborted connect on the server. However, it requires adding an authorization
3728 in the MySQL table, like this :
3729
3730 USE mysql;
3731 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
3732 FLUSH PRIVILEGES;
3733
3734 If you don't specify a username (it is deprecated and not recommended), the
3735 check only consists in parsing the Mysql Handshake Initialisation packet or
3736 Error packet, we don't send anything in this mode. It was reported that it
3737 can generate lockout if check is too frequent and/or if there is not enough
3738 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
3739 value as if a connection is established successfully within fewer than MySQL
3740 "max_connect_errors" attempts after a previous connection was interrupted,
3741 the error count for the host is cleared to zero. If HAProxy's server get
3742 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
3743
3744 Remember that this does not check database presence nor database consistency.
3745 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003746
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02003747 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003748
3749 Most often, an incoming MySQL server needs to see the client's IP address for
3750 various purposes, including IP privilege matching and connection logging.
3751 When possible, it is often wise to masquerade the client's IP address when
3752 connecting to the server using the "usesrc" argument of the "source" keyword,
3753 which requires the cttproxy feature to be compiled in, and the MySQL server
3754 to route the client via the machine hosting haproxy.
3755
3756 See also: "option httpchk"
3757
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003758option pgsql-check [ user <username> ]
3759 Use PostgreSQL health checks for server testing
3760 May be used in sections : defaults | frontend | listen | backend
3761 yes | no | yes | yes
3762 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003763 <username> This is the username which will be used when connecting to
3764 PostgreSQL server.
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003765
3766 The check sends a PostgreSQL StartupMessage and waits for either
3767 Authentication request or ErrorResponse message. It is a basic but useful
3768 test which does not produce error nor aborted connect on the server.
3769 This check is identical with the "mysql-check".
3770
3771 See also: "option httpchk"
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003772
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003773option nolinger
3774no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003775 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003776 May be used in sections: defaults | frontend | listen | backend
3777 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003778 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003779
3780 When clients or servers abort connections in a dirty way (eg: they are
3781 physically disconnected), the session timeouts triggers and the session is
3782 closed. But it will remain in FIN_WAIT1 state for some time in the system,
3783 using some resources and possibly limiting the ability to establish newer
3784 connections.
3785
3786 When this happens, it is possible to activate "option nolinger" which forces
3787 the system to immediately remove any socket's pending data on close. Thus,
3788 the session is instantly purged from the system's tables. This usually has
3789 side effects such as increased number of TCP resets due to old retransmits
3790 getting immediately rejected. Some firewalls may sometimes complain about
3791 this too.
3792
3793 For this reason, it is not recommended to use this option when not absolutely
3794 needed. You know that you need it when you have thousands of FIN_WAIT1
3795 sessions on your system (TIME_WAIT ones do not count).
3796
3797 This option may be used both on frontends and backends, depending on the side
3798 where it is required. Use it on the frontend for clients, and on the backend
3799 for servers.
3800
3801 If this option has been enabled in a "defaults" section, it can be disabled
3802 in a specific instance by prepending the "no" keyword before it.
3803
3804
Willy Tarreau55165fe2009-05-10 12:02:55 +02003805option originalto [ except <network> ] [ header <name> ]
3806 Enable insertion of the X-Original-To header to requests sent to servers
3807 May be used in sections : defaults | frontend | listen | backend
3808 yes | yes | yes | yes
3809 Arguments :
3810 <network> is an optional argument used to disable this option for sources
3811 matching <network>
3812 <name> an optional argument to specify a different "X-Original-To"
3813 header name.
3814
3815 Since HAProxy can work in transparent mode, every request from a client can
3816 be redirected to the proxy and HAProxy itself can proxy every request to a
3817 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
3818 be lost. This is annoying when you want access rules based on destination ip
3819 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
3820 added by HAProxy to all requests sent to the server. This header contains a
3821 value representing the original destination IP address. Since this must be
3822 configured to always use the last occurrence of this header only. Note that
3823 only the last occurrence of the header must be used, since it is really
3824 possible that the client has already brought one.
3825
3826 The keyword "header" may be used to supply a different header name to replace
3827 the default "X-Original-To". This can be useful where you might already
3828 have a "X-Original-To" header from a different application, and you need
3829 preserve it. Also if your backend server doesn't use the "X-Original-To"
3830 header and requires different one.
3831
3832 Sometimes, a same HAProxy instance may be shared between a direct client
3833 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
3834 used to decrypt HTTPS traffic). It is possible to disable the addition of the
3835 header for a known source address or network by adding the "except" keyword
3836 followed by the network address. In this case, any source IP matching the
3837 network will not cause an addition of this header. Most common uses are with
3838 private networks or 127.0.0.1.
3839
3840 This option may be specified either in the frontend or in the backend. If at
3841 least one of them uses it, the header will be added. Note that the backend's
3842 setting of the header subargument takes precedence over the frontend's if
3843 both are defined.
3844
Willy Tarreau87cf5142011-08-19 22:57:24 +02003845 It is important to note that by default, HAProxy works in tunnel mode and
3846 only inspects the first request of a connection, meaning that only the first
3847 request will have the header appended, which is certainly not what you want.
3848 In order to fix this, ensure that any of the "httpclose", "forceclose" or
3849 "http-server-close" options is set when using this option.
Willy Tarreau55165fe2009-05-10 12:02:55 +02003850
3851 Examples :
3852 # Original Destination address
3853 frontend www
3854 mode http
3855 option originalto except 127.0.0.1
3856
3857 # Those servers want the IP Address in X-Client-Dst
3858 backend www
3859 mode http
3860 option originalto header X-Client-Dst
3861
Willy Tarreau87cf5142011-08-19 22:57:24 +02003862 See also : "option httpclose", "option http-server-close",
3863 "option forceclose"
Willy Tarreau55165fe2009-05-10 12:02:55 +02003864
3865
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003866option persist
3867no option persist
3868 Enable or disable forced persistence on down servers
3869 May be used in sections: defaults | frontend | listen | backend
3870 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003871 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003872
3873 When an HTTP request reaches a backend with a cookie which references a dead
3874 server, by default it is redispatched to another server. It is possible to
3875 force the request to be sent to the dead server first using "option persist"
3876 if absolutely needed. A common use case is when servers are under extreme
3877 load and spend their time flapping. In this case, the users would still be
3878 directed to the server they opened the session on, in the hope they would be
3879 correctly served. It is recommended to use "option redispatch" in conjunction
3880 with this option so that in the event it would not be possible to connect to
3881 the server at all (server definitely dead), the client would finally be
3882 redirected to another valid server.
3883
3884 If this option has been enabled in a "defaults" section, it can be disabled
3885 in a specific instance by prepending the "no" keyword before it.
3886
Willy Tarreau4de91492010-01-22 19:10:05 +01003887 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003888
3889
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003890option redispatch
3891no option redispatch
3892 Enable or disable session redistribution in case of connection failure
3893 May be used in sections: defaults | frontend | listen | backend
3894 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003895 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003896
3897 In HTTP mode, if a server designated by a cookie is down, clients may
3898 definitely stick to it because they cannot flush the cookie, so they will not
3899 be able to access the service anymore.
3900
3901 Specifying "option redispatch" will allow the proxy to break their
3902 persistence and redistribute them to a working server.
3903
3904 It also allows to retry last connection to another server in case of multiple
3905 connection failures. Of course, it requires having "retries" set to a nonzero
3906 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01003907
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003908 This form is the preferred form, which replaces both the "redispatch" and
3909 "redisp" keywords.
3910
3911 If this option has been enabled in a "defaults" section, it can be disabled
3912 in a specific instance by prepending the "no" keyword before it.
3913
Willy Tarreau4de91492010-01-22 19:10:05 +01003914 See also : "redispatch", "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003915
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003916
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02003917option redis-check
3918 Use redis health checks for server testing
3919 May be used in sections : defaults | frontend | listen | backend
3920 yes | no | yes | yes
3921 Arguments : none
3922
3923 It is possible to test that the server correctly talks REDIS protocol instead
3924 of just testing that it accepts the TCP connection. When this option is set,
3925 a PING redis command is sent to the server, and the response is analyzed to
3926 find the "+PONG" response message.
3927
3928 Example :
3929 option redis-check
3930
3931 See also : "option httpchk"
3932
3933
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003934option smtpchk
3935option smtpchk <hello> <domain>
3936 Use SMTP health checks for server testing
3937 May be used in sections : defaults | frontend | listen | backend
3938 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01003939 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003940 <hello> is an optional argument. It is the "hello" command to use. It can
3941 be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other
3942 values will be turned into the default command ("HELO").
3943
3944 <domain> is the domain name to present to the server. It may only be
3945 specified (and is mandatory) if the hello command has been
3946 specified. By default, "localhost" is used.
3947
3948 When "option smtpchk" is set, the health checks will consist in TCP
3949 connections followed by an SMTP command. By default, this command is
3950 "HELO localhost". The server's return code is analyzed and only return codes
3951 starting with a "2" will be considered as valid. All other responses,
3952 including a lack of response will constitute an error and will indicate a
3953 dead server.
3954
3955 This test is meant to be used with SMTP servers or relays. Depending on the
3956 request, it is possible that some servers do not log each connection attempt,
3957 so you may want to experiment to improve the behaviour. Using telnet on port
3958 25 is often easier than adjusting the configuration.
3959
3960 Most often, an incoming SMTP server needs to see the client's IP address for
3961 various purposes, including spam filtering, anti-spoofing and logging. When
3962 possible, it is often wise to masquerade the client's IP address when
3963 connecting to the server using the "usesrc" argument of the "source" keyword,
3964 which requires the cttproxy feature to be compiled in.
3965
3966 Example :
3967 option smtpchk HELO mydomain.org
3968
3969 See also : "option httpchk", "source"
3970
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003971
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02003972option socket-stats
3973no option socket-stats
3974
3975 Enable or disable collecting & providing separate statistics for each socket.
3976 May be used in sections : defaults | frontend | listen | backend
3977 yes | yes | yes | no
3978
3979 Arguments : none
3980
3981
Willy Tarreauff4f82d2009-02-06 11:28:13 +01003982option splice-auto
3983no option splice-auto
3984 Enable or disable automatic kernel acceleration on sockets in both directions
3985 May be used in sections : defaults | frontend | listen | backend
3986 yes | yes | yes | yes
3987 Arguments : none
3988
3989 When this option is enabled either on a frontend or on a backend, haproxy
3990 will automatically evaluate the opportunity to use kernel tcp splicing to
3991 forward data between the client and the server, in either direction. Haproxy
3992 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003993 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01003994 are not much aggressive in order to limit excessive use of splicing. This
3995 option requires splicing to be enabled at compile time, and may be globally
3996 disabled with the global option "nosplice". Since splice uses pipes, using it
3997 requires that there are enough spare pipes.
3998
3999 Important note: kernel-based TCP splicing is a Linux-specific feature which
4000 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
4001 transfer data between sockets without copying these data to user-space, thus
4002 providing noticeable performance gains and CPU cycles savings. Since many
4003 early implementations are buggy, corrupt data and/or are inefficient, this
4004 feature is not enabled by default, and it should be used with extreme care.
4005 While it is not possible to detect the correctness of an implementation,
4006 2.6.29 is the first version offering a properly working implementation. In
4007 case of doubt, splicing may be globally disabled using the global "nosplice"
4008 keyword.
4009
4010 Example :
4011 option splice-auto
4012
4013 If this option has been enabled in a "defaults" section, it can be disabled
4014 in a specific instance by prepending the "no" keyword before it.
4015
4016 See also : "option splice-request", "option splice-response", and global
4017 options "nosplice" and "maxpipes"
4018
4019
4020option splice-request
4021no option splice-request
4022 Enable or disable automatic kernel acceleration on sockets for requests
4023 May be used in sections : defaults | frontend | listen | backend
4024 yes | yes | yes | yes
4025 Arguments : none
4026
4027 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004028 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004029 the client to the server. It might still use the recv/send scheme if there
4030 are no spare pipes left. This option requires splicing to be enabled at
4031 compile time, and may be globally disabled with the global option "nosplice".
4032 Since splice uses pipes, using it requires that there are enough spare pipes.
4033
4034 Important note: see "option splice-auto" for usage limitations.
4035
4036 Example :
4037 option splice-request
4038
4039 If this option has been enabled in a "defaults" section, it can be disabled
4040 in a specific instance by prepending the "no" keyword before it.
4041
4042 See also : "option splice-auto", "option splice-response", and global options
4043 "nosplice" and "maxpipes"
4044
4045
4046option splice-response
4047no option splice-response
4048 Enable or disable automatic kernel acceleration on sockets for responses
4049 May be used in sections : defaults | frontend | listen | backend
4050 yes | yes | yes | yes
4051 Arguments : none
4052
4053 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004054 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004055 the server to the client. It might still use the recv/send scheme if there
4056 are no spare pipes left. This option requires splicing to be enabled at
4057 compile time, and may be globally disabled with the global option "nosplice".
4058 Since splice uses pipes, using it requires that there are enough spare pipes.
4059
4060 Important note: see "option splice-auto" for usage limitations.
4061
4062 Example :
4063 option splice-response
4064
4065 If this option has been enabled in a "defaults" section, it can be disabled
4066 in a specific instance by prepending the "no" keyword before it.
4067
4068 See also : "option splice-auto", "option splice-request", and global options
4069 "nosplice" and "maxpipes"
4070
4071
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004072option srvtcpka
4073no option srvtcpka
4074 Enable or disable the sending of TCP keepalive packets on the server side
4075 May be used in sections : defaults | frontend | listen | backend
4076 yes | no | yes | yes
4077 Arguments : none
4078
4079 When there is a firewall or any session-aware component between a client and
4080 a server, and when the protocol involves very long sessions with long idle
4081 periods (eg: remote desktops), there is a risk that one of the intermediate
4082 components decides to expire a session which has remained idle for too long.
4083
4084 Enabling socket-level TCP keep-alives makes the system regularly send packets
4085 to the other end of the connection, leaving it active. The delay between
4086 keep-alive probes is controlled by the system only and depends both on the
4087 operating system and its tuning parameters.
4088
4089 It is important to understand that keep-alive packets are neither emitted nor
4090 received at the application level. It is only the network stacks which sees
4091 them. For this reason, even if one side of the proxy already uses keep-alives
4092 to maintain its connection alive, those keep-alive packets will not be
4093 forwarded to the other side of the proxy.
4094
4095 Please note that this has nothing to do with HTTP keep-alive.
4096
4097 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
4098 server side of a connection, which should help when session expirations are
4099 noticed between HAProxy and a server.
4100
4101 If this option has been enabled in a "defaults" section, it can be disabled
4102 in a specific instance by prepending the "no" keyword before it.
4103
4104 See also : "option clitcpka", "option tcpka"
4105
4106
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004107option ssl-hello-chk
4108 Use SSLv3 client hello health checks for server testing
4109 May be used in sections : defaults | frontend | listen | backend
4110 yes | no | yes | yes
4111 Arguments : none
4112
4113 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
4114 possible to test that the server correctly talks SSL instead of just testing
4115 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
4116 SSLv3 client hello messages are sent once the connection is established to
4117 the server, and the response is analyzed to find an SSL server hello message.
4118 The server is considered valid only when the response contains this server
4119 hello message.
4120
4121 All servers tested till there correctly reply to SSLv3 client hello messages,
4122 and most servers tested do not even log the requests containing only hello
4123 messages, which is appreciable.
4124
Willy Tarreau763a95b2012-10-04 23:15:39 +02004125 Note that this check works even when SSL support was not built into haproxy
4126 because it forges the SSL message. When SSL support is available, it is best
4127 to use native SSL health checks instead of this one.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004128
Willy Tarreau763a95b2012-10-04 23:15:39 +02004129 See also: "option httpchk", "check-ssl"
4130
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004131
Willy Tarreau9ea05a72009-06-14 12:07:01 +02004132option tcp-smart-accept
4133no option tcp-smart-accept
4134 Enable or disable the saving of one ACK packet during the accept sequence
4135 May be used in sections : defaults | frontend | listen | backend
4136 yes | yes | yes | no
4137 Arguments : none
4138
4139 When an HTTP connection request comes in, the system acknowledges it on
4140 behalf of HAProxy, then the client immediately sends its request, and the
4141 system acknowledges it too while it is notifying HAProxy about the new
4142 connection. HAProxy then reads the request and responds. This means that we
4143 have one TCP ACK sent by the system for nothing, because the request could
4144 very well be acknowledged by HAProxy when it sends its response.
4145
4146 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
4147 sending this useless ACK on platforms which support it (currently at least
4148 Linux). It must not cause any problem, because the system will send it anyway
4149 after 40 ms if the response takes more time than expected to come.
4150
4151 During complex network debugging sessions, it may be desirable to disable
4152 this optimization because delayed ACKs can make troubleshooting more complex
4153 when trying to identify where packets are delayed. It is then possible to
4154 fall back to normal behaviour by specifying "no option tcp-smart-accept".
4155
4156 It is also possible to force it for non-HTTP proxies by simply specifying
4157 "option tcp-smart-accept". For instance, it can make sense with some services
4158 such as SMTP where the server speaks first.
4159
4160 It is recommended to avoid forcing this option in a defaults section. In case
4161 of doubt, consider setting it back to automatic values by prepending the
4162 "default" keyword before it, or disabling it using the "no" keyword.
4163
Willy Tarreaud88edf22009-06-14 15:48:17 +02004164 See also : "option tcp-smart-connect"
4165
4166
4167option tcp-smart-connect
4168no option tcp-smart-connect
4169 Enable or disable the saving of one ACK packet during the connect sequence
4170 May be used in sections : defaults | frontend | listen | backend
4171 yes | no | yes | yes
4172 Arguments : none
4173
4174 On certain systems (at least Linux), HAProxy can ask the kernel not to
4175 immediately send an empty ACK upon a connection request, but to directly
4176 send the buffer request instead. This saves one packet on the network and
4177 thus boosts performance. It can also be useful for some servers, because they
4178 immediately get the request along with the incoming connection.
4179
4180 This feature is enabled when "option tcp-smart-connect" is set in a backend.
4181 It is not enabled by default because it makes network troubleshooting more
4182 complex.
4183
4184 It only makes sense to enable it with protocols where the client speaks first
4185 such as HTTP. In other situations, if there is no data to send in place of
4186 the ACK, a normal ACK is sent.
4187
4188 If this option has been enabled in a "defaults" section, it can be disabled
4189 in a specific instance by prepending the "no" keyword before it.
4190
4191 See also : "option tcp-smart-accept"
4192
Willy Tarreau9ea05a72009-06-14 12:07:01 +02004193
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004194option tcpka
4195 Enable or disable the sending of TCP keepalive packets on both sides
4196 May be used in sections : defaults | frontend | listen | backend
4197 yes | yes | yes | yes
4198 Arguments : none
4199
4200 When there is a firewall or any session-aware component between a client and
4201 a server, and when the protocol involves very long sessions with long idle
4202 periods (eg: remote desktops), there is a risk that one of the intermediate
4203 components decides to expire a session which has remained idle for too long.
4204
4205 Enabling socket-level TCP keep-alives makes the system regularly send packets
4206 to the other end of the connection, leaving it active. The delay between
4207 keep-alive probes is controlled by the system only and depends both on the
4208 operating system and its tuning parameters.
4209
4210 It is important to understand that keep-alive packets are neither emitted nor
4211 received at the application level. It is only the network stacks which sees
4212 them. For this reason, even if one side of the proxy already uses keep-alives
4213 to maintain its connection alive, those keep-alive packets will not be
4214 forwarded to the other side of the proxy.
4215
4216 Please note that this has nothing to do with HTTP keep-alive.
4217
4218 Using option "tcpka" enables the emission of TCP keep-alive probes on both
4219 the client and server sides of a connection. Note that this is meaningful
4220 only in "defaults" or "listen" sections. If this option is used in a
4221 frontend, only the client side will get keep-alives, and if this option is
4222 used in a backend, only the server side will get keep-alives. For this
4223 reason, it is strongly recommended to explicitly use "option clitcpka" and
4224 "option srvtcpka" when the configuration is split between frontends and
4225 backends.
4226
4227 See also : "option clitcpka", "option srvtcpka"
4228
Willy Tarreau844e3c52008-01-11 16:28:18 +01004229
4230option tcplog
4231 Enable advanced logging of TCP connections with session state and timers
4232 May be used in sections : defaults | frontend | listen | backend
4233 yes | yes | yes | yes
4234 Arguments : none
4235
4236 By default, the log output format is very poor, as it only contains the
4237 source and destination addresses, and the instance name. By specifying
4238 "option tcplog", each log line turns into a much richer format including, but
4239 not limited to, the connection timers, the session status, the connections
4240 numbers, the frontend, backend and server name, and of course the source
4241 address and ports. This option is useful for pure TCP proxies in order to
4242 find which of the client or server disconnects or times out. For normal HTTP
4243 proxies, it's better to use "option httplog" which is even more complete.
4244
4245 This option may be set either in the frontend or the backend.
4246
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004247 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004248
4249
Willy Tarreau844e3c52008-01-11 16:28:18 +01004250option transparent
4251no option transparent
4252 Enable client-side transparent proxying
4253 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01004254 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01004255 Arguments : none
4256
4257 This option was introduced in order to provide layer 7 persistence to layer 3
4258 load balancers. The idea is to use the OS's ability to redirect an incoming
4259 connection for a remote address to a local process (here HAProxy), and let
4260 this process know what address was initially requested. When this option is
4261 used, sessions without cookies will be forwarded to the original destination
4262 IP address of the incoming request (which should match that of another
4263 equipment), while requests with cookies will still be forwarded to the
4264 appropriate server.
4265
4266 Note that contrary to a common belief, this option does NOT make HAProxy
4267 present the client's IP to the server when establishing the connection.
4268
Willy Tarreaua1146052011-03-01 09:51:54 +01004269 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004270 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004271
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004272
Emeric Brun647caf12009-06-30 17:57:00 +02004273persist rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02004274persist rdp-cookie(<name>)
Emeric Brun647caf12009-06-30 17:57:00 +02004275 Enable RDP cookie-based persistence
4276 May be used in sections : defaults | frontend | listen | backend
4277 yes | no | yes | yes
4278 Arguments :
4279 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02004280 default cookie name "msts" will be used. There currently is no
4281 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02004282
4283 This statement enables persistence based on an RDP cookie. The RDP cookie
4284 contains all information required to find the server in the list of known
4285 servers. So when this option is set in the backend, the request is analysed
4286 and if an RDP cookie is found, it is decoded. If it matches a known server
4287 which is still UP (or if "option persist" is set), then the connection is
4288 forwarded to this server.
4289
4290 Note that this only makes sense in a TCP backend, but for this to work, the
4291 frontend must have waited long enough to ensure that an RDP cookie is present
4292 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004293 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02004294 a single "listen" section.
4295
Willy Tarreau61e28f22010-05-16 22:31:05 +02004296 Also, it is important to understand that the terminal server will emit this
4297 RDP cookie only if it is configured for "token redirection mode", which means
4298 that the "IP address redirection" option is disabled.
4299
Emeric Brun647caf12009-06-30 17:57:00 +02004300 Example :
4301 listen tse-farm
4302 bind :3389
4303 # wait up to 5s for an RDP cookie in the request
4304 tcp-request inspect-delay 5s
4305 tcp-request content accept if RDP_COOKIE
4306 # apply RDP cookie persistence
4307 persist rdp-cookie
4308 # if server is unknown, let's balance on the same cookie.
Cyril Bontédc4d9032012-04-08 21:57:39 +02004309 # alternatively, "balance leastconn" may be useful too.
Emeric Brun647caf12009-06-30 17:57:00 +02004310 balance rdp-cookie
4311 server srv1 1.1.1.1:3389
4312 server srv2 1.1.1.2:3389
4313
Simon Hormanab814e02011-06-24 14:50:20 +09004314 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
4315 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02004316
4317
Willy Tarreau3a7d2072009-03-05 23:48:25 +01004318rate-limit sessions <rate>
4319 Set a limit on the number of new sessions accepted per second on a frontend
4320 May be used in sections : defaults | frontend | listen | backend
4321 yes | yes | yes | no
4322 Arguments :
4323 <rate> The <rate> parameter is an integer designating the maximum number
4324 of new sessions per second to accept on the frontend.
4325
4326 When the frontend reaches the specified number of new sessions per second, it
4327 stops accepting new connections until the rate drops below the limit again.
4328 During this time, the pending sessions will be kept in the socket's backlog
4329 (in system buffers) and haproxy will not even be aware that sessions are
4330 pending. When applying very low limit on a highly loaded service, it may make
4331 sense to increase the socket's backlog using the "backlog" keyword.
4332
4333 This feature is particularly efficient at blocking connection-based attacks
4334 or service abuse on fragile servers. Since the session rate is measured every
4335 millisecond, it is extremely accurate. Also, the limit applies immediately,
4336 no delay is needed at all to detect the threshold.
4337
4338 Example : limit the connection rate on SMTP to 10 per second max
4339 listen smtp
4340 mode tcp
4341 bind :25
4342 rate-limit sessions 10
4343 server 127.0.0.1:1025
4344
Willy Tarreaua17c2d92011-07-25 08:16:20 +02004345 Note : when the maximum rate is reached, the frontend's status is not changed
4346 but its sockets appear as "WAITING" in the statistics if the
4347 "socket-stats" option is enabled.
Willy Tarreau3a7d2072009-03-05 23:48:25 +01004348
4349 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
4350
4351
Willy Tarreau2e1dca82012-09-12 08:43:15 +02004352redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
4353redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
4354redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004355 Return an HTTP redirection if/unless a condition is matched
4356 May be used in sections : defaults | frontend | listen | backend
4357 no | yes | yes | yes
4358
4359 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01004360 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004361
Willy Tarreau0140f252008-11-19 21:07:09 +01004362 Arguments :
Willy Tarreau2e1dca82012-09-12 08:43:15 +02004363 <loc> With "redirect location", the exact value in <loc> is placed into
4364 the HTTP "Location" header.
4365
4366 <pfx> With "redirect prefix", the "Location" header is built from the
4367 concatenation of <pfx> and the complete URI path, including the
4368 query string, unless the "drop-query" option is specified (see
4369 below). As a special case, if <pfx> equals exactly "/", then
4370 nothing is inserted before the original URI. It allows one to
4371 redirect to the same URL (for instance, to insert a cookie).
4372
4373 <sch> With "redirect scheme", then the "Location" header is built by
4374 concatenating <sch> with "://" then the first occurrence of the
4375 "Host" header, and then the URI path, including the query string
4376 unless the "drop-query" option is specified (see below). If no
4377 path is found or if the path is "*", then "/" is used instead. If
4378 no "Host" header is found, then an empty host component will be
4379 returned, which most recent browsers interprete as redirecting to
4380 the same host. This directive is mostly used to redirect HTTP to
4381 HTTPS.
Willy Tarreau0140f252008-11-19 21:07:09 +01004382
4383 <code> The code is optional. It indicates which type of HTTP redirection
4384 is desired. Only codes 301, 302 and 303 are supported, and 302 is
4385 used if no code is specified. 301 means "Moved permanently", and
4386 a browser may cache the Location. 302 means "Moved permanently"
4387 and means that the browser should not cache the redirection. 303
4388 is equivalent to 302 except that the browser will fetch the
4389 location with a GET method.
4390
4391 <option> There are several options which can be specified to adjust the
4392 expected behaviour of a redirection :
4393
4394 - "drop-query"
4395 When this keyword is used in a prefix-based redirection, then the
4396 location will be set without any possible query-string, which is useful
4397 for directing users to a non-secure page for instance. It has no effect
4398 with a location-type redirect.
4399
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01004400 - "append-slash"
4401 This keyword may be used in conjunction with "drop-query" to redirect
4402 users who use a URL not ending with a '/' to the same one with the '/'.
4403 It can be useful to ensure that search engines will only see one URL.
4404 For this, a return code 301 is preferred.
4405
Willy Tarreau0140f252008-11-19 21:07:09 +01004406 - "set-cookie NAME[=value]"
4407 A "Set-Cookie" header will be added with NAME (and optionally "=value")
4408 to the response. This is sometimes used to indicate that a user has
4409 been seen, for instance to protect against some types of DoS. No other
4410 cookie option is added, so the cookie will be a session cookie. Note
4411 that for a browser, a sole cookie name without an equal sign is
4412 different from a cookie with an equal sign.
4413
4414 - "clear-cookie NAME[=]"
4415 A "Set-Cookie" header will be added with NAME (and optionally "="), but
4416 with the "Max-Age" attribute set to zero. This will tell the browser to
4417 delete this cookie. It is useful for instance on logout pages. It is
4418 important to note that clearing the cookie "NAME" will not remove a
4419 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
4420 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004421
4422 Example: move the login URL only to HTTPS.
4423 acl clear dst_port 80
4424 acl secure dst_port 8080
4425 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01004426 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01004427 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01004428 acl cookie_set hdr_sub(cookie) SEEN=1
4429
4430 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01004431 redirect prefix https://mysite.com if login_page !secure
4432 redirect prefix http://mysite.com drop-query if login_page !uid_given
4433 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01004434 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004435
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01004436 Example: send redirects for request for articles without a '/'.
4437 acl missing_slash path_reg ^/article/[^/]*$
4438 redirect code 301 prefix / drop-query append-slash if missing_slash
4439
Willy Tarreau2e1dca82012-09-12 08:43:15 +02004440 Example: redirect all HTTP traffic to HTTPS when SSL is handled by haproxy.
David BERARDe7153042012-11-03 00:11:31 +01004441 redirect scheme https if !{ ssl_fc }
Willy Tarreau2e1dca82012-09-12 08:43:15 +02004442
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004443 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004444
4445
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004446redisp (deprecated)
4447redispatch (deprecated)
4448 Enable or disable session redistribution in case of connection failure
4449 May be used in sections: defaults | frontend | listen | backend
4450 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004451 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004452
4453 In HTTP mode, if a server designated by a cookie is down, clients may
4454 definitely stick to it because they cannot flush the cookie, so they will not
4455 be able to access the service anymore.
4456
4457 Specifying "redispatch" will allow the proxy to break their persistence and
4458 redistribute them to a working server.
4459
4460 It also allows to retry last connection to another server in case of multiple
4461 connection failures. Of course, it requires having "retries" set to a nonzero
4462 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01004463
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004464 This form is deprecated, do not use it in any new configuration, use the new
4465 "option redispatch" instead.
4466
4467 See also : "option redispatch"
4468
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004469
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004470reqadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01004471 Add a header at the end of the HTTP request
4472 May be used in sections : defaults | frontend | listen | backend
4473 no | yes | yes | yes
4474 Arguments :
4475 <string> is the complete line to be added. Any space or known delimiter
4476 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004477 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004478
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004479 <cond> is an optional matching condition built from ACLs. It makes it
4480 possible to ignore this rule when other conditions are not met.
4481
Willy Tarreau303c0352008-01-17 19:01:39 +01004482 A new line consisting in <string> followed by a line feed will be added after
4483 the last header of an HTTP request.
4484
4485 Header transformations only apply to traffic which passes through HAProxy,
4486 and not to traffic generated by HAProxy, such as health-checks or error
4487 responses.
4488
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004489 Example : add "X-Proto: SSL" to requests coming via port 81
4490 acl is-ssl dst_port 81
4491 reqadd X-Proto:\ SSL if is-ssl
4492
4493 See also: "rspadd", section 6 about HTTP header manipulation, and section 7
4494 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004495
4496
Willy Tarreau5321c422010-01-28 20:35:13 +01004497reqallow <search> [{if | unless} <cond>]
4498reqiallow <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004499 Definitely allow an HTTP request if a line matches a regular expression
4500 May be used in sections : defaults | frontend | listen | backend
4501 no | yes | yes | yes
4502 Arguments :
4503 <search> is the regular expression applied to HTTP headers and to the
4504 request line. This is an extended regular expression. Parenthesis
4505 grouping is supported and no preliminary backslash is required.
4506 Any space or known delimiter must be escaped using a backslash
4507 ('\'). The pattern applies to a full line at a time. The
4508 "reqallow" keyword strictly matches case while "reqiallow"
4509 ignores case.
4510
Willy Tarreau5321c422010-01-28 20:35:13 +01004511 <cond> is an optional matching condition built from ACLs. It makes it
4512 possible to ignore this rule when other conditions are not met.
4513
Willy Tarreau303c0352008-01-17 19:01:39 +01004514 A request containing any line which matches extended regular expression
4515 <search> will mark the request as allowed, even if any later test would
4516 result in a deny. The test applies both to the request line and to request
4517 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01004518 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01004519
4520 It is easier, faster and more powerful to use ACLs to write access policies.
4521 Reqdeny, reqallow and reqpass should be avoided in new designs.
4522
4523 Example :
4524 # allow www.* but refuse *.local
4525 reqiallow ^Host:\ www\.
4526 reqideny ^Host:\ .*\.local
4527
Willy Tarreau5321c422010-01-28 20:35:13 +01004528 See also: "reqdeny", "block", section 6 about HTTP header manipulation, and
4529 section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004530
4531
Willy Tarreau5321c422010-01-28 20:35:13 +01004532reqdel <search> [{if | unless} <cond>]
4533reqidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004534 Delete all headers matching a regular expression in an HTTP request
4535 May be used in sections : defaults | frontend | listen | backend
4536 no | yes | yes | yes
4537 Arguments :
4538 <search> is the regular expression applied to HTTP headers and to the
4539 request line. This is an extended regular expression. Parenthesis
4540 grouping is supported and no preliminary backslash is required.
4541 Any space or known delimiter must be escaped using a backslash
4542 ('\'). The pattern applies to a full line at a time. The "reqdel"
4543 keyword strictly matches case while "reqidel" ignores case.
4544
Willy Tarreau5321c422010-01-28 20:35:13 +01004545 <cond> is an optional matching condition built from ACLs. It makes it
4546 possible to ignore this rule when other conditions are not met.
4547
Willy Tarreau303c0352008-01-17 19:01:39 +01004548 Any header line matching extended regular expression <search> in the request
4549 will be completely deleted. Most common use of this is to remove unwanted
4550 and/or dangerous headers or cookies from a request before passing it to the
4551 next servers.
4552
4553 Header transformations only apply to traffic which passes through HAProxy,
4554 and not to traffic generated by HAProxy, such as health-checks or error
4555 responses. Keep in mind that header names are not case-sensitive.
4556
4557 Example :
4558 # remove X-Forwarded-For header and SERVER cookie
4559 reqidel ^X-Forwarded-For:.*
4560 reqidel ^Cookie:.*SERVER=
4561
Willy Tarreau5321c422010-01-28 20:35:13 +01004562 See also: "reqadd", "reqrep", "rspdel", section 6 about HTTP header
4563 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004564
4565
Willy Tarreau5321c422010-01-28 20:35:13 +01004566reqdeny <search> [{if | unless} <cond>]
4567reqideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004568 Deny an HTTP request if a line matches a regular expression
4569 May be used in sections : defaults | frontend | listen | backend
4570 no | yes | yes | yes
4571 Arguments :
4572 <search> is the regular expression applied to HTTP headers and to the
4573 request line. This is an extended regular expression. Parenthesis
4574 grouping is supported and no preliminary backslash is required.
4575 Any space or known delimiter must be escaped using a backslash
4576 ('\'). The pattern applies to a full line at a time. The
4577 "reqdeny" keyword strictly matches case while "reqideny" ignores
4578 case.
4579
Willy Tarreau5321c422010-01-28 20:35:13 +01004580 <cond> is an optional matching condition built from ACLs. It makes it
4581 possible to ignore this rule when other conditions are not met.
4582
Willy Tarreau303c0352008-01-17 19:01:39 +01004583 A request containing any line which matches extended regular expression
4584 <search> will mark the request as denied, even if any later test would
4585 result in an allow. The test applies both to the request line and to request
4586 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01004587 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01004588
Willy Tarreauced27012008-01-17 20:35:34 +01004589 A denied request will generate an "HTTP 403 forbidden" response once the
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004590 complete request has been parsed. This is consistent with what is practiced
Willy Tarreaud72758d2010-01-12 10:42:19 +01004591 using ACLs.
Willy Tarreauced27012008-01-17 20:35:34 +01004592
Willy Tarreau303c0352008-01-17 19:01:39 +01004593 It is easier, faster and more powerful to use ACLs to write access policies.
4594 Reqdeny, reqallow and reqpass should be avoided in new designs.
4595
4596 Example :
4597 # refuse *.local, then allow www.*
4598 reqideny ^Host:\ .*\.local
4599 reqiallow ^Host:\ www\.
4600
Willy Tarreau5321c422010-01-28 20:35:13 +01004601 See also: "reqallow", "rspdeny", "block", section 6 about HTTP header
4602 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004603
4604
Willy Tarreau5321c422010-01-28 20:35:13 +01004605reqpass <search> [{if | unless} <cond>]
4606reqipass <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004607 Ignore any HTTP request line matching a regular expression in next rules
4608 May be used in sections : defaults | frontend | listen | backend
4609 no | yes | yes | yes
4610 Arguments :
4611 <search> is the regular expression applied to HTTP headers and to the
4612 request line. This is an extended regular expression. Parenthesis
4613 grouping is supported and no preliminary backslash is required.
4614 Any space or known delimiter must be escaped using a backslash
4615 ('\'). The pattern applies to a full line at a time. The
4616 "reqpass" keyword strictly matches case while "reqipass" ignores
4617 case.
4618
Willy Tarreau5321c422010-01-28 20:35:13 +01004619 <cond> is an optional matching condition built from ACLs. It makes it
4620 possible to ignore this rule when other conditions are not met.
4621
Willy Tarreau303c0352008-01-17 19:01:39 +01004622 A request containing any line which matches extended regular expression
4623 <search> will skip next rules, without assigning any deny or allow verdict.
4624 The test applies both to the request line and to request headers. Keep in
4625 mind that URLs in request line are case-sensitive while header names are not.
4626
4627 It is easier, faster and more powerful to use ACLs to write access policies.
4628 Reqdeny, reqallow and reqpass should be avoided in new designs.
4629
4630 Example :
4631 # refuse *.local, then allow www.*, but ignore "www.private.local"
4632 reqipass ^Host:\ www.private\.local
4633 reqideny ^Host:\ .*\.local
4634 reqiallow ^Host:\ www\.
4635
Willy Tarreau5321c422010-01-28 20:35:13 +01004636 See also: "reqallow", "reqdeny", "block", section 6 about HTTP header
4637 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004638
4639
Willy Tarreau5321c422010-01-28 20:35:13 +01004640reqrep <search> <string> [{if | unless} <cond>]
4641reqirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004642 Replace a regular expression with a string in an HTTP request line
4643 May be used in sections : defaults | frontend | listen | backend
4644 no | yes | yes | yes
4645 Arguments :
4646 <search> is the regular expression applied to HTTP headers and to the
4647 request line. This is an extended regular expression. Parenthesis
4648 grouping is supported and no preliminary backslash is required.
4649 Any space or known delimiter must be escaped using a backslash
4650 ('\'). The pattern applies to a full line at a time. The "reqrep"
4651 keyword strictly matches case while "reqirep" ignores case.
4652
4653 <string> is the complete line to be added. Any space or known delimiter
4654 must be escaped using a backslash ('\'). References to matched
4655 pattern groups are possible using the common \N form, with N
4656 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004657 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004658
Willy Tarreau5321c422010-01-28 20:35:13 +01004659 <cond> is an optional matching condition built from ACLs. It makes it
4660 possible to ignore this rule when other conditions are not met.
4661
Willy Tarreau303c0352008-01-17 19:01:39 +01004662 Any line matching extended regular expression <search> in the request (both
4663 the request line and header lines) will be completely replaced with <string>.
4664 Most common use of this is to rewrite URLs or domain names in "Host" headers.
4665
4666 Header transformations only apply to traffic which passes through HAProxy,
4667 and not to traffic generated by HAProxy, such as health-checks or error
4668 responses. Note that for increased readability, it is suggested to add enough
4669 spaces between the request and the response. Keep in mind that URLs in
4670 request line are case-sensitive while header names are not.
4671
4672 Example :
4673 # replace "/static/" with "/" at the beginning of any request path.
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04004674 reqrep ^([^\ :]*)\ /static/(.*) \1\ /\2
Willy Tarreau303c0352008-01-17 19:01:39 +01004675 # replace "www.mydomain.com" with "www" in the host name.
4676 reqirep ^Host:\ www.mydomain.com Host:\ www
4677
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +04004678 See also: "reqadd", "reqdel", "rsprep", "tune.bufsize", section 6 about
4679 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004680
4681
Willy Tarreau5321c422010-01-28 20:35:13 +01004682reqtarpit <search> [{if | unless} <cond>]
4683reqitarpit <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004684 Tarpit an HTTP request containing a line matching a regular expression
4685 May be used in sections : defaults | frontend | listen | backend
4686 no | yes | yes | yes
4687 Arguments :
4688 <search> is the regular expression applied to HTTP headers and to the
4689 request line. This is an extended regular expression. Parenthesis
4690 grouping is supported and no preliminary backslash is required.
4691 Any space or known delimiter must be escaped using a backslash
4692 ('\'). The pattern applies to a full line at a time. The
4693 "reqtarpit" keyword strictly matches case while "reqitarpit"
4694 ignores case.
4695
Willy Tarreau5321c422010-01-28 20:35:13 +01004696 <cond> is an optional matching condition built from ACLs. It makes it
4697 possible to ignore this rule when other conditions are not met.
4698
Willy Tarreau303c0352008-01-17 19:01:39 +01004699 A request containing any line which matches extended regular expression
4700 <search> will be tarpitted, which means that it will connect to nowhere, will
Willy Tarreauced27012008-01-17 20:35:34 +01004701 be kept open for a pre-defined time, then will return an HTTP error 500 so
4702 that the attacker does not suspect it has been tarpitted. The status 500 will
4703 be reported in the logs, but the completion flags will indicate "PT". The
Willy Tarreau303c0352008-01-17 19:01:39 +01004704 delay is defined by "timeout tarpit", or "timeout connect" if the former is
4705 not set.
4706
4707 The goal of the tarpit is to slow down robots attacking servers with
4708 identifiable requests. Many robots limit their outgoing number of connections
4709 and stay connected waiting for a reply which can take several minutes to
4710 come. Depending on the environment and attack, it may be particularly
4711 efficient at reducing the load on the network and firewalls.
4712
Willy Tarreau5321c422010-01-28 20:35:13 +01004713 Examples :
Willy Tarreau303c0352008-01-17 19:01:39 +01004714 # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but
4715 # block all others.
4716 reqipass ^User-Agent:\.*(Mozilla|MSIE)
4717 reqitarpit ^User-Agent:
4718
Willy Tarreau5321c422010-01-28 20:35:13 +01004719 # block bad guys
4720 acl badguys src 10.1.0.3 172.16.13.20/28
4721 reqitarpit . if badguys
4722
4723 See also: "reqallow", "reqdeny", "reqpass", section 6 about HTTP header
4724 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004725
4726
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02004727retries <value>
4728 Set the number of retries to perform on a server after a connection failure
4729 May be used in sections: defaults | frontend | listen | backend
4730 yes | no | yes | yes
4731 Arguments :
4732 <value> is the number of times a connection attempt should be retried on
4733 a server when a connection either is refused or times out. The
4734 default value is 3.
4735
4736 It is important to understand that this value applies to the number of
4737 connection attempts, not full requests. When a connection has effectively
4738 been established to a server, there will be no more retry.
4739
4740 In order to avoid immediate reconnections to a server which is restarting,
4741 a turn-around timer of 1 second is applied before a retry occurs.
4742
4743 When "option redispatch" is set, the last retry may be performed on another
4744 server even if a cookie references a different server.
4745
4746 See also : "option redispatch"
4747
4748
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004749rspadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01004750 Add a header at the end of the HTTP response
4751 May be used in sections : defaults | frontend | listen | backend
4752 no | yes | yes | yes
4753 Arguments :
4754 <string> is the complete line to be added. Any space or known delimiter
4755 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004756 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004757
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004758 <cond> is an optional matching condition built from ACLs. It makes it
4759 possible to ignore this rule when other conditions are not met.
4760
Willy Tarreau303c0352008-01-17 19:01:39 +01004761 A new line consisting in <string> followed by a line feed will be added after
4762 the last header of an HTTP response.
4763
4764 Header transformations only apply to traffic which passes through HAProxy,
4765 and not to traffic generated by HAProxy, such as health-checks or error
4766 responses.
4767
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004768 See also: "reqadd", section 6 about HTTP header manipulation, and section 7
4769 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004770
4771
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004772rspdel <search> [{if | unless} <cond>]
4773rspidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004774 Delete all headers matching a regular expression in an HTTP response
4775 May be used in sections : defaults | frontend | listen | backend
4776 no | yes | yes | yes
4777 Arguments :
4778 <search> is the regular expression applied to HTTP headers and to the
4779 response line. This is an extended regular expression, so
4780 parenthesis grouping is supported and no preliminary backslash
4781 is required. Any space or known delimiter must be escaped using
4782 a backslash ('\'). The pattern applies to a full line at a time.
4783 The "rspdel" keyword strictly matches case while "rspidel"
4784 ignores case.
4785
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004786 <cond> is an optional matching condition built from ACLs. It makes it
4787 possible to ignore this rule when other conditions are not met.
4788
Willy Tarreau303c0352008-01-17 19:01:39 +01004789 Any header line matching extended regular expression <search> in the response
4790 will be completely deleted. Most common use of this is to remove unwanted
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02004791 and/or sensitive headers or cookies from a response before passing it to the
Willy Tarreau303c0352008-01-17 19:01:39 +01004792 client.
4793
4794 Header transformations only apply to traffic which passes through HAProxy,
4795 and not to traffic generated by HAProxy, such as health-checks or error
4796 responses. Keep in mind that header names are not case-sensitive.
4797
4798 Example :
4799 # remove the Server header from responses
4800 reqidel ^Server:.*
4801
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004802 See also: "rspadd", "rsprep", "reqdel", section 6 about HTTP header
4803 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004804
4805
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004806rspdeny <search> [{if | unless} <cond>]
4807rspideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004808 Block an HTTP response if a line matches a regular expression
4809 May be used in sections : defaults | frontend | listen | backend
4810 no | yes | yes | yes
4811 Arguments :
4812 <search> is the regular expression applied to HTTP headers and to the
4813 response line. This is an extended regular expression, so
4814 parenthesis grouping is supported and no preliminary backslash
4815 is required. Any space or known delimiter must be escaped using
4816 a backslash ('\'). The pattern applies to a full line at a time.
4817 The "rspdeny" keyword strictly matches case while "rspideny"
4818 ignores case.
4819
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004820 <cond> is an optional matching condition built from ACLs. It makes it
4821 possible to ignore this rule when other conditions are not met.
4822
Willy Tarreau303c0352008-01-17 19:01:39 +01004823 A response containing any line which matches extended regular expression
4824 <search> will mark the request as denied. The test applies both to the
4825 response line and to response headers. Keep in mind that header names are not
4826 case-sensitive.
4827
4828 Main use of this keyword is to prevent sensitive information leak and to
Willy Tarreauced27012008-01-17 20:35:34 +01004829 block the response before it reaches the client. If a response is denied, it
4830 will be replaced with an HTTP 502 error so that the client never retrieves
4831 any sensitive data.
Willy Tarreau303c0352008-01-17 19:01:39 +01004832
4833 It is easier, faster and more powerful to use ACLs to write access policies.
4834 Rspdeny should be avoided in new designs.
4835
4836 Example :
4837 # Ensure that no content type matching ms-word will leak
4838 rspideny ^Content-type:\.*/ms-word
4839
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004840 See also: "reqdeny", "acl", "block", section 6 about HTTP header manipulation
4841 and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004842
4843
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004844rsprep <search> <string> [{if | unless} <cond>]
4845rspirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004846 Replace a regular expression with a string in an HTTP response line
4847 May be used in sections : defaults | frontend | listen | backend
4848 no | yes | yes | yes
4849 Arguments :
4850 <search> is the regular expression applied to HTTP headers and to the
4851 response line. This is an extended regular expression, so
4852 parenthesis grouping is supported and no preliminary backslash
4853 is required. Any space or known delimiter must be escaped using
4854 a backslash ('\'). The pattern applies to a full line at a time.
4855 The "rsprep" keyword strictly matches case while "rspirep"
4856 ignores case.
4857
4858 <string> is the complete line to be added. Any space or known delimiter
4859 must be escaped using a backslash ('\'). References to matched
4860 pattern groups are possible using the common \N form, with N
4861 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004862 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004863
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004864 <cond> is an optional matching condition built from ACLs. It makes it
4865 possible to ignore this rule when other conditions are not met.
4866
Willy Tarreau303c0352008-01-17 19:01:39 +01004867 Any line matching extended regular expression <search> in the response (both
4868 the response line and header lines) will be completely replaced with
4869 <string>. Most common use of this is to rewrite Location headers.
4870
4871 Header transformations only apply to traffic which passes through HAProxy,
4872 and not to traffic generated by HAProxy, such as health-checks or error
4873 responses. Note that for increased readability, it is suggested to add enough
4874 spaces between the request and the response. Keep in mind that header names
4875 are not case-sensitive.
4876
4877 Example :
4878 # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com"
4879 rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com
4880
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004881 See also: "rspadd", "rspdel", "reqrep", section 6 about HTTP header
4882 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004883
4884
David du Colombier486df472011-03-17 10:40:26 +01004885server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004886 Declare a server in a backend
4887 May be used in sections : defaults | frontend | listen | backend
4888 no | no | yes | yes
4889 Arguments :
4890 <name> is the internal name assigned to this server. This name will
Cyril Bonté941a0c62012-10-15 19:44:24 +02004891 appear in logs and alerts. If "http-send-name-header" is
Mark Lamourinec2247f02012-01-04 13:02:01 -05004892 set, it will be added to the request header sent to the server.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004893
David du Colombier486df472011-03-17 10:40:26 +01004894 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
4895 resolvable hostname is supported, but this name will be resolved
4896 during start-up. Address "0.0.0.0" or "*" has a special meaning.
4897 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +02004898 address as the one from the client connection. This is useful in
4899 transparent proxy architectures where the client's connection is
4900 intercepted and haproxy must forward to the original destination
4901 address. This is more or less what the "transparent" keyword does
4902 except that with a server it's possible to limit concurrency and
4903 to report statistics.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004904
Willy Tarreaub6205fd2012-09-24 12:27:33 +02004905 <port> is an optional port specification. If set, all connections will
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004906 be sent to this port. If unset, the same port the client
4907 connected to will be used. The port may also be prefixed by a "+"
4908 or a "-". In this case, the server's port will be determined by
4909 adding this value to the client's port.
4910
4911 <param*> is a list of parameters for this server. The "server" keywords
4912 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004913 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004914
4915 Examples :
4916 server first 10.1.1.1:1080 cookie first check inter 1000
4917 server second 10.1.1.2:1080 cookie second check inter 1000
4918
Mark Lamourinec2247f02012-01-04 13:02:01 -05004919 See also: "default-server", "http-send-name-header" and section 5 about
4920 server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004921
4922
4923source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02004924source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01004925source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004926 Set the source address for outgoing connections
4927 May be used in sections : defaults | frontend | listen | backend
4928 yes | no | yes | yes
4929 Arguments :
4930 <addr> is the IPv4 address HAProxy will bind to before connecting to a
4931 server. This address is also used as a source for health checks.
4932 The default value of 0.0.0.0 means that the system will select
4933 the most appropriate address to reach its destination.
4934
4935 <port> is an optional port. It is normally not needed but may be useful
4936 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02004937 the system will select a free port. Note that port ranges are not
4938 supported in the backend. If you want to force port ranges, you
4939 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004940
4941 <addr2> is the IP address to present to the server when connections are
4942 forwarded in full transparent proxy mode. This is currently only
4943 supported on some patched Linux kernels. When this address is
4944 specified, clients connecting to the server will be presented
4945 with this address, while health checks will still use the address
4946 <addr>.
4947
4948 <port2> is the optional port to present to the server when connections
4949 are forwarded in full transparent proxy mode (see <addr2> above).
4950 The default value of zero means the system will select a free
4951 port.
4952
Willy Tarreaubce70882009-09-07 11:51:47 +02004953 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
4954 This is the name of a comma-separated header list which can
4955 contain multiple IP addresses. By default, the last occurrence is
4956 used. This is designed to work with the X-Forwarded-For header
4957 and to automatically bind to the the client's IP address as seen
4958 by previous proxy, typically Stunnel. In order to use another
4959 occurrence from the last one, please see the <occ> parameter
4960 below. When the header (or occurrence) is not found, no binding
4961 is performed so that the proxy's default IP address is used. Also
4962 keep in mind that the header name is case insensitive, as for any
4963 HTTP header.
4964
4965 <occ> is the occurrence number of a value to be used in a multi-value
4966 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004967 in order to specify which occurrence to use for the source IP
Willy Tarreaubce70882009-09-07 11:51:47 +02004968 address. Positive values indicate a position from the first
4969 occurrence, 1 being the first one. Negative values indicate
4970 positions relative to the last one, -1 being the last one. This
4971 is helpful for situations where an X-Forwarded-For header is set
4972 at the entry point of an infrastructure and must be used several
4973 proxy layers away. When this value is not specified, -1 is
4974 assumed. Passing a zero here disables the feature.
4975
Willy Tarreaud53f96b2009-02-04 18:46:54 +01004976 <name> is an optional interface name to which to bind to for outgoing
4977 traffic. On systems supporting this features (currently, only
4978 Linux), this allows one to bind all traffic to the server to
4979 this interface even if it is not the one the system would select
4980 based on routing tables. This should be used with extreme care.
4981 Note that using this option requires root privileges.
4982
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004983 The "source" keyword is useful in complex environments where a specific
4984 address only is allowed to connect to the servers. It may be needed when a
4985 private address must be used through a public gateway for instance, and it is
4986 known that the system cannot determine the adequate source address by itself.
4987
4988 An extension which is available on certain patched Linux kernels may be used
4989 through the "usesrc" optional keyword. It makes it possible to connect to the
4990 servers with an IP address which does not belong to the system itself. This
4991 is called "full transparent proxy mode". For this to work, the destination
4992 servers have to route their traffic back to this address through the machine
4993 running HAProxy, and IP forwarding must generally be enabled on this machine.
4994
4995 In this "full transparent proxy" mode, it is possible to force a specific IP
4996 address to be presented to the servers. This is not much used in fact. A more
4997 common use is to tell HAProxy to present the client's IP address. For this,
4998 there are two methods :
4999
5000 - present the client's IP and port addresses. This is the most transparent
5001 mode, but it can cause problems when IP connection tracking is enabled on
5002 the machine, because a same connection may be seen twice with different
5003 states. However, this solution presents the huge advantage of not
5004 limiting the system to the 64k outgoing address+port couples, because all
5005 of the client ranges may be used.
5006
5007 - present only the client's IP address and select a spare port. This
5008 solution is still quite elegant but slightly less transparent (downstream
5009 firewalls logs will not match upstream's). It also presents the downside
5010 of limiting the number of concurrent connections to the usual 64k ports.
5011 However, since the upstream and downstream ports are different, local IP
5012 connection tracking on the machine will not be upset by the reuse of the
5013 same session.
5014
5015 Note that depending on the transparent proxy technology used, it may be
5016 required to force the source address. In fact, cttproxy version 2 requires an
5017 IP address in <addr> above, and does not support setting of "0.0.0.0" as the
5018 IP address because it creates NAT entries which much match the exact outgoing
5019 address. Tproxy version 4 and some other kernel patches which work in pure
5020 forwarding mode generally will not have this limitation.
5021
5022 This option sets the default source for all servers in the backend. It may
5023 also be specified in a "defaults" section. Finer source address specification
5024 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005025 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005026
5027 Examples :
5028 backend private
5029 # Connect to the servers using our 192.168.1.200 source address
5030 source 192.168.1.200
5031
5032 backend transparent_ssl1
5033 # Connect to the SSL farm from the client's source address
5034 source 192.168.1.200 usesrc clientip
5035
5036 backend transparent_ssl2
5037 # Connect to the SSL farm from the client's source address and port
5038 # not recommended if IP conntrack is present on the local machine.
5039 source 192.168.1.200 usesrc client
5040
5041 backend transparent_ssl3
5042 # Connect to the SSL farm from the client's source address. It
5043 # is more conntrack-friendly.
5044 source 192.168.1.200 usesrc clientip
5045
5046 backend transparent_smtp
5047 # Connect to the SMTP farm from the client's source address/port
5048 # with Tproxy version 4.
5049 source 0.0.0.0 usesrc clientip
5050
Willy Tarreaubce70882009-09-07 11:51:47 +02005051 backend transparent_http
5052 # Connect to the servers using the client's IP as seen by previous
5053 # proxy.
5054 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
5055
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005056 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005057 the Linux kernel on www.balabit.com, the "bind" keyword.
5058
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005059
Willy Tarreau844e3c52008-01-11 16:28:18 +01005060srvtimeout <timeout> (deprecated)
5061 Set the maximum inactivity time on the server side.
5062 May be used in sections : defaults | frontend | listen | backend
5063 yes | no | yes | yes
5064 Arguments :
5065 <timeout> is the timeout value specified in milliseconds by default, but
5066 can be in any other unit if the number is suffixed by the unit,
5067 as explained at the top of this document.
5068
5069 The inactivity timeout applies when the server is expected to acknowledge or
5070 send data. In HTTP mode, this timeout is particularly important to consider
5071 during the first phase of the server's response, when it has to send the
5072 headers, as it directly represents the server's processing time for the
5073 request. To find out what value to put there, it's often good to start with
5074 what would be considered as unacceptable response times, then check the logs
5075 to observe the response time distribution, and adjust the value accordingly.
5076
5077 The value is specified in milliseconds by default, but can be in any other
5078 unit if the number is suffixed by the unit, as specified at the top of this
5079 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
5080 recommended that the client timeout remains equal to the server timeout in
5081 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01005082 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01005083 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreaud72758d2010-01-12 10:42:19 +01005084 seconds (eg: 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01005085
5086 This parameter is specific to backends, but can be specified once for all in
5087 "defaults" sections. This is in fact one of the easiest solutions not to
5088 forget about it. An unspecified timeout results in an infinite timeout, which
5089 is not recommended. Such a usage is accepted and works but reports a warning
5090 during startup because it may results in accumulation of expired sessions in
5091 the system if the system's timeouts are not configured either.
5092
5093 This parameter is provided for compatibility but is currently deprecated.
5094 Please use "timeout server" instead.
5095
Willy Tarreauce887fd2012-05-12 12:50:00 +02005096 See also : "timeout server", "timeout tunnel", "timeout client" and
5097 "clitimeout".
Willy Tarreau844e3c52008-01-11 16:28:18 +01005098
5099
Cyril Bonté66c327d2010-10-12 00:14:37 +02005100stats admin { if | unless } <cond>
5101 Enable statistics admin level if/unless a condition is matched
5102 May be used in sections : defaults | frontend | listen | backend
5103 no | no | yes | yes
5104
5105 This statement enables the statistics admin level if/unless a condition is
5106 matched.
5107
5108 The admin level allows to enable/disable servers from the web interface. By
5109 default, statistics page is read-only for security reasons.
5110
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005111 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5112 unless you know what you do : memory is not shared between the
5113 processes, which can result in random behaviours.
5114
Cyril Bonté23b39d92011-02-10 22:54:44 +01005115 Currently, the POST request is limited to the buffer size minus the reserved
5116 buffer space, which means that if the list of servers is too long, the
5117 request won't be processed. It is recommended to alter few servers at a
5118 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02005119
5120 Example :
5121 # statistics admin level only for localhost
5122 backend stats_localhost
5123 stats enable
5124 stats admin if LOCALHOST
5125
5126 Example :
5127 # statistics admin level always enabled because of the authentication
5128 backend stats_auth
5129 stats enable
5130 stats auth admin:AdMiN123
5131 stats admin if TRUE
5132
5133 Example :
5134 # statistics admin level depends on the authenticated user
5135 userlist stats-auth
5136 group admin users admin
5137 user admin insecure-password AdMiN123
5138 group readonly users haproxy
5139 user haproxy insecure-password haproxy
5140
5141 backend stats_auth
5142 stats enable
5143 acl AUTH http_auth(stats-auth)
5144 acl AUTH_ADMIN http_auth_group(stats-auth) admin
5145 stats http-request auth unless AUTH
5146 stats admin if AUTH_ADMIN
5147
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005148 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
5149 "bind-process", section 3.4 about userlists and section 7 about
5150 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02005151
5152
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005153stats auth <user>:<passwd>
5154 Enable statistics with authentication and grant access to an account
5155 May be used in sections : defaults | frontend | listen | backend
5156 yes | no | yes | yes
5157 Arguments :
5158 <user> is a user name to grant access to
5159
5160 <passwd> is the cleartext password associated to this user
5161
5162 This statement enables statistics with default settings, and restricts access
5163 to declared users only. It may be repeated as many times as necessary to
5164 allow as many users as desired. When a user tries to access the statistics
5165 without a valid account, a "401 Forbidden" response will be returned so that
5166 the browser asks the user to provide a valid user and password. The real
5167 which will be returned to the browser is configurable using "stats realm".
5168
5169 Since the authentication method is HTTP Basic Authentication, the passwords
5170 circulate in cleartext on the network. Thus, it was decided that the
5171 configuration file would also use cleartext passwords to remind the users
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02005172 that those ones should not be sensitive and not shared with any other account.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005173
5174 It is also possible to reduce the scope of the proxies which appear in the
5175 report using "stats scope".
5176
5177 Though this statement alone is enough to enable statistics reporting, it is
5178 recommended to set all other settings in order to avoid relying on default
5179 unobvious parameters.
5180
5181 Example :
5182 # public access (limited to this backend only)
5183 backend public_www
5184 server srv1 192.168.0.1:80
5185 stats enable
5186 stats hide-version
5187 stats scope .
5188 stats uri /admin?stats
5189 stats realm Haproxy\ Statistics
5190 stats auth admin1:AdMiN123
5191 stats auth admin2:AdMiN321
5192
5193 # internal monitoring access (unlimited)
5194 backend private_monitoring
5195 stats enable
5196 stats uri /admin?stats
5197 stats refresh 5s
5198
5199 See also : "stats enable", "stats realm", "stats scope", "stats uri"
5200
5201
5202stats enable
5203 Enable statistics reporting with default settings
5204 May be used in sections : defaults | frontend | listen | backend
5205 yes | no | yes | yes
5206 Arguments : none
5207
5208 This statement enables statistics reporting with default settings defined
5209 at build time. Unless stated otherwise, these settings are used :
5210 - stats uri : /haproxy?stats
5211 - stats realm : "HAProxy Statistics"
5212 - stats auth : no authentication
5213 - stats scope : no restriction
5214
5215 Though this statement alone is enough to enable statistics reporting, it is
5216 recommended to set all other settings in order to avoid relying on default
5217 unobvious parameters.
5218
5219 Example :
5220 # public access (limited to this backend only)
5221 backend public_www
5222 server srv1 192.168.0.1:80
5223 stats enable
5224 stats hide-version
5225 stats scope .
5226 stats uri /admin?stats
5227 stats realm Haproxy\ Statistics
5228 stats auth admin1:AdMiN123
5229 stats auth admin2:AdMiN321
5230
5231 # internal monitoring access (unlimited)
5232 backend private_monitoring
5233 stats enable
5234 stats uri /admin?stats
5235 stats refresh 5s
5236
5237 See also : "stats auth", "stats realm", "stats uri"
5238
5239
Willy Tarreaud63335a2010-02-26 12:56:52 +01005240stats hide-version
5241 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005242 May be used in sections : defaults | frontend | listen | backend
5243 yes | no | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01005244 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005245
Willy Tarreaud63335a2010-02-26 12:56:52 +01005246 By default, the stats page reports some useful status information along with
5247 the statistics. Among them is HAProxy's version. However, it is generally
5248 considered dangerous to report precise version to anyone, as it can help them
5249 target known weaknesses with specific attacks. The "stats hide-version"
5250 statement removes the version from the statistics report. This is recommended
5251 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005252
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02005253 Though this statement alone is enough to enable statistics reporting, it is
5254 recommended to set all other settings in order to avoid relying on default
5255 unobvious parameters.
5256
Willy Tarreaud63335a2010-02-26 12:56:52 +01005257 Example :
5258 # public access (limited to this backend only)
5259 backend public_www
5260 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02005261 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01005262 stats hide-version
5263 stats scope .
5264 stats uri /admin?stats
5265 stats realm Haproxy\ Statistics
5266 stats auth admin1:AdMiN123
5267 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005268
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005269 # internal monitoring access (unlimited)
5270 backend private_monitoring
5271 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01005272 stats uri /admin?stats
5273 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01005274
Willy Tarreaud63335a2010-02-26 12:56:52 +01005275 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005276
Willy Tarreau983e01e2010-01-11 18:42:06 +01005277
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02005278stats http-request { allow | deny | auth [realm <realm>] }
5279 [ { if | unless } <condition> ]
5280 Access control for statistics
5281
5282 May be used in sections: defaults | frontend | listen | backend
5283 no | no | yes | yes
5284
5285 As "http-request", these set of options allow to fine control access to
5286 statistics. Each option may be followed by if/unless and acl.
5287 First option with matched condition (or option without condition) is final.
5288 For "deny" a 403 error will be returned, for "allow" normal processing is
5289 performed, for "auth" a 401/407 error code is returned so the client
5290 should be asked to enter a username and password.
5291
5292 There is no fixed limit to the number of http-request statements per
5293 instance.
5294
5295 See also : "http-request", section 3.4 about userlists and section 7
5296 about ACL usage.
5297
5298
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005299stats realm <realm>
5300 Enable statistics and set authentication realm
5301 May be used in sections : defaults | frontend | listen | backend
5302 yes | no | yes | yes
5303 Arguments :
5304 <realm> is the name of the HTTP Basic Authentication realm reported to
5305 the browser. The browser uses it to display it in the pop-up
5306 inviting the user to enter a valid username and password.
5307
5308 The realm is read as a single word, so any spaces in it should be escaped
5309 using a backslash ('\').
5310
5311 This statement is useful only in conjunction with "stats auth" since it is
5312 only related to authentication.
5313
5314 Though this statement alone is enough to enable statistics reporting, it is
5315 recommended to set all other settings in order to avoid relying on default
5316 unobvious parameters.
5317
5318 Example :
5319 # public access (limited to this backend only)
5320 backend public_www
5321 server srv1 192.168.0.1:80
5322 stats enable
5323 stats hide-version
5324 stats scope .
5325 stats uri /admin?stats
5326 stats realm Haproxy\ Statistics
5327 stats auth admin1:AdMiN123
5328 stats auth admin2:AdMiN321
5329
5330 # internal monitoring access (unlimited)
5331 backend private_monitoring
5332 stats enable
5333 stats uri /admin?stats
5334 stats refresh 5s
5335
5336 See also : "stats auth", "stats enable", "stats uri"
5337
5338
5339stats refresh <delay>
5340 Enable statistics with automatic refresh
5341 May be used in sections : defaults | frontend | listen | backend
5342 yes | no | yes | yes
5343 Arguments :
5344 <delay> is the suggested refresh delay, specified in seconds, which will
5345 be returned to the browser consulting the report page. While the
5346 browser is free to apply any delay, it will generally respect it
5347 and refresh the page this every seconds. The refresh interval may
5348 be specified in any other non-default time unit, by suffixing the
5349 unit after the value, as explained at the top of this document.
5350
5351 This statement is useful on monitoring displays with a permanent page
5352 reporting the load balancer's activity. When set, the HTML report page will
5353 include a link "refresh"/"stop refresh" so that the user can select whether
5354 he wants automatic refresh of the page or not.
5355
5356 Though this statement alone is enough to enable statistics reporting, it is
5357 recommended to set all other settings in order to avoid relying on default
5358 unobvious parameters.
5359
5360 Example :
5361 # public access (limited to this backend only)
5362 backend public_www
5363 server srv1 192.168.0.1:80
5364 stats enable
5365 stats hide-version
5366 stats scope .
5367 stats uri /admin?stats
5368 stats realm Haproxy\ Statistics
5369 stats auth admin1:AdMiN123
5370 stats auth admin2:AdMiN321
5371
5372 # internal monitoring access (unlimited)
5373 backend private_monitoring
5374 stats enable
5375 stats uri /admin?stats
5376 stats refresh 5s
5377
5378 See also : "stats auth", "stats enable", "stats realm", "stats uri"
5379
5380
5381stats scope { <name> | "." }
5382 Enable statistics and limit access scope
5383 May be used in sections : defaults | frontend | listen | backend
5384 yes | no | yes | yes
5385 Arguments :
5386 <name> is the name of a listen, frontend or backend section to be
5387 reported. The special name "." (a single dot) designates the
5388 section in which the statement appears.
5389
5390 When this statement is specified, only the sections enumerated with this
5391 statement will appear in the report. All other ones will be hidden. This
5392 statement may appear as many times as needed if multiple sections need to be
5393 reported. Please note that the name checking is performed as simple string
5394 comparisons, and that it is never checked that a give section name really
5395 exists.
5396
5397 Though this statement alone is enough to enable statistics reporting, it is
5398 recommended to set all other settings in order to avoid relying on default
5399 unobvious parameters.
5400
5401 Example :
5402 # public access (limited to this backend only)
5403 backend public_www
5404 server srv1 192.168.0.1:80
5405 stats enable
5406 stats hide-version
5407 stats scope .
5408 stats uri /admin?stats
5409 stats realm Haproxy\ Statistics
5410 stats auth admin1:AdMiN123
5411 stats auth admin2:AdMiN321
5412
5413 # internal monitoring access (unlimited)
5414 backend private_monitoring
5415 stats enable
5416 stats uri /admin?stats
5417 stats refresh 5s
5418
5419 See also : "stats auth", "stats enable", "stats realm", "stats uri"
5420
Willy Tarreaud63335a2010-02-26 12:56:52 +01005421
Willy Tarreauc9705a12010-07-27 20:05:50 +02005422stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01005423 Enable reporting of a description on the statistics page.
5424 May be used in sections : defaults | frontend | listen | backend
5425 yes | no | yes | yes
5426
Willy Tarreauc9705a12010-07-27 20:05:50 +02005427 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01005428 description from global section is automatically used instead.
5429
5430 This statement is useful for users that offer shared services to their
5431 customers, where node or description should be different for each customer.
5432
5433 Though this statement alone is enough to enable statistics reporting, it is
5434 recommended to set all other settings in order to avoid relying on default
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04005435 unobvious parameters. By default description is not shown.
Willy Tarreaud63335a2010-02-26 12:56:52 +01005436
5437 Example :
5438 # internal monitoring access (unlimited)
5439 backend private_monitoring
5440 stats enable
5441 stats show-desc Master node for Europe, Asia, Africa
5442 stats uri /admin?stats
5443 stats refresh 5s
5444
5445 See also: "show-node", "stats enable", "stats uri" and "description" in
5446 global section.
5447
5448
5449stats show-legends
5450 Enable reporting additional informations on the statistics page :
5451 - cap: capabilities (proxy)
5452 - mode: one of tcp, http or health (proxy)
5453 - id: SNMP ID (proxy, socket, server)
5454 - IP (socket, server)
5455 - cookie (backend, server)
5456
5457 Though this statement alone is enough to enable statistics reporting, it is
5458 recommended to set all other settings in order to avoid relying on default
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04005459 unobvious parameters. Default behaviour is not to show this information.
Willy Tarreaud63335a2010-02-26 12:56:52 +01005460
5461 See also: "stats enable", "stats uri".
5462
5463
5464stats show-node [ <name> ]
5465 Enable reporting of a host name on the statistics page.
5466 May be used in sections : defaults | frontend | listen | backend
5467 yes | no | yes | yes
5468 Arguments:
5469 <name> is an optional name to be reported. If unspecified, the
5470 node name from global section is automatically used instead.
5471
5472 This statement is useful for users that offer shared services to their
5473 customers, where node or description might be different on a stats page
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04005474 provided for each customer. Default behaviour is not to show host name.
Willy Tarreaud63335a2010-02-26 12:56:52 +01005475
5476 Though this statement alone is enough to enable statistics reporting, it is
5477 recommended to set all other settings in order to avoid relying on default
5478 unobvious parameters.
5479
5480 Example:
5481 # internal monitoring access (unlimited)
5482 backend private_monitoring
5483 stats enable
5484 stats show-node Europe-1
5485 stats uri /admin?stats
5486 stats refresh 5s
5487
5488 See also: "show-desc", "stats enable", "stats uri", and "node" in global
5489 section.
5490
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005491
5492stats uri <prefix>
5493 Enable statistics and define the URI prefix to access them
5494 May be used in sections : defaults | frontend | listen | backend
5495 yes | no | yes | yes
5496 Arguments :
5497 <prefix> is the prefix of any URI which will be redirected to stats. This
5498 prefix may contain a question mark ('?') to indicate part of a
5499 query string.
5500
5501 The statistics URI is intercepted on the relayed traffic, so it appears as a
5502 page within the normal application. It is strongly advised to ensure that the
5503 selected URI will never appear in the application, otherwise it will never be
5504 possible to reach it in the application.
5505
5506 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005507 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005508 It is generally a good idea to include a question mark in the URI so that
5509 intermediate proxies refrain from caching the results. Also, since any string
5510 beginning with the prefix will be accepted as a stats request, the question
5511 mark helps ensuring that no valid URI will begin with the same words.
5512
5513 It is sometimes very convenient to use "/" as the URI prefix, and put that
5514 statement in a "listen" instance of its own. That makes it easy to dedicate
5515 an address or a port to statistics only.
5516
5517 Though this statement alone is enough to enable statistics reporting, it is
5518 recommended to set all other settings in order to avoid relying on default
5519 unobvious parameters.
5520
5521 Example :
5522 # public access (limited to this backend only)
5523 backend public_www
5524 server srv1 192.168.0.1:80
5525 stats enable
5526 stats hide-version
5527 stats scope .
5528 stats uri /admin?stats
5529 stats realm Haproxy\ Statistics
5530 stats auth admin1:AdMiN123
5531 stats auth admin2:AdMiN321
5532
5533 # internal monitoring access (unlimited)
5534 backend private_monitoring
5535 stats enable
5536 stats uri /admin?stats
5537 stats refresh 5s
5538
5539 See also : "stats auth", "stats enable", "stats realm"
5540
5541
Willy Tarreaud63335a2010-02-26 12:56:52 +01005542stick match <pattern> [table <table>] [{if | unless} <cond>]
5543 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005544 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +01005545 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005546
5547 Arguments :
5548 <pattern> is a pattern extraction rule as described in section 7.8. It
5549 describes what elements of the incoming request or connection
5550 will be analysed in the hope to find a matching entry in a
5551 stickiness table. This rule is mandatory.
5552
5553 <table> is an optional stickiness table name. If unspecified, the same
5554 backend's table is used. A stickiness table is declared using
5555 the "stick-table" statement.
5556
5557 <cond> is an optional matching condition. It makes it possible to match
5558 on a certain criterion only when other conditions are met (or
5559 not met). For instance, it could be used to match on a source IP
5560 address except when a request passes through a known proxy, in
5561 which case we'd match on a header containing that IP address.
5562
5563 Some protocols or applications require complex stickiness rules and cannot
5564 always simply rely on cookies nor hashing. The "stick match" statement
5565 describes a rule to extract the stickiness criterion from an incoming request
5566 or connection. See section 7 for a complete list of possible patterns and
5567 transformation rules.
5568
5569 The table has to be declared using the "stick-table" statement. It must be of
5570 a type compatible with the pattern. By default it is the one which is present
5571 in the same backend. It is possible to share a table with other backends by
5572 referencing it using the "table" keyword. If another table is referenced,
5573 the server's ID inside the backends are used. By default, all server IDs
5574 start at 1 in each backend, so the server ordering is enough. But in case of
5575 doubt, it is highly recommended to force server IDs using their "id" setting.
5576
5577 It is possible to restrict the conditions where a "stick match" statement
5578 will apply, using "if" or "unless" followed by a condition. See section 7 for
5579 ACL based conditions.
5580
5581 There is no limit on the number of "stick match" statements. The first that
5582 applies and matches will cause the request to be directed to the same server
5583 as was used for the request which created the entry. That way, multiple
5584 matches can be used as fallbacks.
5585
5586 The stick rules are checked after the persistence cookies, so they will not
5587 affect stickiness if a cookie has already been used to select a server. That
5588 way, it becomes very easy to insert cookies and match on IP addresses in
5589 order to maintain stickiness between HTTP and HTTPS.
5590
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005591 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5592 unless you know what you do : memory is not shared between the
5593 processes, which can result in random behaviours.
5594
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005595 Example :
5596 # forward SMTP users to the same server they just used for POP in the
5597 # last 30 minutes
5598 backend pop
5599 mode tcp
5600 balance roundrobin
5601 stick store-request src
5602 stick-table type ip size 200k expire 30m
5603 server s1 192.168.1.1:110
5604 server s2 192.168.1.1:110
5605
5606 backend smtp
5607 mode tcp
5608 balance roundrobin
5609 stick match src table pop
5610 server s1 192.168.1.1:25
5611 server s2 192.168.1.1:25
5612
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005613 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
5614 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005615
5616
5617stick on <pattern> [table <table>] [{if | unless} <condition>]
5618 Define a request pattern to associate a user to a server
5619 May be used in sections : defaults | frontend | listen | backend
5620 no | no | yes | yes
5621
5622 Note : This form is exactly equivalent to "stick match" followed by
5623 "stick store-request", all with the same arguments. Please refer
5624 to both keywords for details. It is only provided as a convenience
5625 for writing more maintainable configurations.
5626
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005627 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5628 unless you know what you do : memory is not shared between the
5629 processes, which can result in random behaviours.
5630
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005631 Examples :
5632 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +01005633 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005634
5635 # ...is strictly equivalent to this one :
5636 stick match src table pop if !localhost
5637 stick store-request src table pop if !localhost
5638
5639
5640 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
5641 # well as HTTP without cookie. Share the same table between both accesses.
5642 backend http
5643 mode http
5644 balance roundrobin
5645 stick on src table https
5646 cookie SRV insert indirect nocache
5647 server s1 192.168.1.1:80 cookie s1
5648 server s2 192.168.1.1:80 cookie s2
5649
5650 backend https
5651 mode tcp
5652 balance roundrobin
5653 stick-table type ip size 200k expire 30m
5654 stick on src
5655 server s1 192.168.1.1:443
5656 server s2 192.168.1.1:443
5657
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005658 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005659
5660
5661stick store-request <pattern> [table <table>] [{if | unless} <condition>]
5662 Define a request pattern used to create an entry in a stickiness table
5663 May be used in sections : defaults | frontend | listen | backend
5664 no | no | yes | yes
5665
5666 Arguments :
5667 <pattern> is a pattern extraction rule as described in section 7.8. It
5668 describes what elements of the incoming request or connection
5669 will be analysed, extracted and stored in the table once a
5670 server is selected.
5671
5672 <table> is an optional stickiness table name. If unspecified, the same
5673 backend's table is used. A stickiness table is declared using
5674 the "stick-table" statement.
5675
5676 <cond> is an optional storage condition. It makes it possible to store
5677 certain criteria only when some conditions are met (or not met).
5678 For instance, it could be used to store the source IP address
5679 except when the request passes through a known proxy, in which
5680 case we'd store a converted form of a header containing that IP
5681 address.
5682
5683 Some protocols or applications require complex stickiness rules and cannot
5684 always simply rely on cookies nor hashing. The "stick store-request" statement
5685 describes a rule to decide what to extract from the request and when to do
5686 it, in order to store it into a stickiness table for further requests to
5687 match it using the "stick match" statement. Obviously the extracted part must
5688 make sense and have a chance to be matched in a further request. Storing a
5689 client's IP address for instance often makes sense. Storing an ID found in a
5690 URL parameter also makes sense. Storing a source port will almost never make
5691 any sense because it will be randomly matched. See section 7 for a complete
5692 list of possible patterns and transformation rules.
5693
5694 The table has to be declared using the "stick-table" statement. It must be of
5695 a type compatible with the pattern. By default it is the one which is present
5696 in the same backend. It is possible to share a table with other backends by
5697 referencing it using the "table" keyword. If another table is referenced,
5698 the server's ID inside the backends are used. By default, all server IDs
5699 start at 1 in each backend, so the server ordering is enough. But in case of
5700 doubt, it is highly recommended to force server IDs using their "id" setting.
5701
5702 It is possible to restrict the conditions where a "stick store-request"
5703 statement will apply, using "if" or "unless" followed by a condition. This
5704 condition will be evaluated while parsing the request, so any criteria can be
5705 used. See section 7 for ACL based conditions.
5706
5707 There is no limit on the number of "stick store-request" statements, but
5708 there is a limit of 8 simultaneous stores per request or response. This
5709 makes it possible to store up to 8 criteria, all extracted from either the
5710 request or the response, regardless of the number of rules. Only the 8 first
5711 ones which match will be kept. Using this, it is possible to feed multiple
5712 tables at once in the hope to increase the chance to recognize a user on
5713 another protocol or access method.
5714
5715 The "store-request" rules are evaluated once the server connection has been
5716 established, so that the table will contain the real server that processed
5717 the request.
5718
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005719 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5720 unless you know what you do : memory is not shared between the
5721 processes, which can result in random behaviours.
5722
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005723 Example :
5724 # forward SMTP users to the same server they just used for POP in the
5725 # last 30 minutes
5726 backend pop
5727 mode tcp
5728 balance roundrobin
5729 stick store-request src
5730 stick-table type ip size 200k expire 30m
5731 server s1 192.168.1.1:110
5732 server s2 192.168.1.1:110
5733
5734 backend smtp
5735 mode tcp
5736 balance roundrobin
5737 stick match src table pop
5738 server s1 192.168.1.1:25
5739 server s2 192.168.1.1:25
5740
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005741 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
5742 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005743
5744
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005745stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +02005746 size <size> [expire <expire>] [nopurge] [peers <peersect>]
5747 [store <data_type>]*
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005748 Configure the stickiness table for the current backend
5749 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +02005750 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005751
5752 Arguments :
5753 ip a table declared with "type ip" will only store IPv4 addresses.
5754 This form is very compact (about 50 bytes per entry) and allows
5755 very fast entry lookup and stores with almost no overhead. This
5756 is mainly used to store client source IP addresses.
5757
David du Colombier9a6d3c92011-03-17 10:40:24 +01005758 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
5759 This form is very compact (about 60 bytes per entry) and allows
5760 very fast entry lookup and stores with almost no overhead. This
5761 is mainly used to store client source IP addresses.
5762
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005763 integer a table declared with "type integer" will store 32bit integers
5764 which can represent a client identifier found in a request for
5765 instance.
5766
5767 string a table declared with "type string" will store substrings of up
5768 to <len> characters. If the string provided by the pattern
5769 extractor is larger than <len>, it will be truncated before
5770 being stored. During matching, at most <len> characters will be
5771 compared between the string in the table and the extracted
5772 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005773 to 32 characters.
5774
5775 binary a table declared with "type binary" will store binary blocks
5776 of <len> bytes. If the block provided by the pattern
5777 extractor is larger than <len>, it will be truncated before
5778 being stored. If the block provided by the pattern extractor
5779 is shorter than <len>, it will be padded by 0. When not
5780 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005781
5782 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005783 "string" type table (See type "string" above). Or the number
5784 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005785 changing this parameter as memory usage will proportionally
5786 increase.
5787
5788 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +01005789 value directly impacts memory usage. Count approximately
5790 50 bytes per entry, plus the size of a string if any. The size
5791 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005792
5793 [nopurge] indicates that we refuse to purge older entries when the table
5794 is full. When not specified and the table is full when haproxy
5795 wants to store an entry in it, it will flush a few of the oldest
5796 entries in order to release some space for the new ones. This is
5797 most often the desired behaviour. In some specific cases, it
5798 be desirable to refuse new entries instead of purging the older
5799 ones. That may be the case when the amount of data to store is
5800 far above the hardware limits and we prefer not to offer access
5801 to new clients than to reject the ones already connected. When
5802 using this parameter, be sure to properly set the "expire"
5803 parameter (see below).
5804
Emeric Brunf099e792010-09-27 12:05:28 +02005805 <peersect> is the name of the peers section to use for replication. Entries
5806 which associate keys to server IDs are kept synchronized with
5807 the remote peers declared in this section. All entries are also
5808 automatically learned from the local peer (old process) during a
5809 soft restart.
5810
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005811 NOTE : peers can't be used in multi-process mode.
5812
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005813 <expire> defines the maximum duration of an entry in the table since it
5814 was last created, refreshed or matched. The expiration delay is
5815 defined using the standard time format, similarly as the various
5816 timeouts. The maximum duration is slightly above 24 days. See
5817 section 2.2 for more information. If this delay is not specified,
Cyril Bontédc4d9032012-04-08 21:57:39 +02005818 the session won't automatically expire, but older entries will
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005819 be removed once full. Be sure not to use the "nopurge" parameter
5820 if not expiration delay is specified.
5821
Willy Tarreau08d5f982010-06-06 13:34:54 +02005822 <data_type> is used to store additional information in the stick-table. This
5823 may be used by ACLs in order to control various criteria related
5824 to the activity of the client matching the stick-table. For each
5825 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +02005826 that the additional data can fit. Several data types may be
5827 stored with an entry. Multiple data types may be specified after
5828 the "store" keyword, as a comma-separated list. Alternatively,
5829 it is possible to repeat the "store" keyword followed by one or
5830 several data types. Except for the "server_id" type which is
5831 automatically detected and enabled, all data types must be
5832 explicitly declared to be stored. If an ACL references a data
5833 type which is not stored, the ACL will simply not match. Some
5834 data types require an argument which must be passed just after
5835 the type between parenthesis. See below for the supported data
5836 types and their arguments.
5837
5838 The data types that can be stored with an entry are the following :
5839 - server_id : this is an integer which holds the numeric ID of the server a
5840 request was assigned to. It is used by the "stick match", "stick store",
5841 and "stick on" rules. It is automatically enabled when referenced.
5842
5843 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
5844 integer which may be used for anything. Most of the time it will be used
5845 to put a special tag on some entries, for instance to note that a
5846 specific behaviour was detected and must be known for future matches.
5847
5848 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
5849 the absolute number of connections received from clients which matched
5850 this entry. It does not mean the connections were accepted, just that
5851 they were received.
5852
5853 - conn_cur : Current Connections. It is a positive 32-bit integer which
5854 stores the concurrent connection counts for the entry. It is incremented
5855 once an incoming connection matches the entry, and decremented once the
5856 connection leaves. That way it is possible to know at any time the exact
5857 number of concurrent connections for an entry.
5858
5859 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5860 integer parameter <period> which indicates in milliseconds the length
5861 of the period over which the average is measured. It reports the average
5862 incoming connection rate over that period, in connections per period. The
5863 result is an integer which can be matched using ACLs.
5864
5865 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
5866 the absolute number of sessions received from clients which matched this
5867 entry. A session is a connection that was accepted by the layer 4 rules.
5868
5869 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5870 integer parameter <period> which indicates in milliseconds the length
5871 of the period over which the average is measured. It reports the average
5872 incoming session rate over that period, in sessions per period. The
5873 result is an integer which can be matched using ACLs.
5874
5875 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
5876 counts the absolute number of HTTP requests received from clients which
5877 matched this entry. It does not matter whether they are valid requests or
5878 not. Note that this is different from sessions when keep-alive is used on
5879 the client side.
5880
5881 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5882 integer parameter <period> which indicates in milliseconds the length
5883 of the period over which the average is measured. It reports the average
5884 HTTP request rate over that period, in requests per period. The result is
5885 an integer which can be matched using ACLs. It does not matter whether
5886 they are valid requests or not. Note that this is different from sessions
5887 when keep-alive is used on the client side.
5888
5889 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
5890 counts the absolute number of HTTP requests errors induced by clients
5891 which matched this entry. Errors are counted on invalid and truncated
5892 requests, as well as on denied or tarpitted requests, and on failed
5893 authentications. If the server responds with 4xx, then the request is
5894 also counted as an error since it's an error triggered by the client
5895 (eg: vulnerability scan).
5896
5897 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5898 integer parameter <period> which indicates in milliseconds the length
5899 of the period over which the average is measured. It reports the average
5900 HTTP request error rate over that period, in requests per period (see
5901 http_err_cnt above for what is accounted as an error). The result is an
5902 integer which can be matched using ACLs.
5903
5904 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
5905 integer which counts the cumulated amount of bytes received from clients
5906 which matched this entry. Headers are included in the count. This may be
5907 used to limit abuse of upload features on photo or video servers.
5908
5909 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5910 integer parameter <period> which indicates in milliseconds the length
5911 of the period over which the average is measured. It reports the average
5912 incoming bytes rate over that period, in bytes per period. It may be used
5913 to detect users which upload too much and too fast. Warning: with large
5914 uploads, it is possible that the amount of uploaded data will be counted
5915 once upon termination, thus causing spikes in the average transfer speed
5916 instead of having a smooth one. This may partially be smoothed with
5917 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
5918 recommended for better fairness.
5919
5920 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
5921 integer which counts the cumulated amount of bytes sent to clients which
5922 matched this entry. Headers are included in the count. This may be used
5923 to limit abuse of bots sucking the whole site.
5924
5925 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
5926 an integer parameter <period> which indicates in milliseconds the length
5927 of the period over which the average is measured. It reports the average
5928 outgoing bytes rate over that period, in bytes per period. It may be used
5929 to detect users which download too much and too fast. Warning: with large
5930 transfers, it is possible that the amount of transferred data will be
5931 counted once upon termination, thus causing spikes in the average
5932 transfer speed instead of having a smooth one. This may partially be
5933 smoothed with "option contstats" though this is not perfect yet. Use of
5934 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +02005935
Willy Tarreauc00cdc22010-06-06 16:48:26 +02005936 There is only one stick-table per proxy. At the moment of writing this doc,
5937 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005938 to be required, simply create a dummy backend with a stick-table in it and
5939 reference it.
5940
5941 It is important to understand that stickiness based on learning information
5942 has some limitations, including the fact that all learned associations are
5943 lost upon restart. In general it can be good as a complement but not always
5944 as an exclusive stickiness.
5945
Willy Tarreauc9705a12010-07-27 20:05:50 +02005946 Last, memory requirements may be important when storing many data types.
5947 Indeed, storing all indicators above at once in each entry requires 116 bytes
5948 per entry, or 116 MB for a 1-million entries table. This is definitely not
5949 something that can be ignored.
5950
5951 Example:
5952 # Keep track of counters of up to 1 million IP addresses over 5 minutes
5953 # and store a general purpose counter and the average connection rate
5954 # computed over a sliding window of 30 seconds.
5955 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
5956
5957 See also : "stick match", "stick on", "stick store-request", section 2.2
David du Colombiera13d1b92011-03-17 10:40:22 +01005958 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005959
5960
Emeric Brun6a1cefa2010-09-24 18:15:17 +02005961stick store-response <pattern> [table <table>] [{if | unless} <condition>]
5962 Define a request pattern used to create an entry in a stickiness table
5963 May be used in sections : defaults | frontend | listen | backend
5964 no | no | yes | yes
5965
5966 Arguments :
5967 <pattern> is a pattern extraction rule as described in section 7.8. It
5968 describes what elements of the response or connection will
5969 be analysed, extracted and stored in the table once a
5970 server is selected.
5971
5972 <table> is an optional stickiness table name. If unspecified, the same
5973 backend's table is used. A stickiness table is declared using
5974 the "stick-table" statement.
5975
5976 <cond> is an optional storage condition. It makes it possible to store
5977 certain criteria only when some conditions are met (or not met).
5978 For instance, it could be used to store the SSL session ID only
5979 when the response is a SSL server hello.
5980
5981 Some protocols or applications require complex stickiness rules and cannot
5982 always simply rely on cookies nor hashing. The "stick store-response"
5983 statement describes a rule to decide what to extract from the response and
5984 when to do it, in order to store it into a stickiness table for further
5985 requests to match it using the "stick match" statement. Obviously the
5986 extracted part must make sense and have a chance to be matched in a further
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005987 request. Storing an ID found in a header of a response makes sense.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02005988 See section 7 for a complete list of possible patterns and transformation
5989 rules.
5990
5991 The table has to be declared using the "stick-table" statement. It must be of
5992 a type compatible with the pattern. By default it is the one which is present
5993 in the same backend. It is possible to share a table with other backends by
5994 referencing it using the "table" keyword. If another table is referenced,
5995 the server's ID inside the backends are used. By default, all server IDs
5996 start at 1 in each backend, so the server ordering is enough. But in case of
5997 doubt, it is highly recommended to force server IDs using their "id" setting.
5998
5999 It is possible to restrict the conditions where a "stick store-response"
6000 statement will apply, using "if" or "unless" followed by a condition. This
6001 condition will be evaluated while parsing the response, so any criteria can
6002 be used. See section 7 for ACL based conditions.
6003
6004 There is no limit on the number of "stick store-response" statements, but
6005 there is a limit of 8 simultaneous stores per request or response. This
6006 makes it possible to store up to 8 criteria, all extracted from either the
6007 request or the response, regardless of the number of rules. Only the 8 first
6008 ones which match will be kept. Using this, it is possible to feed multiple
6009 tables at once in the hope to increase the chance to recognize a user on
6010 another protocol or access method.
6011
6012 The table will contain the real server that processed the request.
6013
6014 Example :
6015 # Learn SSL session ID from both request and response and create affinity.
6016 backend https
6017 mode tcp
6018 balance roundrobin
Cyril Bontédc4d9032012-04-08 21:57:39 +02006019 # maximum SSL session ID length is 32 bytes.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006020 stick-table type binary len 32 size 30k expire 30m
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006021
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006022 acl clienthello req_ssl_hello_type 1
6023 acl serverhello rep_ssl_hello_type 2
6024
6025 # use tcp content accepts to detects ssl client and server hello.
6026 tcp-request inspect-delay 5s
6027 tcp-request content accept if clienthello
6028
6029 # no timeout on response inspect delay by default.
6030 tcp-response content accept if serverhello
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006031
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006032 # SSL session ID (SSLID) may be present on a client or server hello.
6033 # Its length is coded on 1 byte at offset 43 and its value starts
6034 # at offset 44.
6035
6036 # Match and learn on request if client hello.
6037 stick on payload_lv(43,1) if clienthello
6038
6039 # Learn on response if server hello.
6040 stick store-response payload_lv(43,1) if serverhello
Cyril Bontédc4d9032012-04-08 21:57:39 +02006041
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006042 server s1 192.168.1.1:443
6043 server s2 192.168.1.1:443
6044
6045 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
6046 extraction.
6047
6048
Willy Tarreaue9656522010-08-17 15:40:09 +02006049tcp-request connection <action> [{if | unless} <condition>]
6050 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +02006051 May be used in sections : defaults | frontend | listen | backend
6052 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +02006053 Arguments :
6054 <action> defines the action to perform if the condition applies. Valid
6055 actions include : "accept", "reject", "track-sc1", "track-sc2".
6056 See below for more details.
Willy Tarreau1a687942010-05-23 22:40:30 +02006057
Willy Tarreaue9656522010-08-17 15:40:09 +02006058 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006059
6060 Immediately after acceptance of a new incoming connection, it is possible to
6061 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +02006062 or dropped or have its counters tracked. Those conditions cannot make use of
6063 any data contents because the connection has not been read from yet, and the
6064 buffers are not yet allocated. This is used to selectively and very quickly
6065 accept or drop connections from various sources with a very low overhead. If
6066 some contents need to be inspected in order to take the decision, the
6067 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006068
Willy Tarreaue9656522010-08-17 15:40:09 +02006069 The "tcp-request connection" rules are evaluated in their exact declaration
6070 order. If no rule matches or if there is no rule, the default action is to
6071 accept the incoming connection. There is no specific limit to the number of
6072 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006073
Willy Tarreaue9656522010-08-17 15:40:09 +02006074 Three types of actions are supported :
6075 - accept :
6076 accepts the connection if the condition is true (when used with "if")
6077 or false (when used with "unless"). The first such rule executed ends
6078 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006079
Willy Tarreaue9656522010-08-17 15:40:09 +02006080 - reject :
6081 rejects the connection if the condition is true (when used with "if")
6082 or false (when used with "unless"). The first such rule executed ends
6083 the rules evaluation. Rejected connections do not even become a
6084 session, which is why they are accounted separately for in the stats,
6085 as "denied connections". They are not considered for the session
6086 rate-limit and are not logged either. The reason is that these rules
6087 should only be used to filter extremely high connection rates such as
6088 the ones encountered during a massive DDoS attack. Under these extreme
6089 conditions, the simple action of logging each event would make the
6090 system collapse and would considerably lower the filtering capacity. If
6091 logging is absolutely desired, then "tcp-request content" rules should
6092 be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006093
Willy Tarreaue9656522010-08-17 15:40:09 +02006094 - { track-sc1 | track-sc2 } <key> [table <table>] :
6095 enables tracking of sticky counters from current connection. These
6096 rules do not stop evaluation and do not change default action. Two sets
6097 of counters may be simultaneously tracked by the same connection. The
6098 first "track-sc1" rule executed enables tracking of the counters of the
6099 specified table as the first set. The first "track-sc2" rule executed
6100 enables tracking of the counters of the specified table as the second
6101 set. It is a recommended practice to use the first set of counters for
6102 the per-frontend counters and the second set for the per-backend ones.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006103
Willy Tarreaue9656522010-08-17 15:40:09 +02006104 These actions take one or two arguments :
6105 <key> is mandatory, and defines the criterion the tracking key will
6106 be derived from. At the moment, only "src" is supported. With
6107 it, the key will be the connection's source IPv4 address.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006108
Willy Tarreaue9656522010-08-17 15:40:09 +02006109 <table> is an optional table to be used instead of the default one,
6110 which is the stick-table declared in the current proxy. All
6111 the counters for the matches and updates for the key will
6112 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006113
Willy Tarreaue9656522010-08-17 15:40:09 +02006114 Once a "track-sc*" rule is executed, the key is looked up in the table
6115 and if it is not found, an entry is allocated for it. Then a pointer to
6116 that entry is kept during all the session's life, and this entry's
6117 counters are updated as often as possible, every time the session's
6118 counters are updated, and also systematically when the session ends.
6119 If the entry tracks concurrent connection counters, one connection is
6120 counted for as long as the entry is tracked, and the entry will not
6121 expire during that time. Tracking counters also provides a performance
6122 advantage over just checking the keys, because only one table lookup is
6123 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006124
Willy Tarreaue9656522010-08-17 15:40:09 +02006125 Note that the "if/unless" condition is optional. If no condition is set on
6126 the action, it is simply performed unconditionally. That can be useful for
6127 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006128
Willy Tarreaue9656522010-08-17 15:40:09 +02006129 Example: accept all connections from white-listed hosts, reject too fast
6130 connection without counting them, and track accepted connections.
6131 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006132
Willy Tarreaue9656522010-08-17 15:40:09 +02006133 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006134 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaue9656522010-08-17 15:40:09 +02006135 tcp-request connection track-sc1 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006136
Willy Tarreaue9656522010-08-17 15:40:09 +02006137 Example: accept all connections from white-listed hosts, count all other
6138 connections and reject too fast ones. This results in abusive ones
6139 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006140
Willy Tarreaue9656522010-08-17 15:40:09 +02006141 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
6142 tcp-request connection track-sc1 src
6143 tcp-request connection reject if { sc1_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006144
6145 See section 7 about ACL usage.
6146
Willy Tarreaue9656522010-08-17 15:40:09 +02006147 See also : "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006148
6149
Willy Tarreaue9656522010-08-17 15:40:09 +02006150tcp-request content <action> [{if | unless} <condition>]
6151 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +02006152 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02006153 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +02006154 Arguments :
6155 <action> defines the action to perform if the condition applies. Valid
6156 actions include : "accept", "reject", "track-sc1", "track-sc2".
6157 See "tcp-request connection" above for their signification.
Willy Tarreau62644772008-07-16 18:36:06 +02006158
Willy Tarreaue9656522010-08-17 15:40:09 +02006159 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +02006160
Willy Tarreaue9656522010-08-17 15:40:09 +02006161 A request's contents can be analysed at an early stage of request processing
6162 called "TCP content inspection". During this stage, ACL-based rules are
6163 evaluated every time the request contents are updated, until either an
6164 "accept" or a "reject" rule matches, or the TCP request inspection delay
6165 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +02006166
Willy Tarreaue9656522010-08-17 15:40:09 +02006167 The first difference between these rules and "tcp-request connection" rules
6168 is that "tcp-request content" rules can make use of contents to take a
6169 decision. Most often, these decisions will consider a protocol recognition or
6170 validity. The second difference is that content-based rules can be used in
6171 both frontends and backends. In frontends, they will be evaluated upon new
6172 connections. In backends, they will be evaluated once a session is assigned
6173 a backend. This means that a single frontend connection may be evaluated
6174 several times by one or multiple backends when a session gets reassigned
6175 (for instance after a client-side HTTP keep-alive request).
Willy Tarreau62644772008-07-16 18:36:06 +02006176
Willy Tarreaue9656522010-08-17 15:40:09 +02006177 Content-based rules are evaluated in their exact declaration order. If no
6178 rule matches or if there is no rule, the default action is to accept the
6179 contents. There is no specific limit to the number of rules which may be
6180 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +02006181
Willy Tarreaue9656522010-08-17 15:40:09 +02006182 Three types of actions are supported :
6183 - accept :
6184 - reject :
6185 - { track-sc1 | track-sc2 } <key> [table <table>]
Willy Tarreau62644772008-07-16 18:36:06 +02006186
Willy Tarreaue9656522010-08-17 15:40:09 +02006187 They have the same meaning as their counter-parts in "tcp-request connection"
6188 so please refer to that section for a complete description.
Willy Tarreau62644772008-07-16 18:36:06 +02006189
Willy Tarreaue9656522010-08-17 15:40:09 +02006190 Also, it is worth noting that if sticky counters are tracked from a rule
6191 defined in a backend, this tracking will automatically end when the session
6192 releases the backend. That allows per-backend counter tracking even in case
6193 of HTTP keep-alive requests when the backend changes. While there is nothing
6194 mandatory about it, it is recommended to use the track-sc1 pointer to track
6195 per-frontend counters and track-sc2 to track per-backend counters.
Willy Tarreau62644772008-07-16 18:36:06 +02006196
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006197 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +02006198 the action, it is simply performed unconditionally. That can be useful for
6199 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +02006200
Willy Tarreaue9656522010-08-17 15:40:09 +02006201 It is perfectly possible to match layer 7 contents with "tcp-request content"
Willy Tarreauc0239e02012-04-16 14:42:55 +02006202 rules, since HTTP-specific ACL matches are able to preliminarily parse the
6203 contents of a buffer before extracting the required data. If the buffered
6204 contents do not parse as a valid HTTP message, then the ACL does not match.
6205 The parser which is involved there is exactly the same as for all other HTTP
6206 processing, so there is no risk of parsing something differently.
Willy Tarreau62644772008-07-16 18:36:06 +02006207
6208 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +02006209 # Accept HTTP requests containing a Host header saying "example.com"
6210 # and reject everything else.
6211 acl is_host_com hdr(Host) -i example.com
6212 tcp-request inspect-delay 30s
Willy Tarreauc0239e02012-04-16 14:42:55 +02006213 tcp-request content accept if is_host_com
Willy Tarreaue9656522010-08-17 15:40:09 +02006214 tcp-request content reject
6215
6216 Example:
Willy Tarreau62644772008-07-16 18:36:06 +02006217 # reject SMTP connection if client speaks first
6218 tcp-request inspect-delay 30s
6219 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006220 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +02006221
6222 # Forward HTTPS connection only if client speaks
6223 tcp-request inspect-delay 30s
6224 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006225 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +02006226 tcp-request content reject
6227
6228 Example: track per-frontend and per-backend counters, block abusers at the
6229 frontend when the backend detects abuse.
6230
6231 frontend http
6232 # Use General Purpose Couter 0 in SC1 as a global abuse counter
6233 # protecting all our sites
6234 stick-table type ip size 1m expire 5m store gpc0
6235 tcp-request connection track-sc1 src
6236 tcp-request connection reject if { sc1_get_gpc0 gt 0 }
6237 ...
6238 use_backend http_dynamic if { path_end .php }
6239
6240 backend http_dynamic
6241 # if a source makes too fast requests to this dynamic site (tracked
6242 # by SC2), block it globally in the frontend.
6243 stick-table type ip size 1m expire 5m store http_req_rate(10s)
6244 acl click_too_fast sc2_http_req_rate gt 10
6245 acl mark_as_abuser sc1_inc_gpc0
6246 tcp-request content track-sc2 src
6247 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +02006248
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006249 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02006250
Willy Tarreaue9656522010-08-17 15:40:09 +02006251 See also : "tcp-request connection", "tcp-request inspect-delay"
Willy Tarreau62644772008-07-16 18:36:06 +02006252
6253
6254tcp-request inspect-delay <timeout>
6255 Set the maximum allowed time to wait for data during content inspection
6256 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02006257 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +02006258 Arguments :
6259 <timeout> is the timeout value specified in milliseconds by default, but
6260 can be in any other unit if the number is suffixed by the unit,
6261 as explained at the top of this document.
6262
6263 People using haproxy primarily as a TCP relay are often worried about the
6264 risk of passing any type of protocol to a server without any analysis. In
6265 order to be able to analyze the request contents, we must first withhold
6266 the data then analyze them. This statement simply enables withholding of
6267 data for at most the specified amount of time.
6268
Willy Tarreaufb356202010-08-03 14:02:05 +02006269 TCP content inspection applies very early when a connection reaches a
6270 frontend, then very early when the connection is forwarded to a backend. This
6271 means that a connection may experience a first delay in the frontend and a
6272 second delay in the backend if both have tcp-request rules.
6273
Willy Tarreau62644772008-07-16 18:36:06 +02006274 Note that when performing content inspection, haproxy will evaluate the whole
6275 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006276 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +02006277 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +01006278 contents are definitive. If no delay is set, haproxy will not wait at all
6279 and will immediately apply a verdict based on the available information.
6280 Obviously this is unlikely to be very useful and might even be racy, so such
6281 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +02006282
6283 As soon as a rule matches, the request is released and continues as usual. If
6284 the timeout is reached and no rule matches, the default policy will be to let
6285 it pass through unaffected.
6286
6287 For most protocols, it is enough to set it to a few seconds, as most clients
6288 send the full request immediately upon connection. Add 3 or more seconds to
6289 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +01006290 to use large values, for instance to ensure that the client never talks
Willy Tarreau62644772008-07-16 18:36:06 +02006291 before the server (eg: SMTP), or to wait for a client to talk before passing
6292 data to the server (eg: SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +02006293 least the inspection delay, otherwise it will expire first. If the client
6294 closes the connection or if the buffer is full, the delay immediately expires
6295 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +02006296
Willy Tarreau55165fe2009-05-10 12:02:55 +02006297 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +02006298 "timeout client".
6299
6300
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006301tcp-response content <action> [{if | unless} <condition>]
6302 Perform an action on a session response depending on a layer 4-7 condition
6303 May be used in sections : defaults | frontend | listen | backend
6304 no | no | yes | yes
6305 Arguments :
6306 <action> defines the action to perform if the condition applies. Valid
6307 actions include : "accept", "reject".
6308 See "tcp-request connection" above for their signification.
6309
6310 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
6311
6312 Response contents can be analysed at an early stage of response processing
6313 called "TCP content inspection". During this stage, ACL-based rules are
6314 evaluated every time the response contents are updated, until either an
6315 "accept" or a "reject" rule matches, or a TCP response inspection delay is
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006316 set and expires with no matching rule.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006317
6318 Most often, these decisions will consider a protocol recognition or validity.
6319
6320 Content-based rules are evaluated in their exact declaration order. If no
6321 rule matches or if there is no rule, the default action is to accept the
6322 contents. There is no specific limit to the number of rules which may be
6323 inserted.
6324
6325 Two types of actions are supported :
6326 - accept :
6327 accepts the response if the condition is true (when used with "if")
6328 or false (when used with "unless"). The first such rule executed ends
6329 the rules evaluation.
6330
6331 - reject :
6332 rejects the response if the condition is true (when used with "if")
6333 or false (when used with "unless"). The first such rule executed ends
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006334 the rules evaluation. Rejected session are immediately closed.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006335
6336 Note that the "if/unless" condition is optional. If no condition is set on
6337 the action, it is simply performed unconditionally. That can be useful for
6338 for changing the default action to a reject.
6339
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006340 It is perfectly possible to match layer 7 contents with "tcp-response
6341 content" rules, but then it is important to ensure that a full response has
6342 been buffered, otherwise no contents will match. In order to achieve this,
6343 the best solution involves detecting the HTTP protocol during the inspection
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006344 period.
6345
6346 See section 7 about ACL usage.
6347
6348 See also : "tcp-request content", "tcp-response inspect-delay"
6349
6350
6351tcp-response inspect-delay <timeout>
6352 Set the maximum allowed time to wait for a response during content inspection
6353 May be used in sections : defaults | frontend | listen | backend
6354 no | no | yes | yes
6355 Arguments :
6356 <timeout> is the timeout value specified in milliseconds by default, but
6357 can be in any other unit if the number is suffixed by the unit,
6358 as explained at the top of this document.
6359
6360 See also : "tcp-response content", "tcp-request inspect-delay".
6361
6362
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006363timeout check <timeout>
6364 Set additional check timeout, but only after a connection has been already
6365 established.
6366
6367 May be used in sections: defaults | frontend | listen | backend
6368 yes | no | yes | yes
6369 Arguments:
6370 <timeout> is the timeout value specified in milliseconds by default, but
6371 can be in any other unit if the number is suffixed by the unit,
6372 as explained at the top of this document.
6373
6374 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
6375 for check and "timeout check" as an additional read timeout. The "min" is
6376 used so that people running with *very* long "timeout connect" (eg. those
6377 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +01006378 (Please also note that there is no valid reason to have such long connect
6379 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
6380 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006381
6382 If "timeout check" is not set haproxy uses "inter" for complete check
6383 timeout (connect + read) exactly like all <1.3.15 version.
6384
6385 In most cases check request is much simpler and faster to handle than normal
6386 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +01006387 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006388
6389 This parameter is specific to backends, but can be specified once for all in
6390 "defaults" sections. This is in fact one of the easiest solutions not to
6391 forget about it.
6392
Willy Tarreau41a340d2008-01-22 12:25:31 +01006393 See also: "timeout connect", "timeout queue", "timeout server",
6394 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006395
6396
Willy Tarreau0ba27502007-12-24 16:55:16 +01006397timeout client <timeout>
6398timeout clitimeout <timeout> (deprecated)
6399 Set the maximum inactivity time on the client side.
6400 May be used in sections : defaults | frontend | listen | backend
6401 yes | yes | yes | no
6402 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006403 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01006404 can be in any other unit if the number is suffixed by the unit,
6405 as explained at the top of this document.
6406
6407 The inactivity timeout applies when the client is expected to acknowledge or
6408 send data. In HTTP mode, this timeout is particularly important to consider
6409 during the first phase, when the client sends the request, and during the
6410 response while it is reading data sent by the server. The value is specified
6411 in milliseconds by default, but can be in any other unit if the number is
6412 suffixed by the unit, as specified at the top of this document. In TCP mode
6413 (and to a lesser extent, in HTTP mode), it is highly recommended that the
6414 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006415 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01006416 losses by specifying timeouts that are slightly above multiples of 3 seconds
Willy Tarreauce887fd2012-05-12 12:50:00 +02006417 (eg: 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
6418 sessions (eg: WebSocket and HTTP), it's worth considering "timeout tunnel",
6419 which overrides "timeout client" and "timeout server" for tunnels.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006420
6421 This parameter is specific to frontends, but can be specified once for all in
6422 "defaults" sections. This is in fact one of the easiest solutions not to
6423 forget about it. An unspecified timeout results in an infinite timeout, which
6424 is not recommended. Such a usage is accepted and works but reports a warning
6425 during startup because it may results in accumulation of expired sessions in
6426 the system if the system's timeouts are not configured either.
6427
6428 This parameter replaces the old, deprecated "clitimeout". It is recommended
6429 to use it to write new configurations. The form "timeout clitimeout" is
6430 provided only by backwards compatibility but its use is strongly discouraged.
6431
Willy Tarreauce887fd2012-05-12 12:50:00 +02006432 See also : "clitimeout", "timeout server", "timeout tunnel".
Willy Tarreau0ba27502007-12-24 16:55:16 +01006433
6434
6435timeout connect <timeout>
6436timeout contimeout <timeout> (deprecated)
6437 Set the maximum time to wait for a connection attempt to a server to succeed.
6438 May be used in sections : defaults | frontend | listen | backend
6439 yes | no | yes | yes
6440 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006441 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01006442 can be in any other unit if the number is suffixed by the unit,
6443 as explained at the top of this document.
6444
6445 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006446 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01006447 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01006448 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006449 connect timeout also presets both queue and tarpit timeouts to the same value
6450 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006451
6452 This parameter is specific to backends, but can be specified once for all in
6453 "defaults" sections. This is in fact one of the easiest solutions not to
6454 forget about it. An unspecified timeout results in an infinite timeout, which
6455 is not recommended. Such a usage is accepted and works but reports a warning
6456 during startup because it may results in accumulation of failed sessions in
6457 the system if the system's timeouts are not configured either.
6458
6459 This parameter replaces the old, deprecated "contimeout". It is recommended
6460 to use it to write new configurations. The form "timeout contimeout" is
6461 provided only by backwards compatibility but its use is strongly discouraged.
6462
Willy Tarreau41a340d2008-01-22 12:25:31 +01006463 See also: "timeout check", "timeout queue", "timeout server", "contimeout",
6464 "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +01006465
6466
Willy Tarreaub16a5742010-01-10 14:46:16 +01006467timeout http-keep-alive <timeout>
6468 Set the maximum allowed time to wait for a new HTTP request to appear
6469 May be used in sections : defaults | frontend | listen | backend
6470 yes | yes | yes | yes
6471 Arguments :
6472 <timeout> is the timeout value specified in milliseconds by default, but
6473 can be in any other unit if the number is suffixed by the unit,
6474 as explained at the top of this document.
6475
6476 By default, the time to wait for a new request in case of keep-alive is set
6477 by "timeout http-request". However this is not always convenient because some
6478 people want very short keep-alive timeouts in order to release connections
6479 faster, and others prefer to have larger ones but still have short timeouts
6480 once the request has started to present itself.
6481
6482 The "http-keep-alive" timeout covers these needs. It will define how long to
6483 wait for a new HTTP request to start coming after a response was sent. Once
6484 the first byte of request has been seen, the "http-request" timeout is used
6485 to wait for the complete request to come. Note that empty lines prior to a
6486 new request do not refresh the timeout and are not counted as a new request.
6487
6488 There is also another difference between the two timeouts : when a connection
6489 expires during timeout http-keep-alive, no error is returned, the connection
6490 just closes. If the connection expires in "http-request" while waiting for a
6491 connection to complete, a HTTP 408 error is returned.
6492
6493 In general it is optimal to set this value to a few tens to hundreds of
6494 milliseconds, to allow users to fetch all objects of a page at once but
6495 without waiting for further clicks. Also, if set to a very small value (eg:
6496 1 millisecond) it will probably only accept pipelined requests but not the
6497 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +02006498 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +01006499
6500 If this parameter is not set, the "http-request" timeout applies, and if both
6501 are not set, "timeout client" still applies at the lower level. It should be
6502 set in the frontend to take effect, unless the frontend is in TCP mode, in
6503 which case the HTTP backend's timeout will be used.
6504
6505 See also : "timeout http-request", "timeout client".
6506
6507
Willy Tarreau036fae02008-01-06 13:24:40 +01006508timeout http-request <timeout>
6509 Set the maximum allowed time to wait for a complete HTTP request
6510 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +02006511 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +01006512 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006513 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +01006514 can be in any other unit if the number is suffixed by the unit,
6515 as explained at the top of this document.
6516
6517 In order to offer DoS protection, it may be required to lower the maximum
6518 accepted time to receive a complete HTTP request without affecting the client
6519 timeout. This helps protecting against established connections on which
6520 nothing is sent. The client timeout cannot offer a good protection against
6521 this abuse because it is an inactivity timeout, which means that if the
6522 attacker sends one character every now and then, the timeout will not
6523 trigger. With the HTTP request timeout, no matter what speed the client
6524 types, the request will be aborted if it does not complete in time.
6525
6526 Note that this timeout only applies to the header part of the request, and
6527 not to any data. As soon as the empty line is received, this timeout is not
Willy Tarreaub16a5742010-01-10 14:46:16 +01006528 used anymore. It is used again on keep-alive connections to wait for a second
6529 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +01006530
6531 Generally it is enough to set it to a few seconds, as most clients send the
6532 full request immediately upon connection. Add 3 or more seconds to cover TCP
6533 retransmits but that's all. Setting it to very low values (eg: 50 ms) will
6534 generally work on local networks as long as there are no packet losses. This
6535 will prevent people from sending bare HTTP requests using telnet.
6536
6537 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +02006538 chunk of the incoming request. It should be set in the frontend to take
6539 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
6540 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +01006541
Willy Tarreaub16a5742010-01-10 14:46:16 +01006542 See also : "timeout http-keep-alive", "timeout client".
Willy Tarreau036fae02008-01-06 13:24:40 +01006543
Willy Tarreau844e3c52008-01-11 16:28:18 +01006544
6545timeout queue <timeout>
6546 Set the maximum time to wait in the queue for a connection slot to be free
6547 May be used in sections : defaults | frontend | listen | backend
6548 yes | no | yes | yes
6549 Arguments :
6550 <timeout> is the timeout value specified in milliseconds by default, but
6551 can be in any other unit if the number is suffixed by the unit,
6552 as explained at the top of this document.
6553
6554 When a server's maxconn is reached, connections are left pending in a queue
6555 which may be server-specific or global to the backend. In order not to wait
6556 indefinitely, a timeout is applied to requests pending in the queue. If the
6557 timeout is reached, it is considered that the request will almost never be
6558 served, so it is dropped and a 503 error is returned to the client.
6559
6560 The "timeout queue" statement allows to fix the maximum time for a request to
6561 be left pending in a queue. If unspecified, the same value as the backend's
6562 connection timeout ("timeout connect") is used, for backwards compatibility
6563 with older versions with no "timeout queue" parameter.
6564
6565 See also : "timeout connect", "contimeout".
6566
6567
6568timeout server <timeout>
6569timeout srvtimeout <timeout> (deprecated)
6570 Set the maximum inactivity time on the server side.
6571 May be used in sections : defaults | frontend | listen | backend
6572 yes | no | yes | yes
6573 Arguments :
6574 <timeout> is the timeout value specified in milliseconds by default, but
6575 can be in any other unit if the number is suffixed by the unit,
6576 as explained at the top of this document.
6577
6578 The inactivity timeout applies when the server is expected to acknowledge or
6579 send data. In HTTP mode, this timeout is particularly important to consider
6580 during the first phase of the server's response, when it has to send the
6581 headers, as it directly represents the server's processing time for the
6582 request. To find out what value to put there, it's often good to start with
6583 what would be considered as unacceptable response times, then check the logs
6584 to observe the response time distribution, and adjust the value accordingly.
6585
6586 The value is specified in milliseconds by default, but can be in any other
6587 unit if the number is suffixed by the unit, as specified at the top of this
6588 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
6589 recommended that the client timeout remains equal to the server timeout in
6590 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006591 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01006592 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreauce887fd2012-05-12 12:50:00 +02006593 seconds (eg: 4 or 5 seconds minimum). If some long-lived sessions are mixed
6594 with short-lived sessions (eg: WebSocket and HTTP), it's worth considering
6595 "timeout tunnel", which overrides "timeout client" and "timeout server" for
6596 tunnels.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006597
6598 This parameter is specific to backends, but can be specified once for all in
6599 "defaults" sections. This is in fact one of the easiest solutions not to
6600 forget about it. An unspecified timeout results in an infinite timeout, which
6601 is not recommended. Such a usage is accepted and works but reports a warning
6602 during startup because it may results in accumulation of expired sessions in
6603 the system if the system's timeouts are not configured either.
6604
6605 This parameter replaces the old, deprecated "srvtimeout". It is recommended
6606 to use it to write new configurations. The form "timeout srvtimeout" is
6607 provided only by backwards compatibility but its use is strongly discouraged.
6608
Willy Tarreauce887fd2012-05-12 12:50:00 +02006609 See also : "srvtimeout", "timeout client" and "timeout tunnel".
Willy Tarreau844e3c52008-01-11 16:28:18 +01006610
6611
6612timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +01006613 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +01006614 May be used in sections : defaults | frontend | listen | backend
6615 yes | yes | yes | yes
6616 Arguments :
6617 <timeout> is the tarpit duration specified in milliseconds by default, but
6618 can be in any other unit if the number is suffixed by the unit,
6619 as explained at the top of this document.
6620
6621 When a connection is tarpitted using "reqtarpit", it is maintained open with
6622 no activity for a certain amount of time, then closed. "timeout tarpit"
6623 defines how long it will be maintained open.
6624
6625 The value is specified in milliseconds by default, but can be in any other
6626 unit if the number is suffixed by the unit, as specified at the top of this
6627 document. If unspecified, the same value as the backend's connection timeout
6628 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +01006629 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006630
6631 See also : "timeout connect", "contimeout".
6632
6633
Willy Tarreauce887fd2012-05-12 12:50:00 +02006634timeout tunnel <timeout>
6635 Set the maximum inactivity time on the client and server side for tunnels.
6636 May be used in sections : defaults | frontend | listen | backend
6637 yes | no | yes | yes
6638 Arguments :
6639 <timeout> is the timeout value specified in milliseconds by default, but
6640 can be in any other unit if the number is suffixed by the unit,
6641 as explained at the top of this document.
6642
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006643 The tunnel timeout applies when a bidirectional connection is established
Willy Tarreauce887fd2012-05-12 12:50:00 +02006644 between a client and a server, and the connection remains inactive in both
6645 directions. This timeout supersedes both the client and server timeouts once
6646 the connection becomes a tunnel. In TCP, this timeout is used as soon as no
6647 analyser remains attached to either connection (eg: tcp content rules are
6648 accepted). In HTTP, this timeout is used when a connection is upgraded (eg:
6649 when switching to the WebSocket protocol, or forwarding a CONNECT request
6650 to a proxy), or after the first response when no keepalive/close option is
6651 specified.
6652
6653 The value is specified in milliseconds by default, but can be in any other
6654 unit if the number is suffixed by the unit, as specified at the top of this
6655 document. Whatever the expected normal idle time, it is a good practice to
6656 cover at least one or several TCP packet losses by specifying timeouts that
6657 are slightly above multiples of 3 seconds (eg: 4 or 5 seconds minimum).
6658
6659 This parameter is specific to backends, but can be specified once for all in
6660 "defaults" sections. This is in fact one of the easiest solutions not to
6661 forget about it.
6662
6663 Example :
6664 defaults http
6665 option http-server-close
6666 timeout connect 5s
6667 timeout client 30s
6668 timeout client 30s
6669 timeout server 30s
6670 timeout tunnel 1h # timeout to use with WebSocket and CONNECT
6671
6672 See also : "timeout client", "timeout server".
6673
6674
Willy Tarreau844e3c52008-01-11 16:28:18 +01006675transparent (deprecated)
6676 Enable client-side transparent proxying
6677 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01006678 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01006679 Arguments : none
6680
6681 This keyword was introduced in order to provide layer 7 persistence to layer
6682 3 load balancers. The idea is to use the OS's ability to redirect an incoming
6683 connection for a remote address to a local process (here HAProxy), and let
6684 this process know what address was initially requested. When this option is
6685 used, sessions without cookies will be forwarded to the original destination
6686 IP address of the incoming request (which should match that of another
6687 equipment), while requests with cookies will still be forwarded to the
6688 appropriate server.
6689
6690 The "transparent" keyword is deprecated, use "option transparent" instead.
6691
6692 Note that contrary to a common belief, this option does NOT make HAProxy
6693 present the client's IP to the server when establishing the connection.
6694
Willy Tarreau844e3c52008-01-11 16:28:18 +01006695 See also: "option transparent"
6696
William Lallemanda73203e2012-03-12 12:48:57 +01006697unique-id-format <string>
6698 Generate a unique ID for each request.
6699 May be used in sections : defaults | frontend | listen | backend
6700 yes | yes | yes | no
6701 Arguments :
6702 <string> is a log-format string.
6703
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006704 This keyword creates a ID for each request using the custom log format. A
6705 unique ID is useful to trace a request passing through many components of
6706 a complex infrastructure. The newly created ID may also be logged using the
6707 %ID tag the log-format string.
William Lallemanda73203e2012-03-12 12:48:57 +01006708
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006709 The format should be composed from elements that are guaranteed to be
6710 unique when combined together. For instance, if multiple haproxy instances
6711 are involved, it might be important to include the node name. It is often
6712 needed to log the incoming connection's source and destination addresses
6713 and ports. Note that since multiple requests may be performed over the same
6714 connection, including a request counter may help differentiate them.
6715 Similarly, a timestamp may protect against a rollover of the counter.
6716 Logging the process ID will avoid collisions after a service restart.
William Lallemanda73203e2012-03-12 12:48:57 +01006717
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006718 It is recommended to use hexadecimal notation for many fields since it
6719 makes them more compact and saves space in logs.
William Lallemanda73203e2012-03-12 12:48:57 +01006720
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006721 Example:
William Lallemanda73203e2012-03-12 12:48:57 +01006722
6723 unique-id-format %{+X}o\ %Ci:%Cp_%Fi:%Fp_%Ts_%rt:%pid
6724
6725 will generate:
6726
6727 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
6728
6729 See also: "unique-id-header"
6730
6731unique-id-header <name>
6732 Add a unique ID header in the HTTP request.
6733 May be used in sections : defaults | frontend | listen | backend
6734 yes | yes | yes | no
6735 Arguments :
6736 <name> is the name of the header.
6737
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006738 Add a unique-id header in the HTTP request sent to the server, using the
6739 unique-id-format. It can't work if the unique-id-format doesn't exist.
William Lallemanda73203e2012-03-12 12:48:57 +01006740
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006741 Example:
William Lallemanda73203e2012-03-12 12:48:57 +01006742
6743 unique-id-format %{+X}o\ %Ci:%Cp_%Fi:%Fp_%Ts_%rt:%pid
6744 unique-id-header X-Unique-ID
6745
6746 will generate:
6747
6748 X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
6749
6750 See also: "unique-id-format"
Willy Tarreau844e3c52008-01-11 16:28:18 +01006751
6752use_backend <backend> if <condition>
6753use_backend <backend> unless <condition>
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006754 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006755 May be used in sections : defaults | frontend | listen | backend
6756 no | yes | yes | no
6757 Arguments :
6758 <backend> is the name of a valid backend or "listen" section.
6759
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006760 <condition> is a condition composed of ACLs, as described in section 7.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006761
6762 When doing content-switching, connections arrive on a frontend and are then
6763 dispatched to various backends depending on a number of conditions. The
6764 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006765 "use_backend" keyword. While it is normally used with HTTP processing, it can
6766 also be used in pure TCP, either without content using stateless ACLs (eg:
6767 source address validation) or combined with a "tcp-request" rule to wait for
6768 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006769
6770 There may be as many "use_backend" rules as desired. All of these rules are
6771 evaluated in their declaration order, and the first one which matches will
6772 assign the backend.
6773
6774 In the first form, the backend will be used if the condition is met. In the
6775 second form, the backend will be used if the condition is not met. If no
6776 condition is valid, the backend defined with "default_backend" will be used.
6777 If no default backend is defined, either the servers in the same section are
6778 used (in case of a "listen" section) or, in case of a frontend, no server is
6779 used and a 503 service unavailable response is returned.
6780
Willy Tarreau51aecc72009-07-12 09:47:04 +02006781 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006782 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +02006783 and backend processing will immediately follow, or the backend will wait for
6784 a complete HTTP request to get in. This feature is useful when a frontend
6785 must decode several protocols on a unique port, one of them being HTTP.
6786
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006787 See also: "default_backend", "tcp-request", and section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +01006788
Willy Tarreau036fae02008-01-06 13:24:40 +01006789
Willy Tarreau4a5cade2012-04-05 21:09:48 +02006790use-server <server> if <condition>
6791use-server <server> unless <condition>
6792 Only use a specific server if/unless an ACL-based condition is matched.
6793 May be used in sections : defaults | frontend | listen | backend
6794 no | no | yes | yes
6795 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006796 <server> is the name of a valid server in the same backend section.
Willy Tarreau4a5cade2012-04-05 21:09:48 +02006797
6798 <condition> is a condition composed of ACLs, as described in section 7.
6799
6800 By default, connections which arrive to a backend are load-balanced across
6801 the available servers according to the configured algorithm, unless a
6802 persistence mechanism such as a cookie is used and found in the request.
6803
6804 Sometimes it is desirable to forward a particular request to a specific
6805 server without having to declare a dedicated backend for this server. This
6806 can be achieved using the "use-server" rules. These rules are evaluated after
6807 the "redirect" rules and before evaluating cookies, and they have precedence
6808 on them. There may be as many "use-server" rules as desired. All of these
6809 rules are evaluated in their declaration order, and the first one which
6810 matches will assign the server.
6811
6812 If a rule designates a server which is down, and "option persist" is not used
6813 and no force-persist rule was validated, it is ignored and evaluation goes on
6814 with the next rules until one matches.
6815
6816 In the first form, the server will be used if the condition is met. In the
6817 second form, the server will be used if the condition is not met. If no
6818 condition is valid, the processing continues and the server will be assigned
6819 according to other persistence mechanisms.
6820
6821 Note that even if a rule is matched, cookie processing is still performed but
6822 does not assign the server. This allows prefixed cookies to have their prefix
6823 stripped.
6824
6825 The "use-server" statement works both in HTTP and TCP mode. This makes it
6826 suitable for use with content-based inspection. For instance, a server could
6827 be selected in a farm according to the TLS SNI field. And if these servers
6828 have their weight set to zero, they will not be used for other traffic.
6829
6830 Example :
6831 # intercept incoming TLS requests based on the SNI field
6832 use-server www if { req_ssl_sni -i www.example.com }
6833 server www 192.168.0.1:443 weight 0
6834 use-server mail if { req_ssl_sni -i mail.example.com }
6835 server mail 192.168.0.1:587 weight 0
6836 use-server imap if { req_ssl_sni -i imap.example.com }
6837 server mail 192.168.0.1:993 weight 0
6838 # all the rest is forwarded to this server
6839 server default 192.168.0.2:443 check
6840
6841 See also: "use_backend", serction 5 about server and section 7 about ACLs.
6842
Willy Tarreaub6205fd2012-09-24 12:27:33 +02006843
68445. Bind and Server options
6845--------------------------
6846
6847The "bind", "server" and "default-server" keywords support a number of settings
6848depending on some build options and on the system HAProxy was built on. These
6849settings generally each consist in one word sometimes followed by a value,
6850written on the same line as the "bind" or "server" line. All these options are
6851described in this section.
6852
6853
68545.1. Bind options
6855-----------------
6856
6857The "bind" keyword supports a certain number of settings which are all passed
6858as arguments on the same line. The order in which those arguments appear makes
6859no importance, provided that they appear after the bind address. All of these
6860parameters are optional. Some of them consist in a single words (booleans),
6861while other ones expect a value after them. In this case, the value must be
6862provided immediately after the setting name.
6863
6864The currently supported settings are the following ones.
6865
6866accept-proxy
6867 Enforces the use of the PROXY protocol over any connection accepted by any of
6868 the sockets declared on the same line. The PROXY protocol dictates the layer
6869 3/4 addresses of the incoming connection to be used everywhere an address is
6870 used, with the only exception of "tcp-request connection" rules which will
6871 only see the real connection address. Logs will reflect the addresses
6872 indicated in the protocol, unless it is violated, in which case the real
6873 address will still be used. This keyword combined with support from external
6874 components can be used as an efficient and reliable alternative to the
6875 X-Forwarded-For mechanism which is not always reliable and not even always
6876 usable.
6877
6878backlog <backlog>
6879 Sets the socket's backlog to this value. If unspecified, the frontend's
6880 backlog is used instead, which generally defaults to the maxconn value.
6881
Emeric Brun7fb34422012-09-28 15:26:15 +02006882ecdhe <named curve>
6883 This setting is only available when support for OpenSSL was built in. It sets
6884 the named curve (RFC 4492) used to generate ECDH ephemeral keys and makes
6885 ECDHE cipher suites usable.
6886
Emeric Brunfd33a262012-10-11 16:28:27 +02006887ca-file <cafile>
Emeric Brun1a073b42012-09-28 17:07:34 +02006888 This setting is only available when support for OpenSSL was built in. It
6889 designates a PEM file from which to load CA certificates used to verify
6890 client's certificate.
6891
Emeric Brunb6dc9342012-09-28 17:55:37 +02006892ca-ignore-err [all|<errorID>,...]
6893 This setting is only available when support for OpenSSL was built in.
6894 Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
6895 If set to 'all', all errors are ignored. SSL handshake is not aborted if an
6896 error is ignored.
6897
Willy Tarreaub6205fd2012-09-24 12:27:33 +02006898ciphers <ciphers>
6899 This setting is only available when support for OpenSSL was built in. It sets
6900 the string describing the list of cipher algorithms ("cipher suite") that are
6901 negociated during the SSL/TLS handshake. The format of the string is defined
6902 in "man 1 ciphers" from OpenSSL man pages, and can be for instance a string
6903 such as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes).
6904
Emeric Brunfd33a262012-10-11 16:28:27 +02006905crl-file <crlfile>
Emeric Brun1a073b42012-09-28 17:07:34 +02006906 This setting is only available when support for OpenSSL was built in. It
6907 designates a PEM file from which to load certificate revocation list used
6908 to verify client's certificate.
6909
Willy Tarreaub6205fd2012-09-24 12:27:33 +02006910crt <cert>
6911 This setting is only available when support for OpenSSL was built in.
6912 It designates a PEM file from which to load both a certificate and the
6913 associated private key. This file can be built by concatenating both PEM
Emeric Brune032bfa2012-09-28 13:01:45 +02006914 files into one. If the OpenSSL used supports Diffie-Hellman, parameters
6915 present in this file are also loaded. If a directory name is used instead of a
6916 PEM file, then all files found in that directory will be loaded. This
6917 directive may be specified multiple times in order to load certificates from
6918 multiple files or directories. The certificates will be presented to clients
6919 who provide a valid TLS Server Name Indication field matching one of their CN
6920 or alt subjects. Wildcards are supported, where a wildcard character '*' is
6921 used instead of the first hostname component (eg: *.example.org matches
Willy Tarreaub6205fd2012-09-24 12:27:33 +02006922 www.example.org but not www.sub.example.org). If no SNI is provided by the
Emeric Brune032bfa2012-09-28 13:01:45 +02006923 client or if the SSL library does not support TLS extensions, or if the client
6924 provides and SNI which does not match any certificate, then the first loaded
6925 certificate will be presented. This means that when loading certificates from
6926 a directory, it is highly recommended to load the default one first as a file.
6927 Note that the same cert may be loaded multiple times without side effects.
Willy Tarreaub6205fd2012-09-24 12:27:33 +02006928
Emeric Brunb6dc9342012-09-28 17:55:37 +02006929crt-ignore-err <errors>
6930 This setting is only available when support for OpenSSL was built in.
6931 Sets a comma separated list of errorIDs to ignore during verify at depth == 0.
6932 If set to 'all', all errors are ignored. SSL handshake is not abored if an
6933 error is ignored.
6934
Willy Tarreaub6205fd2012-09-24 12:27:33 +02006935defer-accept
6936 Is an optional keyword which is supported only on certain Linux kernels. It
6937 states that a connection will only be accepted once some data arrive on it,
6938 or at worst after the first retransmit. This should be used only on protocols
6939 for which the client talks first (eg: HTTP). It can slightly improve
6940 performance by ensuring that most of the request is already available when
6941 the connection is accepted. On the other hand, it will not be able to detect
6942 connections which don't talk. It is important to note that this option is
6943 broken in all kernels up to 2.6.31, as the connection is never accepted until
6944 the client talks. This can cause issues with front firewalls which would see
6945 an established connection while the proxy will only see it in SYN_RECV. This
6946 option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
6947
Emeric Brun2cb7ae52012-10-05 14:14:21 +02006948force-sslv3
6949 This option enforces use of SSLv3 only on SSL connections instanciated from
6950 this listener. SSLv3 is generally less expensive than the TLS counterparts
6951 for high connection rates. See also "force-tls*", "no-sslv3", and "no-tls*".
6952
6953force-tlsv10
6954 This option enforces use of TLSv1.0 only on SSL connections instanciated from
6955 this listener. See also "force-tls*", "no-sslv3", and "no-tls*".
6956
6957force-tlsv11
6958 This option enforces use of TLSv1.1 only on SSL connections instanciated from
6959 this listener. See also "force-tls*", "no-sslv3", and "no-tls*".
6960
6961force-tlsv12
6962 This option enforces use of TLSv1.2 only on SSL connections instanciated from
6963 this listener. See also "force-tls*", "no-sslv3", and "no-tls*".
6964
Willy Tarreaub6205fd2012-09-24 12:27:33 +02006965gid <gid>
6966 Sets the group of the UNIX sockets to the designated system gid. It can also
6967 be set by default in the global section's "unix-bind" statement. Note that
6968 some platforms simply ignore this. This setting is equivalent to the "group"
6969 setting except that the group ID is used instead of its name. This setting is
6970 ignored by non UNIX sockets.
6971
6972group <group>
6973 Sets the group of the UNIX sockets to the designated system group. It can
6974 also be set by default in the global section's "unix-bind" statement. Note
6975 that some platforms simply ignore this. This setting is equivalent to the
6976 "gid" setting except that the group name is used instead of its gid. This
6977 setting is ignored by non UNIX sockets.
6978
6979id <id>
6980 Fixes the socket ID. By default, socket IDs are automatically assigned, but
6981 sometimes it is more convenient to fix them to ease monitoring. This value
6982 must be strictly positive and unique within the listener/frontend. This
6983 option can only be used when defining only a single socket.
6984
6985interface <interface>
6986 Sets the name of the network interface to listen. This is currently only
6987 supported on Linux. The interface must be a primary system interface, not an
6988 aliased interface. When specified, all addresses on the same line will only
6989 be accepted if the incoming packets physically come through the designated
6990 interface. It is also possible to bind multiple frontends to the same address
6991 if they are bound to different interfaces. Note that binding to a network
6992 interface requires root privileges. This parameter is only compatible with
6993 TCPv4/TCPv6 sockets.
6994
Willy Tarreauabb175f2012-09-24 12:43:26 +02006995level <level>
6996 This setting is used with the stats sockets only to restrict the nature of
6997 the commands that can be issued on the socket. It is ignored by other
6998 sockets. <level> can be one of :
6999 - "user" is the least privileged level ; only non-sensitive stats can be
7000 read, and no change is allowed. It would make sense on systems where it
7001 is not easy to restrict access to the socket.
7002 - "operator" is the default level and fits most common uses. All data can
7003 be read, and only non-sensitive changes are permitted (eg: clear max
7004 counters).
7005 - "admin" should be used with care, as everything is permitted (eg: clear
7006 all counters).
7007
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007008maxconn <maxconn>
7009 Limits the sockets to this number of concurrent connections. Extraneous
7010 connections will remain in the system's backlog until a connection is
7011 released. If unspecified, the limit will be the same as the frontend's
7012 maxconn. Note that in case of port ranges or multiple addresses, the same
7013 value will be applied to each socket. This setting enables different
7014 limitations on expensive sockets, for instance SSL entries which may easily
7015 eat all memory.
7016
7017mode <mode>
7018 Sets the octal mode used to define access permissions on the UNIX socket. It
7019 can also be set by default in the global section's "unix-bind" statement.
7020 Note that some platforms simply ignore this. This setting is ignored by non
7021 UNIX sockets.
7022
7023mss <maxseg>
7024 Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming
7025 connections. This can be used to force a lower MSS for certain specific
7026 ports, for instance for connections passing through a VPN. Note that this
7027 relies on a kernel feature which is theoretically supported under Linux but
7028 was buggy in all versions prior to 2.6.28. It may or may not work on other
7029 operating systems. It may also not change the advertised value but change the
7030 effective size of outgoing segments. The commonly advertised value for TCPv4
7031 over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is
7032 positive, it will be used as the advertised MSS. If it is negative, it will
7033 indicate by how much to reduce the incoming connection's advertised MSS for
7034 outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.
7035
7036name <name>
7037 Sets an optional name for these sockets, which will be reported on the stats
7038 page.
7039
7040nice <nice>
7041 Sets the 'niceness' of connections initiated from the socket. Value must be
7042 in the range -1024..1024 inclusive, and defaults to zero. Positive values
7043 means that such connections are more friendly to others and easily offer
7044 their place in the scheduler. On the opposite, negative values mean that
7045 connections want to run with a higher priority than others. The difference
7046 only happens under high loads when the system is close to saturation.
7047 Negative values are appropriate for low-latency or administration services,
7048 and high values are generally recommended for CPU intensive tasks such as SSL
7049 processing or bulk transfers which are less sensible to latency. For example,
7050 it may make sense to use a positive value for an SMTP socket and a negative
7051 one for an RDP socket.
7052
Emeric Brun9b3009b2012-10-05 11:55:06 +02007053no-sslv3
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007054 This setting is only available when support for OpenSSL was built in. It
7055 disables support for SSLv3 on any sockets instanciated from the listener when
7056 SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007057 be enabled using any configuration option. See also "force-tls*",
7058 and "force-sslv3".
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007059
Emeric Brun90ad8722012-10-02 14:00:59 +02007060no-tls-tickets
7061 This setting is only available when support for OpenSSL was built in. It
7062 disables the stateless session resumption (RFC 5077 TLS Ticket
7063 extension) and force to use stateful session resumption. Stateless
7064 session resumption is more expensive in CPU usage.
7065
Emeric Brun9b3009b2012-10-05 11:55:06 +02007066no-tlsv10
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007067 This setting is only available when support for OpenSSL was built in. It
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007068 disables support for TLSv1.0 on any sockets instanciated from the listener
7069 when SSL is supported. Note that SSLv2 is forced disabled in the code and
7070 cannot be enabled using any configuration option. See also "force-tls*",
7071 and "force-sslv3".
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007072
Emeric Brun9b3009b2012-10-05 11:55:06 +02007073no-tlsv11
Emeric Brunf5da4932012-09-28 19:42:54 +02007074 This setting is only available when support for OpenSSL was built in. It
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007075 disables support for TLSv1.1 on any sockets instanciated from the listener
7076 when SSL is supported. Note that SSLv2 is forced disabled in the code and
7077 cannot be enabled using any configuration option. See also "force-tls*",
7078 and "force-sslv3".
Emeric Brunf5da4932012-09-28 19:42:54 +02007079
Emeric Brun9b3009b2012-10-05 11:55:06 +02007080no-tlsv12
Emeric Brunf5da4932012-09-28 19:42:54 +02007081 This setting is only available when support for OpenSSL was built in. It
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007082 disables support for TLSv1.2 on any sockets instanciated from the listener
7083 when SSL is supported. Note that SSLv2 is forced disabled in the code and
7084 cannot be enabled using any configuration option. See also "force-tls*",
7085 and "force-sslv3".
Emeric Brunf5da4932012-09-28 19:42:54 +02007086
Willy Tarreau6c9a3d52012-10-18 18:57:14 +02007087npn <protocols>
7088 This enables the NPN TLS extension and advertises the specified protocol list
7089 as supported on top of NPN. The protocol list consists in a comma-delimited
7090 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
7091 This requires that the SSL library is build with support for TLS extensions
7092 enabled (check with haproxy -vv).
7093
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007094ssl
7095 This setting is only available when support for OpenSSL was built in. It
7096 enables SSL deciphering on connections instanciated from this listener. A
7097 certificate is necessary (see "crt" above). All contents in the buffers will
7098 appear in clear text, so that ACLs and HTTP processing will only have access
7099 to deciphered contents.
7100
Willy Tarreau1c862c52012-10-05 16:21:00 +02007101tfo
7102 Is an optional keyword which is supported only on Linux kernels >= 3.6. It
7103 enables TCP Fast Open on the listening socket, which means that clients which
7104 support this feature will be able to send a request and receive a response
7105 during the 3-way handshake starting from second connection, thus saving one
7106 round-trip after the first connection. This only makes sense with protocols
7107 that use high connection rates and where each round trip matters. This can
7108 possibly cause issues with many firewalls which do not accept data on SYN
7109 packets, so this option should only be enabled once well tested. This option
7110 is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
7111
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007112transparent
7113 Is an optional keyword which is supported only on certain Linux kernels. It
7114 indicates that the addresses will be bound even if they do not belong to the
7115 local machine, and that packets targeting any of these addresses will be
7116 intercepted just as if the addresses were locally configured. This normally
7117 requires that IP forwarding is enabled. Caution! do not use this with the
7118 default address '*', as it would redirect any traffic for the specified port.
7119 This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1.
7120 This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on
7121 kernel version. Some distribution kernels include backports of the feature,
7122 so check for support with your vendor.
7123
7124uid <uid>
7125 Sets the owner of the UNIX sockets to the designated system uid. It can also
7126 be set by default in the global section's "unix-bind" statement. Note that
7127 some platforms simply ignore this. This setting is equivalent to the "user"
7128 setting except that the user numeric ID is used instead of its name. This
7129 setting is ignored by non UNIX sockets.
7130
7131user <user>
7132 Sets the owner of the UNIX sockets to the designated system user. It can also
7133 be set by default in the global section's "unix-bind" statement. Note that
7134 some platforms simply ignore this. This setting is equivalent to the "uid"
7135 setting except that the user name is used instead of its uid. This setting is
7136 ignored by non UNIX sockets.
7137
Emeric Brun1a073b42012-09-28 17:07:34 +02007138verify [none|optional|required]
7139 This setting is only available when support for OpenSSL was built in. If set
7140 to 'none', client certificate is not requested. This is the default. In other
7141 cases, a client certificate is requested. If the client does not provide a
7142 certificate after the request and if 'verify' is set to 'required', then the
7143 handshake is aborted, while it would have succeeded if set to 'optional'. The
Emeric Brunfd33a262012-10-11 16:28:27 +02007144 certificate provided by the client is always verified using CAs from
7145 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
7146 is aborted, regardless of the 'verify' option, unless the error code exactly
7147 matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.
Willy Tarreau4a5cade2012-04-05 21:09:48 +02007148
Willy Tarreaub6205fd2012-09-24 12:27:33 +020071495.2. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +01007150------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007151
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01007152The "server" and "default-server" keywords support a certain number of settings
7153which are all passed as arguments on the server line. The order in which those
7154arguments appear does not count, and they are all optional. Some of those
7155settings are single words (booleans) while others expect one or several values
7156after them. In this case, the values must immediately follow the setting name.
7157Except default-server, all those settings must be specified after the server's
7158address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +02007159
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007160 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01007161 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +02007162
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007163The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +01007164
Willy Tarreauceb4ac92012-04-28 00:41:46 +02007165addr <ipv4|ipv6>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007166 Using the "addr" parameter, it becomes possible to use a different IP address
7167 to send health-checks. On some servers, it may be desirable to dedicate an IP
7168 address to specific component able to perform complex tests which are more
7169 suitable to health-checks than the application. This parameter is ignored if
7170 the "check" parameter is not set. See also the "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007171
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007172 Supported in default-server: No
7173
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007174backup
7175 When "backup" is present on a server line, the server is only used in load
7176 balancing when all other non-backup servers are unavailable. Requests coming
7177 with a persistence cookie referencing the server will always be served
7178 though. By default, only the first operational backup server is used, unless
7179 the "allbackups" option is set in the backend. See also the "allbackups"
7180 option.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007181
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007182 Supported in default-server: No
7183
Emeric Brunef42d922012-10-11 16:11:36 +02007184ca-file <cafile>
7185 This setting is only available when support for OpenSSL was built in. It
7186 designates a PEM file from which to load CA certificates used to verify
7187 server's certificate.
7188
7189 Supported in default-server: No
7190
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007191check
7192 This option enables health checks on the server. By default, a server is
Patrick Mézardb7aeec62012-01-22 16:01:22 +01007193 always considered available. If "check" is set, the server is available when
7194 accepting periodic TCP connections, to ensure that it is really able to serve
7195 requests. The default address and port to send the tests to are those of the
7196 server, and the default source is the same as the one defined in the
7197 backend. It is possible to change the address using the "addr" parameter, the
7198 port using the "port" parameter, the source address using the "source"
7199 address, and the interval and timers using the "inter", "rise" and "fall"
7200 parameters. The request method is define in the backend using the "httpchk",
7201 "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please
7202 refer to those options and parameters for more information.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007203
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007204 Supported in default-server: No
7205
Willy Tarreau6c16adc2012-10-05 00:04:16 +02007206check-send-proxy
7207 This option forces emission of a PROXY protocol line with outgoing health
7208 checks, regardless of whether the server uses send-proxy or not for the
7209 normal traffic. By default, the PROXY protocol is enabled for health checks
7210 if it is already enabled for normal traffic and if no "port" nor "addr"
7211 directive is present. However, if such a directive is present, the
7212 "check-send-proxy" option needs to be used to force the use of the
7213 protocol. See also the "send-proxy" option for more information.
7214
7215 Supported in default-server: No
7216
Willy Tarreau763a95b2012-10-04 23:15:39 +02007217check-ssl
7218 This option forces encryption of all health checks over SSL, regardless of
7219 whether the server uses SSL or not for the normal traffic. This is generally
7220 used when an explicit "port" or "addr" directive is specified and SSL health
7221 checks are not inherited. It is important to understand that this option
7222 inserts an SSL transport layer below the ckecks, so that a simple TCP connect
7223 check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
7224 common use is to send HTTPS checks by combining "httpchk" with SSL checks.
7225 All SSL settings are common to health checks and traffic (eg: ciphers).
7226 See the "ssl" option for more information.
7227
7228 Supported in default-server: No
7229
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007230ciphers <ciphers>
7231 This option sets the string describing the list of cipher algorithms that is
7232 is negociated during the SSL/TLS handshake with the server. The format of the
7233 string is defined in "man 1 ciphers". When SSL is used to communicate with
7234 servers on the local network, it is common to see a weaker set of algorithms
7235 than what is used over the internet. Doing so reduces CPU usage on both the
7236 server and haproxy while still keeping it compatible with deployed software.
7237 Some algorithms such as RC4-SHA1 are reasonably cheap. If no security at all
7238 is needed and just connectivity, using DES can be appropriate.
7239
Willy Tarreau763a95b2012-10-04 23:15:39 +02007240 Supported in default-server: No
7241
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007242cookie <value>
7243 The "cookie" parameter sets the cookie value assigned to the server to
7244 <value>. This value will be checked in incoming requests, and the first
7245 operational server possessing the same value will be selected. In return, in
7246 cookie insertion or rewrite modes, this value will be assigned to the cookie
7247 sent to the client. There is nothing wrong in having several servers sharing
7248 the same cookie value, and it is in fact somewhat common between normal and
7249 backup servers. See also the "cookie" keyword in backend section.
7250
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007251 Supported in default-server: No
7252
Emeric Brunef42d922012-10-11 16:11:36 +02007253crl-file <crlfile>
7254 This setting is only available when support for OpenSSL was built in. It
7255 designates a PEM file from which to load certificate revocation list used
7256 to verify server's certificate.
7257
7258 Supported in default-server: No
7259
Emeric Bruna7aa3092012-10-26 12:58:00 +02007260crt <cert>
7261 This setting is only available when support for OpenSSL was built in.
7262 It designates a PEM file from which to load both a certificate and the
7263 associated private key. This file can be built by concatenating both PEM
7264 files into one. This certificate will be sent if the server send a client
7265 certificate request.
7266
7267 Supported in default-server: No
7268
Willy Tarreau96839092010-03-29 10:02:24 +02007269disabled
7270 The "disabled" keyword starts the server in the "disabled" state. That means
7271 that it is marked down in maintenance mode, and no connection other than the
7272 ones allowed by persist mode will reach it. It is very well suited to setup
7273 new servers, because normal traffic will never reach them, while it is still
7274 possible to test the service by making use of the force-persist mechanism.
7275
7276 Supported in default-server: No
7277
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007278error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +01007279 If health observing is enabled, the "error-limit" parameter specifies the
7280 number of consecutive errors that triggers event selected by the "on-error"
7281 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007282
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007283 Supported in default-server: Yes
7284
7285 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007286
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007287fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007288 The "fall" parameter states that a server will be considered as dead after
7289 <count> consecutive unsuccessful health checks. This value defaults to 3 if
7290 unspecified. See also the "check", "inter" and "rise" parameters.
7291
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007292 Supported in default-server: Yes
7293
Emeric Brun8694b9a2012-10-05 14:39:07 +02007294force-sslv3
7295 This option enforces use of SSLv3 only when SSL is used to communicate with
7296 the server. SSLv3 is generally less expensive than the TLS counterparts for
7297 high connection rates. See also "no-tlsv*", "no-sslv3".
7298
7299 Supported in default-server: No
7300
7301force-tlsv10
7302 This option enforces use of TLSv1.0 only when SSL is used to communicate with
7303 the server. See also "no-tlsv*", "no-sslv3".
7304
7305 Supported in default-server: No
7306
7307force-tlsv11
7308 This option enforces use of TLSv1.1 only when SSL is used to communicate with
7309 the server. See also "no-tlsv*", "no-sslv3".
7310
7311 Supported in default-server: No
7312
7313force-tlsv12
7314 This option enforces use of TLSv1.2 only when SSL is used to communicate with
7315 the server. See also "no-tlsv*", "no-sslv3".
7316
7317 Supported in default-server: No
7318
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007319id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02007320 Set a persistent ID for the server. This ID must be positive and unique for
7321 the proxy. An unused ID will automatically be assigned if unset. The first
7322 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007323
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007324 Supported in default-server: No
7325
7326inter <delay>
7327fastinter <delay>
7328downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007329 The "inter" parameter sets the interval between two consecutive health checks
7330 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
7331 It is also possible to use "fastinter" and "downinter" to optimize delays
7332 between checks depending on the server state :
7333
7334 Server state | Interval used
7335 ---------------------------------+-----------------------------------------
7336 UP 100% (non-transitional) | "inter"
7337 ---------------------------------+-----------------------------------------
7338 Transitionally UP (going down), |
7339 Transitionally DOWN (going up), | "fastinter" if set, "inter" otherwise.
7340 or yet unchecked. |
7341 ---------------------------------+-----------------------------------------
7342 DOWN 100% (non-transitional) | "downinter" if set, "inter" otherwise.
7343 ---------------------------------+-----------------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +01007344
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007345 Just as with every other time-based parameter, they can be entered in any
7346 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
7347 serves as a timeout for health checks sent to servers if "timeout check" is
7348 not set. In order to reduce "resonance" effects when multiple servers are
7349 hosted on the same hardware, the health-checks of all servers are started
7350 with a small time offset between them. It is also possible to add some random
7351 noise in the health checks interval using the global "spread-checks"
7352 keyword. This makes sense for instance when a lot of backends use the same
7353 servers.
7354
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007355 Supported in default-server: Yes
7356
7357maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007358 The "maxconn" parameter specifies the maximal number of concurrent
7359 connections that will be sent to this server. If the number of incoming
7360 concurrent requests goes higher than this value, they will be queued, waiting
7361 for a connection to be released. This parameter is very important as it can
7362 save fragile servers from going down under extreme loads. If a "minconn"
7363 parameter is specified, the limit becomes dynamic. The default value is "0"
7364 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
7365 the backend's "fullconn" keyword.
7366
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007367 Supported in default-server: Yes
7368
7369maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007370 The "maxqueue" parameter specifies the maximal number of connections which
7371 will wait in the queue for this server. If this limit is reached, next
7372 requests will be redispatched to other servers instead of indefinitely
7373 waiting to be served. This will break persistence but may allow people to
7374 quickly re-log in when the server they try to connect to is dying. The
7375 default value is "0" which means the queue is unlimited. See also the
7376 "maxconn" and "minconn" parameters.
7377
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007378 Supported in default-server: Yes
7379
7380minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007381 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
7382 limit following the backend's load. The server will always accept at least
7383 <minconn> connections, never more than <maxconn>, and the limit will be on
7384 the ramp between both values when the backend has less than <fullconn>
7385 concurrent connections. This makes it possible to limit the load on the
7386 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007387 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007388 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007389
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007390 Supported in default-server: Yes
7391
Emeric Brun9b3009b2012-10-05 11:55:06 +02007392no-sslv3
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007393 This option disables support for SSLv3 when SSL is used to communicate with
7394 the server. Note that SSLv2 is disabled in the code and cannot be enabled
Emeric Brun8694b9a2012-10-05 14:39:07 +02007395 using any configuration option. See also "force-sslv3", "force-tlsv*".
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007396
Willy Tarreau763a95b2012-10-04 23:15:39 +02007397 Supported in default-server: No
7398
Emeric Brunf9c5c472012-10-11 15:28:34 +02007399no-tls-tickets
7400 This setting is only available when support for OpenSSL was built in. It
7401 disables the stateless session resumption (RFC 5077 TLS Ticket
7402 extension) and force to use stateful session resumption. Stateless
7403 session resumption is more expensive in CPU usage for servers.
7404
7405 Supported in default-server: No
7406
Emeric Brun9b3009b2012-10-05 11:55:06 +02007407no-tlsv10
Emeric Brun8694b9a2012-10-05 14:39:07 +02007408 This option disables support for TLSv1.0 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +02007409 the server. Note that SSLv2 is disabled in the code and cannot be enabled
7410 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun8694b9a2012-10-05 14:39:07 +02007411 often makes sense to disable it when communicating with local servers. See
7412 also "force-sslv3", "force-tlsv*".
Emeric Brunf5da4932012-09-28 19:42:54 +02007413
Willy Tarreau763a95b2012-10-04 23:15:39 +02007414 Supported in default-server: No
7415
Emeric Brun9b3009b2012-10-05 11:55:06 +02007416no-tlsv11
Emeric Brun8694b9a2012-10-05 14:39:07 +02007417 This option disables support for TLSv1.1 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +02007418 the server. Note that SSLv2 is disabled in the code and cannot be enabled
7419 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun8694b9a2012-10-05 14:39:07 +02007420 often makes sense to disable it when communicating with local servers. See
7421 also "force-sslv3", "force-tlsv*".
Emeric Brunf5da4932012-09-28 19:42:54 +02007422
Willy Tarreau763a95b2012-10-04 23:15:39 +02007423 Supported in default-server: No
7424
Emeric Brun9b3009b2012-10-05 11:55:06 +02007425no-tlsv12
Emeric Brun8694b9a2012-10-05 14:39:07 +02007426 This option disables support for TLSv1.2 when SSL is used to communicate with
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007427 the server. Note that SSLv2 is disabled in the code and cannot be enabled
7428 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun8694b9a2012-10-05 14:39:07 +02007429 often makes sense to disable it when communicating with local servers. See
7430 also "force-sslv3", "force-tlsv*".
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007431
Willy Tarreau763a95b2012-10-04 23:15:39 +02007432 Supported in default-server: No
7433
Simon Hormanfa461682011-06-25 09:39:49 +09007434non-stick
7435 Never add connections allocated to this sever to a stick-table.
7436 This may be used in conjunction with backup to ensure that
7437 stick-table persistence is disabled for backup servers.
7438
Willy Tarreau763a95b2012-10-04 23:15:39 +02007439 Supported in default-server: No
7440
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007441observe <mode>
7442 This option enables health adjusting based on observing communication with
7443 the server. By default this functionality is disabled and enabling it also
7444 requires to enable health checks. There are two supported modes: "layer4" and
7445 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
7446 significant. In layer7, which is only allowed for http proxies, responses
7447 received from server are verified, like valid/wrong http code, unparsable
Willy Tarreau150d1462012-03-10 08:19:02 +01007448 headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007449
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007450 Supported in default-server: No
7451
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007452 See also the "check", "on-error" and "error-limit".
7453
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007454on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007455 Select what should happen when enough consecutive errors are detected.
7456 Currently, four modes are available:
7457 - fastinter: force fastinter
7458 - fail-check: simulate a failed check, also forces fastinter (default)
7459 - sudden-death: simulate a pre-fatal failed health check, one more failed
7460 check will mark a server down, forces fastinter
7461 - mark-down: mark the server immediately down and force fastinter
7462
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007463 Supported in default-server: Yes
7464
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007465 See also the "check", "observe" and "error-limit".
7466
Simon Hormane0d1bfb2011-06-21 14:34:58 +09007467on-marked-down <action>
7468 Modify what occurs when a server is marked down.
7469 Currently one action is available:
Justin Karnegeseb2c24a2012-05-24 15:28:52 -07007470 - shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
7471 all connections to the server are immediately terminated when the server
7472 goes down. It might be used if the health check detects more complex cases
7473 than a simple connection status, and long timeouts would cause the service
7474 to remain unresponsive for too long a time. For instance, a health check
7475 might detect that a database is stuck and that there's no chance to reuse
7476 existing connections anymore. Connections killed this way are logged with
7477 a 'D' termination code (for "Down").
Simon Hormane0d1bfb2011-06-21 14:34:58 +09007478
7479 Actions are disabled by default
7480
7481 Supported in default-server: Yes
7482
Justin Karnegeseb2c24a2012-05-24 15:28:52 -07007483on-marked-up <action>
7484 Modify what occurs when a server is marked up.
7485 Currently one action is available:
7486 - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
7487 done only if the server is not in backup state and if it is not disabled
7488 (it must have an effective weight > 0). This can be used sometimes to force
7489 an active server to take all the traffic back after recovery when dealing
7490 with long sessions (eg: LDAP, SQL, ...). Doing this can cause more trouble
7491 than it tries to solve (eg: incomplete transactions), so use this feature
7492 with extreme care. Sessions killed because a server comes up are logged
7493 with an 'U' termination code (for "Up").
7494
7495 Actions are disabled by default
7496
7497 Supported in default-server: Yes
7498
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007499port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007500 Using the "port" parameter, it becomes possible to use a different port to
7501 send health-checks. On some servers, it may be desirable to dedicate a port
7502 to a specific component able to perform complex tests which are more suitable
7503 to health-checks than the application. It is common to run a simple script in
7504 inetd for instance. This parameter is ignored if the "check" parameter is not
7505 set. See also the "addr" parameter.
7506
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007507 Supported in default-server: Yes
7508
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007509redir <prefix>
7510 The "redir" parameter enables the redirection mode for all GET and HEAD
7511 requests addressing this server. This means that instead of having HAProxy
7512 forward the request to the server, it will send an "HTTP 302" response with
7513 the "Location" header composed of this prefix immediately followed by the
7514 requested URI beginning at the leading '/' of the path component. That means
7515 that no trailing slash should be used after <prefix>. All invalid requests
7516 will be rejected, and all non-GET or HEAD requests will be normally served by
7517 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007518 mangling nor cookie insertion is possible in the response. However, cookies in
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007519 requests are still analysed, making this solution completely usable to direct
7520 users to a remote location in case of local disaster. Main use consists in
7521 increasing bandwidth for static servers by having the clients directly
7522 connect to them. Note: never use a relative location here, it would cause a
7523 loop between the client and HAProxy!
7524
7525 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
7526
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007527 Supported in default-server: No
7528
7529rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007530 The "rise" parameter states that a server will be considered as operational
7531 after <count> consecutive successful health checks. This value defaults to 2
7532 if unspecified. See also the "check", "inter" and "fall" parameters.
7533
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007534 Supported in default-server: Yes
7535
Willy Tarreau5ab04ec2011-03-20 10:32:26 +01007536send-proxy
7537 The "send-proxy" parameter enforces use of the PROXY protocol over any
7538 connection established to this server. The PROXY protocol informs the other
7539 end about the layer 3/4 addresses of the incoming connection, so that it can
7540 know the client's address or the public address it accessed to, whatever the
7541 upper layer protocol. For connections accepted by an "accept-proxy" listener,
7542 the advertised address will be used. Only TCPv4 and TCPv6 address families
7543 are supported. Other families such as Unix sockets, will report an UNKNOWN
7544 family. Servers using this option can fully be chained to another instance of
7545 haproxy listening with an "accept-proxy" setting. This setting must not be
Willy Tarreau6c16adc2012-10-05 00:04:16 +02007546 used if the server isn't aware of the protocol. When health checks are sent
7547 to the server, the PROXY protocol is automatically used when this option is
7548 set, unless there is an explicit "port" or "addr" directive, in which case an
7549 explicit "check-send-proxy" directive would also be needed to use the PROXY
7550 protocol. See also the "accept-proxy" option of the "bind" keyword.
Willy Tarreau5ab04ec2011-03-20 10:32:26 +01007551
7552 Supported in default-server: No
7553
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007554slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007555 The "slowstart" parameter for a server accepts a value in milliseconds which
7556 indicates after how long a server which has just come back up will run at
7557 full speed. Just as with every other time-based parameter, it can be entered
7558 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
7559 linearly from 0 to 100% during this time. The limitation applies to two
7560 parameters :
7561
7562 - maxconn: the number of connections accepted by the server will grow from 1
7563 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
7564
7565 - weight: when the backend uses a dynamic weighted algorithm, the weight
7566 grows linearly from 1 to 100%. In this case, the weight is updated at every
7567 health-check. For this reason, it is important that the "inter" parameter
7568 is smaller than the "slowstart", in order to maximize the number of steps.
7569
7570 The slowstart never applies when haproxy starts, otherwise it would cause
7571 trouble to running servers. It only applies when a server has been previously
7572 seen as failed.
7573
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007574 Supported in default-server: Yes
7575
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02007576source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02007577source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02007578source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007579 The "source" parameter sets the source address which will be used when
7580 connecting to the server. It follows the exact same parameters and principle
7581 as the backend "source" keyword, except that it only applies to the server
7582 referencing it. Please consult the "source" keyword for details.
7583
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02007584 Additionally, the "source" statement on a server line allows one to specify a
7585 source port range by indicating the lower and higher bounds delimited by a
7586 dash ('-'). Some operating systems might require a valid IP address when a
7587 source port range is specified. It is permitted to have the same IP/range for
7588 several servers. Doing so makes it possible to bypass the maximum of 64k
7589 total concurrent connections. The limit will then reach 64k connections per
7590 server.
7591
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007592 Supported in default-server: No
7593
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007594ssl
Willy Tarreau763a95b2012-10-04 23:15:39 +02007595 This option enables SSL ciphering on outgoing connections to the server. At
7596 the moment, server certificates are not checked, so this is prone to man in
7597 the middle attacks. The real intended use is to permit SSL communication
7598 with software which cannot work in other modes over networks that would
7599 otherwise be considered safe enough for clear text communications. When this
7600 option is used, health checks are automatically sent in SSL too unless there
7601 is a "port" or an "addr" directive indicating the check should be sent to a
7602 different location. See the "check-ssl" optino to force SSL health checks.
7603
7604 Supported in default-server: No
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007605
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007606track [<proxy>/]<server>
7607 This option enables ability to set the current state of the server by
7608 tracking another one. Only a server with checks enabled can be tracked
7609 so it is not possible for example to track a server that tracks another
7610 one. If <proxy> is omitted the current one is used. If disable-on-404 is
7611 used, it has to be enabled on both proxies.
7612
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007613 Supported in default-server: No
7614
Emeric Brunef42d922012-10-11 16:11:36 +02007615verify [none|required]
7616 This setting is only available when support for OpenSSL was built in. If set
7617 to 'none', server certificate is not verified. This is the default. In the
7618 other case, The certificate provided by the server is verified using CAs from
7619 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
7620 is aborted.
7621
7622 Supported in default-server: No
7623
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007624weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007625 The "weight" parameter is used to adjust the server's weight relative to
7626 other servers. All servers will receive a load proportional to their weight
7627 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +02007628 load. The default weight is 1, and the maximal value is 256. A value of 0
7629 means the server will not participate in load-balancing but will still accept
7630 persistent connections. If this parameter is used to distribute the load
7631 according to server's capacity, it is recommended to start with values which
7632 can both grow and shrink, for instance between 10 and 100 to leave enough
7633 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007634
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007635 Supported in default-server: Yes
7636
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007637
76386. HTTP header manipulation
7639---------------------------
7640
7641In HTTP mode, it is possible to rewrite, add or delete some of the request and
7642response headers based on regular expressions. It is also possible to block a
7643request or a response if a particular header matches a regular expression,
7644which is enough to stop most elementary protocol attacks, and to protect
7645against information leak from the internal network. But there is a limitation
7646to this : since HAProxy's HTTP engine does not support keep-alive, only headers
7647passed during the first request of a TCP session will be seen. All subsequent
7648headers will be considered data only and not analyzed. Furthermore, HAProxy
7649never touches data contents, it stops analysis at the end of headers.
7650
Willy Tarreau816b9792009-09-15 21:25:21 +02007651There is an exception though. If HAProxy encounters an "Informational Response"
7652(status code 1xx), it is able to process all rsp* rules which can allow, deny,
7653rewrite or delete a header, but it will refuse to add a header to any such
7654messages as this is not HTTP-compliant. The reason for still processing headers
7655in such responses is to stop and/or fix any possible information leak which may
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007656happen, for instance because another downstream equipment would unconditionally
Willy Tarreau816b9792009-09-15 21:25:21 +02007657add a header, or if a server name appears there. When such messages are seen,
7658normal processing still occurs on the next non-informational messages.
7659
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007660This section covers common usage of the following keywords, described in detail
7661in section 4.2 :
7662
7663 - reqadd <string>
7664 - reqallow <search>
7665 - reqiallow <search>
7666 - reqdel <search>
7667 - reqidel <search>
7668 - reqdeny <search>
7669 - reqideny <search>
7670 - reqpass <search>
7671 - reqipass <search>
7672 - reqrep <search> <replace>
7673 - reqirep <search> <replace>
7674 - reqtarpit <search>
7675 - reqitarpit <search>
7676 - rspadd <string>
7677 - rspdel <search>
7678 - rspidel <search>
7679 - rspdeny <search>
7680 - rspideny <search>
7681 - rsprep <search> <replace>
7682 - rspirep <search> <replace>
7683
7684With all these keywords, the same conventions are used. The <search> parameter
7685is a POSIX extended regular expression (regex) which supports grouping through
7686parenthesis (without the backslash). Spaces and other delimiters must be
7687prefixed with a backslash ('\') to avoid confusion with a field delimiter.
7688Other characters may be prefixed with a backslash to change their meaning :
7689
7690 \t for a tab
7691 \r for a carriage return (CR)
7692 \n for a new line (LF)
7693 \ to mark a space and differentiate it from a delimiter
7694 \# to mark a sharp and differentiate it from a comment
7695 \\ to use a backslash in a regex
7696 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
7697 \xXX to write the ASCII hex code XX as in the C language
7698
7699The <replace> parameter contains the string to be used to replace the largest
7700portion of text matching the regex. It can make use of the special characters
7701above, and can reference a substring which is delimited by parenthesis in the
7702regex, by writing a backslash ('\') immediately followed by one digit from 0 to
77039 indicating the group position (0 designating the entire line). This practice
7704is very common to users of the "sed" program.
7705
7706The <string> parameter represents the string which will systematically be added
7707after the last header line. It can also use special character sequences above.
7708
7709Notes related to these keywords :
7710---------------------------------
7711 - these keywords are not always convenient to allow/deny based on header
7712 contents. It is strongly recommended to use ACLs with the "block" keyword
7713 instead, resulting in far more flexible and manageable rules.
7714
7715 - lines are always considered as a whole. It is not possible to reference
7716 a header name only or a value only. This is important because of the way
7717 headers are written (notably the number of spaces after the colon).
7718
7719 - the first line is always considered as a header, which makes it possible to
7720 rewrite or filter HTTP requests URIs or response codes, but in turn makes
7721 it harder to distinguish between headers and request line. The regex prefix
7722 ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix
7723 ^[^ \t:]*: matches any header name followed by a colon.
7724
7725 - for performances reasons, the number of characters added to a request or to
7726 a response is limited at build time to values between 1 and 4 kB. This
7727 should normally be far more than enough for most usages. If it is too short
7728 on occasional usages, it is possible to gain some space by removing some
7729 useless headers before adding new ones.
7730
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007731 - keywords beginning with "reqi" and "rspi" are the same as their counterpart
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007732 without the 'i' letter except that they ignore case when matching patterns.
7733
7734 - when a request passes through a frontend then a backend, all req* rules
7735 from the frontend will be evaluated, then all req* rules from the backend
7736 will be evaluated. The reverse path is applied to responses.
7737
7738 - req* statements are applied after "block" statements, so that "block" is
7739 always the first one, but before "use_backend" in order to permit rewriting
Willy Tarreaud72758d2010-01-12 10:42:19 +01007740 before switching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007741
7742
Willy Tarreaub937b7e2010-01-12 15:27:54 +010077437. Using ACLs and pattern extraction
7744------------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007745
7746The use of Access Control Lists (ACL) provides a flexible solution to perform
7747content switching and generally to take decisions based on content extracted
7748from the request, the response or any environmental status. The principle is
7749simple :
7750
7751 - define test criteria with sets of values
7752 - perform actions only if a set of tests is valid
7753
7754The actions generally consist in blocking the request, or selecting a backend.
7755
7756In order to define a test, the "acl" keyword is used. The syntax is :
7757
7758 acl <aclname> <criterion> [flags] [operator] <value> ...
7759
7760This creates a new ACL <aclname> or completes an existing one with new tests.
7761Those tests apply to the portion of request/response specified in <criterion>
7762and may be adjusted with optional flags [flags]. Some criteria also support
7763an operator which may be specified before the set of values. The values are
7764of the type supported by the criterion, and are separated by spaces.
7765
7766ACL names must be formed from upper and lower case letters, digits, '-' (dash),
7767'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
7768which means that "my_acl" and "My_Acl" are two different ACLs.
7769
7770There is no enforced limit to the number of ACLs. The unused ones do not affect
7771performance, they just consume a small amount of memory.
7772
7773The following ACL flags are currently supported :
7774
Willy Tarreau2b5285d2010-05-09 23:45:24 +02007775 -i : ignore case during matching of all subsequent patterns.
7776 -f : load patterns from a file.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007777 -- : force end of flags. Useful when a string looks like one of the flags.
7778
Willy Tarreau2b5285d2010-05-09 23:45:24 +02007779The "-f" flag is special as it loads all of the lines it finds in the file
7780specified in argument and loads all of them before continuing. It is even
7781possible to pass multiple "-f" arguments if the patterns are to be loaded from
Willy Tarreau58215a02010-05-13 22:07:43 +02007782multiple files. Empty lines as well as lines beginning with a sharp ('#') will
7783be ignored. All leading spaces and tabs will be stripped. If it is absolutely
7784needed to insert a valid pattern beginning with a sharp, just prefix it with a
7785space so that it is not taken for a comment. Depending on the data type and
7786match method, haproxy may load the lines into a binary tree, allowing very fast
7787lookups. This is true for IPv4 and exact string matching. In this case,
7788duplicates will automatically be removed. Also, note that the "-i" flag applies
Jamie Gloudonaaa21002012-08-25 00:18:33 -04007789to subsequent entries and not to entries loaded from files preceding it. For
Willy Tarreau58215a02010-05-13 22:07:43 +02007790instance :
Willy Tarreau2b5285d2010-05-09 23:45:24 +02007791
7792 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
7793
7794In this example, each line of "exact-ua.lst" will be exactly matched against
7795the "user-agent" header of the request. Then each line of "generic-ua" will be
7796case-insensitively matched. Then the word "test" will be insensitively matched
7797too.
7798
7799Note that right now it is difficult for the ACL parsers to report errors, so if
7800a file is unreadable or unparsable, the most you'll get is a parse error in the
7801ACL. Thus, file-based ACLs should only be produced by reliable processes.
7802
Willy Tarreau6a06a402007-07-15 20:15:28 +02007803Supported types of values are :
Willy Tarreau0ba27502007-12-24 16:55:16 +01007804
Willy Tarreau6a06a402007-07-15 20:15:28 +02007805 - integers or integer ranges
7806 - strings
7807 - regular expressions
7808 - IP addresses and networks
7809
7810
Willy Tarreauc57f0e22009-05-10 13:12:33 +020078117.1. Matching integers
7812----------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007813
7814Matching integers is special in that ranges and operators are permitted. Note
7815that integer matching only applies to positive values. A range is a value
7816expressed with a lower and an upper bound separated with a colon, both of which
7817may be omitted.
7818
7819For instance, "1024:65535" is a valid range to represent a range of
7820unprivileged ports, and "1024:" would also work. "0:1023" is a valid
7821representation of privileged ports, and ":1023" would also work.
7822
Willy Tarreau62644772008-07-16 18:36:06 +02007823As a special case, some ACL functions support decimal numbers which are in fact
7824two integers separated by a dot. This is used with some version checks for
7825instance. All integer properties apply to those decimal numbers, including
7826ranges and operators.
7827
Willy Tarreau6a06a402007-07-15 20:15:28 +02007828For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +01007829operators with ranges does not make much sense and is strongly discouraged.
7830Similarly, it does not make much sense to perform order comparisons with a set
7831of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007832
Willy Tarreau0ba27502007-12-24 16:55:16 +01007833Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +02007834
7835 eq : true if the tested value equals at least one value
7836 ge : true if the tested value is greater than or equal to at least one value
7837 gt : true if the tested value is greater than at least one value
7838 le : true if the tested value is less than or equal to at least one value
7839 lt : true if the tested value is less than at least one value
7840
Willy Tarreau0ba27502007-12-24 16:55:16 +01007841For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +02007842
7843 acl negative-length hdr_val(content-length) lt 0
7844
Willy Tarreau62644772008-07-16 18:36:06 +02007845This one matches SSL versions between 3.0 and 3.1 (inclusive) :
7846
7847 acl sslv3 req_ssl_ver 3:3.1
7848
Willy Tarreau6a06a402007-07-15 20:15:28 +02007849
Willy Tarreauc57f0e22009-05-10 13:12:33 +020078507.2. Matching strings
7851---------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007852
7853String matching applies to verbatim strings as they are passed, with the
7854exception of the backslash ("\") which makes it possible to escape some
7855characters such as the space. If the "-i" flag is passed before the first
7856string, then the matching will be performed ignoring the case. In order
7857to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +01007858before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02007859
7860
Willy Tarreauc57f0e22009-05-10 13:12:33 +020078617.3. Matching regular expressions (regexes)
7862-------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007863
7864Just like with string matching, regex matching applies to verbatim strings as
7865they are passed, with the exception of the backslash ("\") which makes it
7866possible to escape some characters such as the space. If the "-i" flag is
7867passed before the first regex, then the matching will be performed ignoring
7868the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +01007869the "--" flag before the first string. Same principle applies of course to
7870match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02007871
7872
Willy Tarreauceb4ac92012-04-28 00:41:46 +020078737.4. Matching IPv4 and IPv6 addresses
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007874----------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007875
7876IPv4 addresses values can be specified either as plain addresses or with a
7877netmask appended, in which case the IPv4 address matches whenever it is
7878within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01007879host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +01007880difficult to read and debug configurations. If hostnames are used, you should
7881at least ensure that they are present in /etc/hosts so that the configuration
7882does not depend on any random DNS match at the moment the configuration is
7883parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007884
Willy Tarreauceb4ac92012-04-28 00:41:46 +02007885IPv6 may be entered in their usual form, with or without a netmask appended.
7886Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of
7887trouble with randomly resolved IP addresses, host names are never allowed in
7888IPv6 patterns.
7889
7890HAProxy is also able to match IPv4 addresses with IPv6 addresses in the
7891following situations :
7892 - tested address is IPv4, pattern address is IPv4, the match applies
7893 in IPv4 using the supplied mask if any.
7894 - tested address is IPv6, pattern address is IPv6, the match applies
7895 in IPv6 using the supplied mask if any.
7896 - tested address is IPv6, pattern address is IPv4, the match applies in IPv4
7897 using the pattern's mask if the IPv6 address matches with 2002:IPV4::,
7898 ::IPV4 or ::ffff:IPV4, otherwise it fails.
7899 - tested address is IPv4, pattern address is IPv6, the IPv4 address is first
7900 converted to IPv6 by prefixing ::ffff: in front of it, then the match is
7901 applied in IPv6 using the supplied IPv6 mask.
7902
Willy Tarreau6a06a402007-07-15 20:15:28 +02007903
Willy Tarreauc57f0e22009-05-10 13:12:33 +020079047.5. Available matching criteria
7905--------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007906
Willy Tarreauc57f0e22009-05-10 13:12:33 +020079077.5.1. Matching at Layer 4 and below
7908------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01007909
7910A first set of criteria applies to information which does not require any
7911analysis of the request or response contents. Those generally include TCP/IP
Jamie Gloudon801a0a32012-08-25 00:18:33 -04007912addresses and ports, as well as internal values independent on the stream.
Willy Tarreau0ba27502007-12-24 16:55:16 +01007913
Willy Tarreau6a06a402007-07-15 20:15:28 +02007914always_false
7915 This one never matches. All values and flags are ignored. It may be used as
7916 a temporary replacement for another one when adjusting configurations.
7917
7918always_true
7919 This one always matches. All values and flags are ignored. It may be used as
7920 a temporary replacement for another one when adjusting configurations.
7921
Willy Tarreaud63335a2010-02-26 12:56:52 +01007922avg_queue <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007923avg_queue(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007924 Returns the total number of queued connections of the designated backend
7925 divided by the number of active servers. This is very similar to "queue"
7926 except that the size of the farm is considered, in order to give a more
7927 accurate measurement of the time it may take for a new connection to be
7928 processed. The main usage is to return a sorry page to new users when it
7929 becomes certain they will get a degraded service. Note that in the event
7930 there would not be any active server anymore, we would consider twice the
7931 number of queued connections as the measured value. This is a fair estimate,
7932 as we expect one server to get back soon anyway, but we still prefer to send
7933 new traffic to another backend if in better shape. See also the "queue",
7934 "be_conn", and "be_sess_rate" criteria.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +01007935
Willy Tarreaua36af912009-10-10 12:02:45 +02007936be_conn <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007937be_conn(<backend>) <integer>
Willy Tarreaua36af912009-10-10 12:02:45 +02007938 Applies to the number of currently established connections on the backend,
7939 possibly including the connection being evaluated. If no backend name is
7940 specified, the current one is used. But it is also possible to check another
7941 backend. It can be used to use a specific farm when the nominal one is full.
7942 See also the "fe_conn", "queue" and "be_sess_rate" criteria.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007943
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01007944be_id <integer>
7945 Applies to the backend's id. Can be used in frontends to check from which
7946 backend it was called.
7947
Willy Tarreaud63335a2010-02-26 12:56:52 +01007948be_sess_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007949be_sess_rate(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01007950 Returns true when the sessions creation rate on the backend matches the
7951 specified values or ranges, in number of new sessions per second. This is
7952 used to switch to an alternate backend when an expensive or fragile one
7953 reaches too high a session rate, or to limit abuse of service (eg. prevent
7954 sucking of an online dictionary).
7955
7956 Example :
7957 # Redirect to an error page if the dictionary is requested too often
7958 backend dynamic
7959 mode http
7960 acl being_scanned be_sess_rate gt 100
7961 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +01007962
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007963connslots <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007964connslots(<backend>) <integer>
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007965 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +02007966 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007967 usage; see "use_backend" keyword) can be redirected to a different backend.
7968
Willy Tarreau55165fe2009-05-10 12:02:55 +02007969 'connslots' = number of available server connection slots, + number of
7970 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007971
Willy Tarreaua36af912009-10-10 12:02:45 +02007972 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +02007973 useful when you have a case of traffic going to one single ip, splitting into
7974 multiple backends (perhaps using acls to do name-based load balancing) and
7975 you want to be able to differentiate between different backends, and their
7976 available "connslots". Also, whereas "nbsrv" only measures servers that are
7977 actually *down*, this acl is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +02007978 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007979
Willy Tarreau55165fe2009-05-10 12:02:55 +02007980 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
7981 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
7982 then this acl clearly does not make sense, in which case the value returned
7983 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08007984
Willy Tarreaud63335a2010-02-26 12:56:52 +01007985dst <ip_address>
Willy Tarreauceb4ac92012-04-28 00:41:46 +02007986 Applies to the local IPv4 or IPv6 address the client connected to. It can be
7987 used to switch to a different backend for some alternative addresses.
Willy Tarreaua36af912009-10-10 12:02:45 +02007988
Willy Tarreaud63335a2010-02-26 12:56:52 +01007989dst_conn <integer>
7990 Applies to the number of currently established connections on the same socket
7991 including the one being evaluated. It can be used to either return a sorry
7992 page before hard-blocking, or to use a specific backend to drain new requests
7993 when the socket is considered saturated. This offers the ability to assign
7994 different limits to different listening ports or addresses. See also the
7995 "fe_conn" and "be_conn" criteria.
7996
7997dst_port <integer>
7998 Applies to the local port the client connected to. It can be used to switch
7999 to a different backend for some alternative ports.
8000
8001fe_conn <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008002fe_conn(<frontend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008003 Applies to the number of currently established connections on the frontend,
8004 possibly including the connection being evaluated. If no frontend name is
8005 specified, the current one is used. But it is also possible to check another
8006 frontend. It can be used to either return a sorry page before hard-blocking,
8007 or to use a specific backend to drain new requests when the farm is
8008 considered saturated. See also the "dst_conn", "be_conn" and "fe_sess_rate"
8009 criteria.
8010
8011fe_id <integer>
Cyril Bonté78caf842010-03-10 22:41:43 +01008012 Applies to the frontend's id. Can be used in backends to check from which
Willy Tarreaud63335a2010-02-26 12:56:52 +01008013 frontend it was called.
Willy Tarreaua36af912009-10-10 12:02:45 +02008014
Willy Tarreau079ff0a2009-03-05 21:34:28 +01008015fe_sess_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008016fe_sess_rate(<frontend>) <integer>
Willy Tarreau079ff0a2009-03-05 21:34:28 +01008017 Returns true when the session creation rate on the current or the named
8018 frontend matches the specified values or ranges, expressed in new sessions
8019 per second. This is used to limit the connection rate to acceptable ranges in
8020 order to prevent abuse of service at the earliest moment. This can be
8021 combined with layer 4 ACLs in order to force the clients to wait a bit for
8022 the rate to go down below the limit.
8023
8024 Example :
8025 # This frontend limits incoming mails to 10/s with a max of 100
8026 # concurrent connections. We accept any connection below 10/s, and
8027 # force excess clients to wait for 100 ms. Since clients are limited to
8028 # 100 max, there cannot be more than 10 incoming mails per second.
8029 frontend mail
8030 bind :25
8031 mode tcp
8032 maxconn 100
8033 acl too_fast fe_sess_rate ge 10
8034 tcp-request inspect-delay 100ms
8035 tcp-request content accept if ! too_fast
8036 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +01008037
Willy Tarreaud63335a2010-02-26 12:56:52 +01008038nbsrv <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008039nbsrv(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008040 Returns true when the number of usable servers of either the current backend
8041 or the named backend matches the values or ranges specified. This is used to
8042 switch to an alternate backend when the number of servers is too low to
8043 to handle some load. It is useful to report a failure when combined with
8044 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +01008045
Willy Tarreaud63335a2010-02-26 12:56:52 +01008046queue <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008047queue(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008048 Returns the total number of queued connections of the designated backend,
8049 including all the connections in server queues. If no backend name is
8050 specified, the current one is used, but it is also possible to check another
8051 one. This can be used to take actions when queuing goes above a known level,
8052 generally indicating a surge of traffic or a massive slowdown on the servers.
8053 One possible action could be to reject new users but still accept old ones.
8054 See also the "avg_queue", "be_conn", and "be_sess_rate" criteria.
8055
Willy Tarreaue9656522010-08-17 15:40:09 +02008056sc1_bytes_in_rate
8057sc2_bytes_in_rate
8058 Returns the average client-to-server bytes rate from the currently tracked
8059 counters, measured in amount of bytes over the period configured in the
8060 table. See also src_bytes_in_rate.
8061
8062sc1_bytes_out_rate
8063sc2_bytes_out_rate
8064 Returns the average server-to-client bytes rate from the currently tracked
8065 counters, measured in amount of bytes over the period configured in the
8066 table. See also src_bytes_out_rate.
8067
Willy Tarreauf73cd112011-08-13 01:45:16 +02008068sc1_clr_gpc0
8069sc2_clr_gpc0
8070 Clears the first General Purpose Counter associated to the currently tracked
8071 counters, and returns its previous value. Before the first invocation, the
8072 stored value is zero, so first invocation will always return zero. The test
8073 can also be used alone and always returns true. This is typically used as a
8074 second ACL in an expression in order to mark a connection when a first ACL
8075 was verified :
8076
8077 # block if 5 consecutive requests continue to come faster than 10 sess
8078 # per second, and reset the counter as soon as the traffic slows down.
8079 acl abuse sc1_http_req_rate gt 10
8080 acl kill sc1_inc_gpc0 gt 5
8081 acl save sc1_clr_gpc0
8082 tcp-request connection accept if !abuse save
8083 tcp-request connection reject if abuse kill
8084
Willy Tarreaue9656522010-08-17 15:40:09 +02008085sc1_conn_cnt
8086sc2_conn_cnt
8087 Returns the cumulated number of incoming connections from currently tracked
8088 counters. See also src_conn_cnt.
8089
8090sc1_conn_cur
8091sc2_conn_cur
8092 Returns the current amount of concurrent connections tracking the same
8093 tracked counters. This number is automatically incremented when tracking
8094 begins and decremented when tracking stops. See also src_conn_cur.
8095
8096sc1_conn_rate
8097sc2_conn_rate
8098 Returns the average connection rate from the currently tracked counters,
8099 measured in amount of connections over the period configured in the table.
8100 See also src_conn_rate.
8101
8102sc1_get_gpc0
8103sc2_get_gpc0
8104 Returns the value of the first General Purpose Counter associated to the
8105 currently tracked counters. See also src_get_gpc0 and sc1/sc2_inc_gpc0.
8106
8107sc1_http_err_cnt
8108sc2_http_err_cnt
8109 Returns the cumulated number of HTTP errors from the currently tracked
8110 counters. This includes the both request errors and 4xx error responses.
8111 See also src_http_err_cnt.
8112
8113sc1_http_err_rate
8114sc2_http_err_rate
8115 Returns the average rate of HTTP errors from the currently tracked counters,
8116 measured in amount of errors over the period configured in the table. This
8117 includes the both request errors and 4xx error responses. See also
8118 src_http_err_rate.
8119
8120sc1_http_req_cnt
8121sc2_http_req_cnt
8122 Returns the cumulated number of HTTP requests from the currently tracked
8123 counters. This includes every started request, valid or not. See also
8124 src_http_req_cnt.
8125
8126sc1_http_req_rate
8127sc2_http_req_rate
8128 Returns the average rate of HTTP requests from the currently tracked
8129 counters, measured in amount of requests over the period configured in
8130 the table. This includes every started request, valid or not. See also
8131 src_http_req_rate.
8132
8133sc1_inc_gpc0
8134sc2_inc_gpc0
8135 Increments the first General Purpose Counter associated to the currently
8136 tracked counters, and returns its value. Before the first invocation, the
8137 stored value is zero, so first invocation will increase it to 1 and will
8138 return 1. The test can also be used alone and always returns true. This is
8139 typically used as a second ACL in an expression in order to mark a connection
8140 when a first ACL was verified :
8141
8142 acl abuse sc1_http_req_rate gt 10
8143 acl kill sc1_inc_gpc0
8144 tcp-request connection reject if abuse kill
8145
8146sc1_kbytes_in
8147sc2_kbytes_in
8148 Returns the amount of client-to-server data from the currently tracked
8149 counters, measured in kilobytes over the period configured in the table. The
8150 test is currently performed on 32-bit integers, which limits values to 4
8151 terabytes. See also src_kbytes_in.
8152
8153sc1_kbytes_out
8154sc2_kbytes_out
8155 Returns the amount of server-to-client data from the currently tracked
8156 counters, measured in kilobytes over the period configured in the table. The
8157 test is currently performed on 32-bit integers, which limits values to 4
8158 terabytes. See also src_kbytes_out.
8159
8160sc1_sess_cnt
8161sc2_sess_cnt
8162 Returns the cumulated number of incoming connections that were transformed
8163 into sessions, which means that they were accepted by a "tcp-request
8164 connection" rule, from the currently tracked counters. A backend may count
8165 more sessions than connections because each connection could result in many
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008166 backend sessions if some HTTP keep-alive is performed over the connection
Willy Tarreaue9656522010-08-17 15:40:09 +02008167 with the client. See also src_sess_cnt.
8168
8169sc1_sess_rate
8170sc2_sess_rate
8171 Returns the average session rate from the currently tracked counters,
8172 measured in amount of sessions over the period configured in the table. A
8173 session is a connection that got past the early "tcp-request connection"
8174 rules. A backend may count more sessions than connections because each
8175 connection could result in many backend sessions if some HTTP keep-alive is
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008176 performed over the connection with the client. See also src_sess_rate.
Willy Tarreaue9656522010-08-17 15:40:09 +02008177
Willy Tarreaud63335a2010-02-26 12:56:52 +01008178so_id <integer>
8179 Applies to the socket's id. Useful in frontends with many bind keywords.
8180
8181src <ip_address>
Willy Tarreauceb4ac92012-04-28 00:41:46 +02008182 Applies to the client's IPv4 or IPv6 address. It is usually used to limit
8183 access to certain resources such as statistics. Note that it is the TCP-level
8184 source address which is used, and not the address of a client behind a proxy.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008185
Willy Tarreauc9705a12010-07-27 20:05:50 +02008186src_bytes_in_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008187src_bytes_in_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008188 Returns the average bytes rate from the connection's source IPv4 address in
8189 the current proxy's stick-table or in the designated stick-table, measured in
8190 amount of bytes over the period configured in the table. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02008191 not found, zero is returned. See also sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008192
8193src_bytes_out_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008194src_bytes_out_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008195 Returns the average bytes rate to the connection's source IPv4 address in the
8196 current proxy's stick-table or in the designated stick-table, measured in
8197 amount of bytes over the period configured in the table. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02008198 not found, zero is returned. See also sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008199
Willy Tarreauf73cd112011-08-13 01:45:16 +02008200src_clr_gpc0 <integer>
8201src_clr_gpc0(<table>) <integer>
8202 Clears the first General Purpose Counter associated to the connection's
8203 source IPv4 address in the current proxy's stick-table or in the designated
8204 stick-table, and returns its previous value. If the address is not found, an
8205 entry is created and 0 is returned. The test can also be used alone and
8206 always returns true. This is typically used as a second ACL in an expression
8207 in order to mark a connection when a first ACL was verified :
8208
8209 # block if 5 consecutive requests continue to come faster than 10 sess
8210 # per second, and reset the counter as soon as the traffic slows down.
8211 acl abuse src_http_req_rate gt 10
8212 acl kill src_inc_gpc0 gt 5
8213 acl save src_clr_gpc0
8214 tcp-request connection accept if !abuse save
8215 tcp-request connection reject if abuse kill
8216
Willy Tarreauc9705a12010-07-27 20:05:50 +02008217src_conn_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008218src_conn_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008219 Returns the cumulated number of connections initiated from the current
8220 connection's source IPv4 address in the current proxy's stick-table or in
8221 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreaue9656522010-08-17 15:40:09 +02008222 See also sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008223
8224src_conn_cur <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008225src_conn_cur(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008226 Returns the current amount of concurrent connections initiated from the
8227 current connection's source IPv4 address in the current proxy's stick-table
8228 or in the designated stick-table. If the address is not found, zero is
Willy Tarreaue9656522010-08-17 15:40:09 +02008229 returned. See also sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008230
8231src_conn_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008232src_conn_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008233 Returns the average connection rate from the connection's source IPv4 address
8234 in the current proxy's stick-table or in the designated stick-table, measured
8235 in amount of connections over the period configured in the table. If the
Willy Tarreaue9656522010-08-17 15:40:09 +02008236 address is not found, zero is returned. See also sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008237
8238src_get_gpc0 <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008239src_get_gpc0(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008240 Returns the value of the first General Purpose Counter associated to the
8241 connection's source IPv4 address in the current proxy's stick-table or in
8242 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreaue9656522010-08-17 15:40:09 +02008243 See also sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008244
8245src_http_err_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008246src_http_err_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008247 Returns the cumulated number of HTTP errors from the current connection's
8248 source IPv4 address in the current proxy's stick-table or in the designated
8249 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreaue9656522010-08-17 15:40:09 +02008250 If the address is not found, zero is returned. See also sc1/sc2_http_err_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008251
8252src_http_err_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008253src_http_err_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008254 Returns the average rate of HTTP errors from the current connection's source
8255 IPv4 address in the current proxy's stick-table or in the designated stick-
8256 table, measured in amount of errors over the period configured in the table.
8257 This includes the both request errors and 4xx error responses. If the address
Willy Tarreaue9656522010-08-17 15:40:09 +02008258 is not found, zero is returned. See also sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008259
8260src_http_req_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008261src_http_req_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008262 Returns the cumulated number of HTTP requests from the current connection's
8263 source IPv4 address in the current proxy's stick-table or in the designated
8264 stick-table. This includes every started request, valid or not. If the
Willy Tarreaue9656522010-08-17 15:40:09 +02008265 address is not found, zero is returned. See also sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008266
8267src_http_req_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008268src_http_req_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008269 Returns the average rate of HTTP requests from the current connection's
8270 source IPv4 address in the current proxy's stick-table or in the designated
8271 stick-table, measured in amount of requests over the period configured in the
8272 table. This includes every started request, valid or not. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02008273 not found, zero is returned. See also sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008274
8275src_inc_gpc0 <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008276src_inc_gpc0(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008277 Increments the first General Purpose Counter associated to the connection's
8278 source IPv4 address in the current proxy's stick-table or in the designated
8279 stick-table, and returns its value. If the address is not found, an entry is
8280 created and 1 is returned. The test can also be used alone and always returns
8281 true. This is typically used as a second ACL in an expression in order to
8282 mark a connection when a first ACL was verified :
8283
8284 acl abuse src_http_req_rate gt 10
8285 acl kill src_inc_gpc0
Willy Tarreaue9656522010-08-17 15:40:09 +02008286 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +02008287
8288src_kbytes_in <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008289src_kbytes_in(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008290 Returns the amount of data received from the connection's source IPv4 address
8291 in the current proxy's stick-table or in the designated stick-table, measured
8292 in kilobytes over the period configured in the table. If the address is not
8293 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreaue9656522010-08-17 15:40:09 +02008294 which limits values to 4 terabytes. See also sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008295
8296src_kbytes_out <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008297src_kbytes_out(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008298 Returns the amount of data sent to the connection's source IPv4 address in
8299 the current proxy's stick-table or in the designated stick-table, measured
8300 in kilobytes over the period configured in the table. If the address is not
8301 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreaue9656522010-08-17 15:40:09 +02008302 which limits values to 4 terabytes. See also sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008303
Willy Tarreaud63335a2010-02-26 12:56:52 +01008304src_port <integer>
8305 Applies to the client's TCP source port. This has a very limited usage.
Willy Tarreau079ff0a2009-03-05 21:34:28 +01008306
Willy Tarreauc9705a12010-07-27 20:05:50 +02008307src_sess_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008308src_sess_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008309 Returns the cumulated number of connections initiated from the current
8310 connection's source IPv4 address in the current proxy's stick-table or in the
8311 designated stick-table, that were transformed into sessions, which means that
8312 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreaue9656522010-08-17 15:40:09 +02008313 is returned. See also sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008314
8315src_sess_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008316src_sess_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008317 Returns the average session rate from the connection's source IPv4 address in
8318 the current proxy's stick-table or in the designated stick-table, measured in
8319 amount of sessions over the period configured in the table. A session is a
8320 connection that got past the early "tcp-request" rules. If the address is not
Willy Tarreaue9656522010-08-17 15:40:09 +02008321 found, zero is returned. See also sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008322
8323src_updt_conn_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008324src_updt_conn_cnt(<table>) <integer>
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008325 Creates or updates the entry associated to the source IPv4 address in the
Willy Tarreauc9705a12010-07-27 20:05:50 +02008326 current proxy's stick-table or in the designated stick-table. This table
8327 must be configured to store the "conn_cnt" data type, otherwise the match
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008328 will be ignored. The current count is incremented by one, and the expiration
8329 timer refreshed. The updated count is returned, so this match can't return
8330 zero. This is used to reject service abusers based on their source address.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008331 Note: it is recommended to use the more complete "track-counters" instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008332
8333 Example :
8334 # This frontend limits incoming SSH connections to 3 per 10 second for
8335 # each source address, and rejects excess connections until a 10 second
8336 # silence is observed. At most 20 addresses are tracked.
8337 listen ssh
8338 bind :22
8339 mode tcp
8340 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +02008341 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008342 tcp-request content reject if { src_update_count gt 3 }
8343 server local 127.0.0.1:22
8344
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008345srv_conn(<backend>/<server>) <integer>
Hervé COMMOWICKdaa824e2011-08-05 12:09:44 +02008346 Applies to the number of currently established connections on the server,
8347 possibly including the connection being evaluated.
8348 It can be used to use a specific farm when one server is full.
8349 See also the "fe_conn", "be_conn" and "queue" criteria.
8350
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01008351srv_id <integer>
8352 Applies to the server's id. Can be used in frontends or backends.
8353
Willy Tarreau0b1cd942010-05-16 22:18:27 +02008354srv_is_up(<server>)
8355srv_is_up(<backend>/<server>)
8356 Returns true when the designated server is UP, and false when it is either
8357 DOWN or in maintenance mode. If <backend> is omitted, then the server is
8358 looked up in the current backend. The function takes no arguments since it
8359 is used as a boolean. It is mainly used to take action based on an external
8360 status reported via a health check (eg: a geographical site's availability).
8361 Another possible use which is more of a hack consists in using dummy servers
8362 as boolean variables that can be enabled or disabled from the CLI, so that
8363 rules depending on those ACLs can be tweaked in realtime.
8364
Willy Tarreauc735a072011-03-29 00:57:02 +02008365table_avl <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008366table_avl(<table>) <integer>
Willy Tarreauc735a072011-03-29 00:57:02 +02008367 Returns the total number of available entries in the current proxy's
8368 stick-table or in the designated stick-table. See also table_cnt.
8369
8370table_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008371table_cnt(<table>) <integer>
Willy Tarreauc735a072011-03-29 00:57:02 +02008372 Returns the total number of entries currently in use in the current proxy's
8373 stick-table or in the designated stick-table. See also src_conn_cnt and
8374 table_avl for other entry counting methods.
8375
Willy Tarreau0ba27502007-12-24 16:55:16 +01008376
Willy Tarreaue9656522010-08-17 15:40:09 +020083777.5.2. Matching contents at Layer 4 (also called Layer 6)
8378---------------------------------------------------------
Willy Tarreau62644772008-07-16 18:36:06 +02008379
8380A second set of criteria depends on data found in buffers, but which can change
8381during analysis. This requires that some data has been buffered, for instance
Willy Tarreaue9656522010-08-17 15:40:09 +02008382through TCP request content inspection. Please see the "tcp-request content"
8383keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +02008384
Willy Tarreaub6672b52011-12-12 17:23:41 +01008385rep_ssl_hello_type <integer>
8386 Returns true when data in the response buffer looks like a complete SSL (v3
8387 or superior) hello message and handshake type is equal to <integer>.
8388 This test was designed to be used with TCP response content inspection: a
Willy Tarreau7875d092012-09-10 08:20:03 +02008389 SSL session ID may be fetched. Note that this only applies to raw contents
8390 found in the request buffer and not to contents deciphered via an SSL data
8391 layer, so this will not work with "bind" lines having the "ssl" option.
Willy Tarreaub6672b52011-12-12 17:23:41 +01008392
Willy Tarreau62644772008-07-16 18:36:06 +02008393req_len <integer>
Emeric Brunbede3d02009-06-30 17:54:00 +02008394 Returns true when the length of the data in the request buffer matches the
Willy Tarreau62644772008-07-16 18:36:06 +02008395 specified range. It is important to understand that this test does not
8396 return false as long as the buffer is changing. This means that a check with
8397 equality to zero will almost always immediately match at the beginning of the
8398 session, while a test for more data will wait for that data to come in and
8399 return false only when haproxy is certain that no more data will come in.
8400 This test was designed to be used with TCP request content inspection.
8401
Willy Tarreau2492d5b2009-07-11 00:06:00 +02008402req_proto_http
8403 Returns true when data in the request buffer look like HTTP and correctly
8404 parses as such. It is the same parser as the common HTTP request parser which
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008405 is used so there should be no surprises. This test can be used for instance
Willy Tarreau2492d5b2009-07-11 00:06:00 +02008406 to direct HTTP traffic to a given port and HTTPS traffic to another one
8407 using TCP request content inspection rules.
8408
Emeric Brunbede3d02009-06-30 17:54:00 +02008409req_rdp_cookie <string>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008410req_rdp_cookie(<name>) <string>
Emeric Brunbede3d02009-06-30 17:54:00 +02008411 Returns true when data in the request buffer look like the RDP protocol, and
8412 a cookie is present and equal to <string>. By default, any cookie name is
8413 checked, but a specific cookie name can be specified in parenthesis. The
8414 parser only checks for the first cookie, as illustrated in the RDP protocol
8415 specification. The cookie name is case insensitive. This ACL can be useful
8416 with the "MSTS" cookie, as it can contain the user name of the client
8417 connecting to the server if properly configured on the client. This can be
8418 used to restrict access to certain servers to certain users.
8419
8420req_rdp_cookie_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008421req_rdp_cookie_cnt(<name>) <integer>
Emeric Brunbede3d02009-06-30 17:54:00 +02008422 Returns true when the data in the request buffer look like the RDP protocol
8423 and the number of RDP cookies matches the specified range (typically zero or
8424 one). Optionally a specific cookie name can be checked. This is a simple way
8425 of detecting the RDP protocol, as clients generally send the MSTS or MSTSHASH
8426 cookies.
8427
Willy Tarreaub6672b52011-12-12 17:23:41 +01008428req_ssl_hello_type <integer>
8429 Returns true when data in the request buffer looks like a complete SSL (v3
8430 or superior) hello message and handshake type is equal to <integer>.
8431 This test was designed to be used with TCP request content inspection: an
Willy Tarreau7875d092012-09-10 08:20:03 +02008432 SSL session ID may be fetched. Note that this only applies to raw contents
8433 found in the request buffer and not to contents deciphered via an SSL data
8434 layer, so this will not work with "bind" lines having the "ssl" option.
Willy Tarreaub6672b52011-12-12 17:23:41 +01008435
8436req_ssl_sni <string>
8437 Returns true when data in the request buffer looks like a complete SSL (v3
8438 or superior) client hello message with a Server Name Indication TLS extension
8439 (SNI) matching <string>. SNI normally contains the name of the host the
8440 client tries to connect to (for recent browsers). SNI is useful for allowing
8441 or denying access to certain hosts when SSL/TLS is used by the client. This
8442 test was designed to be used with TCP request content inspection. If content
8443 switching is needed, it is recommended to first wait for a complete client
Willy Tarreau7875d092012-09-10 08:20:03 +02008444 hello (type 1), like in the example below. Note that this only applies to raw
8445 contents found in the request buffer and not to contents deciphered via an
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008446 SSL transport layer, so this will not work with "bind" lines having the "ssl"
Willy Tarreau7875d092012-09-10 08:20:03 +02008447 option. See also "ssl_sni" below.
Willy Tarreaub6672b52011-12-12 17:23:41 +01008448
8449 Examples :
8450 # Wait for a client hello for at most 5 seconds
8451 tcp-request inspect-delay 5s
8452 tcp-request content accept if { req_ssl_hello_type 1 }
8453 use_backend bk_allow if { req_ssl_sni -f allowed_sites }
8454 default_backend bk_sorry_page
8455
Willy Tarreau62644772008-07-16 18:36:06 +02008456req_ssl_ver <decimal>
8457 Returns true when data in the request buffer look like SSL, with a protocol
8458 version matching the specified range. Both SSLv2 hello messages and SSLv3
8459 messages are supported. The test tries to be strict enough to avoid being
8460 easily fooled. In particular, it waits for as many bytes as announced in the
8461 message header if this header looks valid (bound to the buffer size). Note
8462 that TLSv1 is announced as SSL version 3.1. This test was designed to be used
Willy Tarreau7875d092012-09-10 08:20:03 +02008463 with TCP request content inspection. Note that this only applies to raw
8464 contents found in the request buffer and not to contents deciphered via an
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008465 SSL transport layer, so this will not work with "bind" lines having the "ssl"
Willy Tarreau7875d092012-09-10 08:20:03 +02008466 option.
8467
Emeric Brun2525b6b2012-10-18 15:59:43 +02008468ssl_c_ca_err <integer>
8469 Returns true when the incoming connection was made over an SSL/TLS transport
8470 layer, and the ID of the first error detected during verification of the
8471 client certificate at depth > 0 matches the specified value (check man verify
8472 for possible values). Note that error zero means no error was encountered
8473 during this verification process.
8474
8475ssl_c_ca_err_depth <integer>
8476 Returns true when the incoming connection was made over an SSL/TLS transport
8477 layer, and the depth in the CA chain of the first error detected during the
8478 verification of the client certificate matches the specified value. When no
8479 error is found, depth 0 is returned.
8480
8481ssl_c_err <integer>
8482 Returns true when the incoming connection was made over an SSL/TLS transport
8483 layer, and the ID of the first error detected during verification at depth==0
8484 matches the specified value (check man verify for possible values). Note that
8485 error zero means no error was encountered during this verification process.
8486
Emeric Brun87855892012-10-17 17:39:35 +02008487ssl_c_i_dn <string>
8488ssl_c_i_dn(entry[,occ]) <string>
8489 If no entry specified, returns true when the incoming connection was made
8490 over an SSL/TLS transport layer, and the full distinguished name of the
8491 issuer of the certificate presented by the client matches the specified
8492 string. Otherwise returns true if the value of the first given entry from
8493 the beginning of the DN matches the specified string. If a positive/negative
8494 occurrence number is specified as the optional second argument, it returns
8495 true if the value of the nth given entry value from the beginning/end of the
8496 DN matches the specified string.
8497
Emeric Brun7f56e742012-10-19 18:15:40 +02008498ssl_c_key_alg <string>
8499 Returns true when the incoming connection was made over an SSL/TLS transport
8500 layer, and the name of the algorithm used to generate the key of the
8501 certificate presented by the client matches the string.
8502
Emeric Brunce5ad802012-10-22 14:11:22 +02008503ssl_c_notafter <string>
8504 Returns true when the incoming connection was made over an SSL/TLS transport
8505 layer, and the end date of the certificate presented by the client matches
8506 the string formatted as YYMMDDhhmmss[Z].
8507
8508ssl_c_notbefore <string>
8509 Returns true when the incoming connection was made over an SSL/TLS transport
8510 layer, and the start date of the certificate presented by the client matches
8511 the string formatted as YYMMDDhhmmss[Z].
8512
Emeric Brun87855892012-10-17 17:39:35 +02008513ssl_c_s_dn <string>
8514ssl_c_s_dn(entry[,occ]) <string>
8515 If no entry specified, returns true when the incoming connection was made
8516 over an SSL/TLS transport layer, and the full distinguished name of the
8517 subject of the certificate presented by the client matches the specified
8518 string. Otherwise returns true if the value of the first given entry from
8519 the beginning of the DN matches the specified string. If a positive/negative
8520 occurrence number is specified as the optional second argument, it returns
8521 true if the value of the nth given entry value from the beginning/end of the
8522 DN matches the specified string.
8523
Willy Tarreau8d598402012-10-22 17:58:39 +02008524ssl_c_serial <hexa>
8525 Returns true when the incoming connection was made over an SSL/TLS transport
8526 layer, and the serial of the certificate presented by the client matches
8527 the value written in hexa.
8528
Emeric Brun7f56e742012-10-19 18:15:40 +02008529ssl_c_sig_alg <string>
8530 Returns true when the incoming connection was made over an SSL/TLS transport
8531 layer, and the name of the algorithm used to sign the certificate presented
8532 by the client matches the string.
8533
Emeric Brun2525b6b2012-10-18 15:59:43 +02008534ssl_c_verify <integer>
8535 Returns true when the incoming connection was made over an SSL/TLS transport
8536 layer, and the verify result matches the specified value (check man verify
8537 for possible values). Zero indicates no error was detected.
8538
Emeric Bruna7359fd2012-10-17 15:03:11 +02008539ssl_c_version <integer>
8540 Returns true when the incoming connection was made over an SSL/TLS transport
8541 layer, and the version of the certificate presented by the client matches
8542 the value.
8543
Emeric Brun87855892012-10-17 17:39:35 +02008544ssl_f_i_dn <string>
8545ssl_f_i_dn(entry[,occ]) <string>
8546 If no entry specified, returns true when the incoming connection was made
8547 over an SSL/TLS transport layer, and the full distinguished name of the
8548 issuer of the certificate presented by the frontend matches the specified
8549 string. Otherwise returns true if the value of the first given entry from
8550 the beginning of the DN matches the specified string. If a positive/negative
8551 occurrence number is specified as the optional second argument, it returns
8552 true if the value of the nth given entry value from the beginning/end of the
8553 DN matches the specified string.
8554
Emeric Brun7f56e742012-10-19 18:15:40 +02008555ssl_c_key_alg <string>
8556 Returns true when the incoming connection was made over an SSL/TLS transport
8557 layer, and the name of the algorithm used to generate the key of the
8558 certificate presented by the frontend matches the string.
8559
Emeric Brunce5ad802012-10-22 14:11:22 +02008560ssl_f_notafter <string>
8561 Returns true when the incoming connection was made over an SSL/TLS transport
8562 layer, and the end date of the certificate presented by the frontend matches
8563 the string formatted as YYMMDDhhmmss[Z].
8564
8565ssl_f_notbefore <string>
8566 Returns true when the incoming connection was made over an SSL/TLS transport
8567 layer, and the start date of the certificate presented by the frontend matches
8568 the string formatted as YYMMDDhhmmss[Z].
8569
Emeric Brun87855892012-10-17 17:39:35 +02008570ssl_f_s_dn <string>
8571ssl_f_s_dn(entry[,occ]) <string>
8572 If no entry specified, returns true when the incoming connection was made
8573 over an SSL/TLS transport layer, and the full distinguished name of the
8574 subject of the certificate presented by the frontend matches the specified
8575 string. Otherwise returns true if the value of the first given entry from
8576 the beginning of the DN matches the specified string. If a positive/negative
8577 occurrence number is specified as the optional second argument, it returns
8578 true if the value of the nth given entry value from the beginning/end of the
8579 DN matches the specified string.
8580
Willy Tarreau8d598402012-10-22 17:58:39 +02008581ssl_f_serial <hexa>
8582 Returns true when the incoming connection was made over an SSL/TLS transport
8583 layer, and the serial of the certificate presented by the frontend matches
8584 the value written in hexa.
8585
Emeric Brun7f56e742012-10-19 18:15:40 +02008586ssl_f_sig_alg <string>
8587 Returns true when the incoming connection was made over an SSL/TLS transport
8588 layer, and the name of the algorithm used to sign the certificate presented
8589 by the frontend matches the string.
8590
Emeric Bruna7359fd2012-10-17 15:03:11 +02008591ssl_f_version <integer>
8592 Returns true when the incoming connection was made over an SSL/TLS transport
8593 layer, and the version of the certificate presented by the frontend matches
8594 the value.
8595
Emeric Brun2525b6b2012-10-18 15:59:43 +02008596ssl_fc
8597 Returns true when the front connection was made via an SSL/TLS transport
8598 layer and is locally deciphered. This means it has matched a socket declared
8599 with a "bind" line having the "ssl" option.
8600
Emeric Brun589fcad2012-10-16 14:13:26 +02008601ssl_fc_alg_keysize <integer>
8602 Returns true when the incoming connection was made over an SSL/TLS transport
8603 layer and the symmetric cipher key size supported in bits matches the value.
8604
8605ssl_fc_cipher <string>
8606 returns true when the incoming connection was made over an ssl/tls transport
8607 layer and the name of the used cipher matches the string.
8608
Emeric Brun2525b6b2012-10-18 15:59:43 +02008609ssl_fc_has_crt
8610 Returns true if a client certificate is present in an incoming connection over
8611 SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
8612
8613ssl_fc_has_sni
Willy Tarreau7875d092012-09-10 08:20:03 +02008614 This is used to check for presence of a Server Name Indication TLS extension
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008615 in an incoming connection was made over an SSL/TLS transport layer. Returns
8616 true when the incoming connection presents a TLS SNI field. This requires
8617 that the SSL library is build with support for TLS extensions enabled (check
8618 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02008619
Emeric Brun2525b6b2012-10-18 15:59:43 +02008620ssl_fc_npn <string>
Willy Tarreaua33c6542012-10-15 13:19:06 +02008621 Returns true when the incoming connection was made over an SSL/TLS transport
8622 layer which deciphered it and found a Next Protocol Negociation TLS extension
8623 sent by the client, matching the specified string. This requires that the SSL
8624 library is build with support for TLS extensions enabled (check haproxy -vv).
Willy Tarreau6c9a3d52012-10-18 18:57:14 +02008625 Note that the TLS NPN extension is not advertised unless the "npn" keyword on
8626 the "bind" line specifies a protocol list. Also, nothing forces the client to
8627 pick a protocol from this list, any other one may be requested.
Willy Tarreaua33c6542012-10-15 13:19:06 +02008628
Emeric Brun589fcad2012-10-16 14:13:26 +02008629ssl_fc_protocol <string>
8630 Returns true when the incoming connection was made over an SSL/TLS transport
8631 layer and the name of the used protocol matches the string.
8632
Emeric Brun2525b6b2012-10-18 15:59:43 +02008633ssl_fc_sni <string>
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008634 Returns true when the incoming connection was made over an SSL/TLS transport
8635 layer which deciphered it and found a Server Name Indication TLS extension
8636 sent by the client, matching the specified string. In HTTPS, the SNI field
8637 (when present) is equal to the requested host name. This match is different
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +02008638 from "req_ssl_sni" above in that it applies to the connection being
8639 deciphered by haproxy and not to SSL contents being blindly forwarded.
Emeric Brun2525b6b2012-10-18 15:59:43 +02008640 See also "ssl_fc_sni_end" and "ssl_fc_sni_req" below. This requires that the
8641 SSL library is build with support for TLS extensions enabled (check
8642 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02008643
Emeric Brun2525b6b2012-10-18 15:59:43 +02008644ssl_fc_sni_end <string>
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008645 Returns true when the incoming connection was made over an SSL/TLS transport
8646 layer which deciphered it and found a Server Name Indication TLS extension
8647 sent by the client, ending like the specified string. In HTTPS, the SNI field
8648 (when present) is equal to the requested host name. This match is different
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +02008649 from "req_ssl_sni" above in that it applies to the connection being
8650 deciphered by haproxy and not to SSL contents being blindly forwarded. This
8651 requires that the SSL library is build with support for TLS extensions
8652 enabled (check haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02008653
Emeric Brun2525b6b2012-10-18 15:59:43 +02008654ssl_fc_sni_reg <regex>
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008655 Returns true when the incoming connection was made over an SSL/TLS transport
8656 layer which deciphered it and found a Server Name Indication TLS extension
8657 sent by the client, matching the specified regex. In HTTPS, the SNI field
8658 (when present) is equal to the requested host name. This match is different
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +02008659 from "req_ssl_sni" above in that it applies to the connection being
8660 deciphered by haproxy and not to SSL contents being blindly forwarded. This
8661 requires that the SSL library is build with support for TLS extensions
8662 enabled (check haproxy -vv).
Willy Tarreau62644772008-07-16 18:36:06 +02008663
Emeric Brun589fcad2012-10-16 14:13:26 +02008664ssl_fc_use_keysize <integer>
8665 Returns true when the incoming connection was made over an SSL/TLS transport
8666 layer and the symmetric cipher key size used in bits matches the value.
8667
Willy Tarreaub6fb4202008-07-20 11:18:28 +02008668wait_end
8669 Waits for the end of the analysis period to return true. This may be used in
8670 conjunction with content analysis to avoid returning a wrong verdict early.
8671 It may also be used to delay some actions, such as a delayed reject for some
8672 special addresses. Since it either stops the rules evaluation or immediately
8673 returns true, it is recommended to use this acl as the last one in a rule.
8674 Please note that the default ACL "WAIT_END" is always usable without prior
8675 declaration. This test was designed to be used with TCP request content
8676 inspection.
8677
8678 Examples :
8679 # delay every incoming request by 2 seconds
8680 tcp-request inspect-delay 2s
8681 tcp-request content accept if WAIT_END
8682
8683 # don't immediately tell bad guys they are rejected
8684 tcp-request inspect-delay 10s
8685 acl goodguys src 10.0.0.0/24
8686 acl badguys src 10.0.1.0/24
8687 tcp-request content accept if goodguys
8688 tcp-request content reject if badguys WAIT_END
8689 tcp-request content reject
8690
Willy Tarreau62644772008-07-16 18:36:06 +02008691
Willy Tarreauc57f0e22009-05-10 13:12:33 +020086927.5.3. Matching at Layer 7
8693--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01008694
Willy Tarreau62644772008-07-16 18:36:06 +02008695A third set of criteria applies to information which can be found at the
Willy Tarreau0ba27502007-12-24 16:55:16 +01008696application layer (layer 7). Those require that a full HTTP request has been
8697read, and are only evaluated then. They may require slightly more CPU resources
8698than the layer 4 ones, but not much since the request and response are indexed.
8699
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02008700base <string>
8701 Returns true when the concatenation of the first Host header and the path
8702 part of the request, which starts at the first slash and ends before the
8703 question mark, equals one of the strings. It may be used to match known
8704 files in virtual hosting environments, such as "www.example.com/favicon.ico".
8705 See also "path" and "uri".
8706
8707base_beg <string>
8708 Returns true when the base (see above) begins with one of the strings. This
8709 can be used to send certain directory names to alternative backends. See also
8710 "path_beg".
8711
8712base_dir <string>
8713 Returns true when one of the strings is found isolated or delimited with
8714 slashes in the base (see above). Probably of little use, see "url_dir" and
8715 "path_dir" instead.
8716
8717base_dom <string>
8718 Returns true when one of the strings is found isolated or delimited with dots
8719 in the base (see above). Probably of little use, see "path_dom" and "url_dom"
8720 instead.
8721
8722base_end <string>
8723 Returns true when the base (see above) ends with one of the strings. This may
8724 be used to control file name extension, though "path_end" is cheaper.
8725
8726base_len <integer>
8727 Returns true when the base (see above) length matches the values or ranges
8728 specified. This may be used to detect abusive requests for instance.
8729
8730base_reg <regex>
8731 Returns true when the base (see above) matches one of the regular
8732 expressions. It can be used any time, but it is important to remember that
8733 regex matching is slower than other methods. See also "path_reg", "url_reg"
8734 and all "base_" criteria.
8735
8736base_sub <string>
8737 Returns true when the base (see above) contains one of the strings. It can be
8738 used to detect particular patterns in paths, such as "../" for example. See
8739 also "base_dir".
8740
Willy Tarreau04aa6a92012-04-06 18:57:55 +02008741cook(<name>) <string>
8742 All "cook*" matching criteria inspect all "Cookie" headers to find a cookie
8743 with the name between parenthesis. If multiple occurrences of the cookie are
8744 found in the request, they will all be evaluated. Spaces around the name and
8745 the value are ignored as requested by the Cookie specification (RFC6265). The
8746 cookie name is case-sensitive. Use the scook() variant for response cookies
8747 sent by the server.
8748
8749 The "cook" criteria returns true if any of the request cookies <name> match
8750 any of the strings. This can be used to check exact for values. For instance,
8751 checking that the "profile" cookie is set to either "silver" or "gold" :
8752
8753 cook(profile) silver gold
8754
8755cook_beg(<name>) <string>
8756 Returns true if any of the request cookies <name> begins with one of the
8757 strings. See "cook" for more information on cookie matching. Use the
8758 scook_beg() variant for response cookies sent by the server.
8759
8760cook_cnt(<name>) <integer>
8761 Returns true when the number of occurrences of the specified cookie matches
8762 the values or ranges specified. This is used to detect presence, absence or
8763 abuse of a specific cookie. See "cook" for more information on header
8764 matching. Use the scook_cnt() variant for response cookies sent by the
8765 server.
8766
8767cook_dir(<name>) <string>
8768 Returns true if any of the request cookies <name> contains one of the strings
8769 either isolated or delimited by slashes. This is used to perform filename or
8770 directory name matching, though it generally is of limited use with cookies.
8771 See "cook" for more information on cookie matching. Use the scook_dir()
8772 variant for response cookies sent by the server.
8773
8774cook_dom(<name>) <string>
8775 Returns true if any of the request cookies <name> contains one of the strings
8776 either isolated or delimited by dots. This is used to perform domain name
8777 matching. See "cook" for more information on cookie matching. Use the
8778 scook_dom() variant for response cookies sent by the server.
8779
8780cook_end(<name>) <string>
8781 Returns true if any of the request cookies <name> ends with one of the
8782 strings. See "cook" for more information on cookie matching. Use the
8783 scook_end() variant for response cookies sent by the server.
8784
8785cook_len(<name>) <integer>
8786 Returns true if any of the request cookies <name> has a length which matches
8787 the values or ranges specified. This may be used to detect empty or too large
8788 cookie values. Note that an absent cookie does not match a zero-length test.
8789 See "cook" for more information on cookie matching. Use the scook_len()
8790 variant for response cookies sent by the server.
8791
8792cook_reg(<name>) <regex>
8793 Returns true if any of the request cookies <name> matches any of the regular
8794 expressions. It can be used at any time, but it is important to remember that
8795 regex matching is slower than other methods. See also other "cook_" criteria,
8796 as well as "cook" for more information on cookie matching. Use the
8797 scook_reg() variant for response cookies sent by the server.
8798
8799cook_sub(<name>) <string>
8800 Returns true if any of the request cookies <name> contains at least one of
8801 the strings. See "cook" for more information on cookie matching. Use the
8802 scook_sub() variant for response cookies sent by the server.
8803
Willy Tarreau51539362012-05-08 12:46:28 +02008804cook_val(<name>) <integer>
8805 Returns true if any of the request cookies <name> starts with a number which
8806 matches the values or ranges specified. This may be used to select a server
8807 based on application-specific cookies. Note that an absent cookie does not
8808 match any value. See "cook" for more information on cookie matching. Use the
8809 scook_val() variant for response cookies sent by the server.
8810
Willy Tarreaud63335a2010-02-26 12:56:52 +01008811hdr <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008812hdr(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008813 Note: all the "hdr*" matching criteria either apply to all headers, or to a
8814 particular header whose name is passed between parenthesis and without any
8815 space. The header name is not case-sensitive. The header matching complies
8816 with RFC2616, and treats as separate headers all values delimited by commas.
Willy Tarreau185b5c42012-04-26 15:11:51 +02008817 If an occurrence number is specified as the optional second argument, only
8818 this occurrence will be considered. Positive values indicate a position from
8819 the first occurrence, 1 being the first one. Negative values indicate
8820 positions relative to the last one, -1 being the last one. Use the shdr()
8821 variant for response headers sent by the server.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008822
8823 The "hdr" criteria returns true if any of the headers matching the criteria
Willy Tarreau25c1ebc2012-04-25 16:21:44 +02008824 match any of the strings. This can be used to check for exact values. For
Willy Tarreaud63335a2010-02-26 12:56:52 +01008825 instance, checking that "connection: close" is set :
8826
8827 hdr(Connection) -i close
8828
8829hdr_beg <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008830hdr_beg(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008831 Returns true when one of the headers begins with one of the strings. See
8832 "hdr" for more information on header matching. Use the shdr_beg() variant for
8833 response headers sent by the server.
8834
8835hdr_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008836hdr_cnt(<header>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008837 Returns true when the number of occurrence of the specified header matches
8838 the values or ranges specified. It is important to remember that one header
8839 line may count as several headers if it has several values. This is used to
8840 detect presence, absence or abuse of a specific header, as well as to block
8841 request smuggling attacks by rejecting requests which contain more than one
8842 of certain headers. See "hdr" for more information on header matching. Use
8843 the shdr_cnt() variant for response headers sent by the server.
8844
8845hdr_dir <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008846hdr_dir(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008847 Returns true when one of the headers contains one of the strings either
8848 isolated or delimited by slashes. This is used to perform filename or
8849 directory name matching, and may be used with Referer. See "hdr" for more
8850 information on header matching. Use the shdr_dir() variant for response
8851 headers sent by the server.
8852
8853hdr_dom <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008854hdr_dom(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008855 Returns true when one of the headers contains one of the strings either
8856 isolated or delimited by dots. This is used to perform domain name matching,
8857 and may be used with the Host header. See "hdr" for more information on
8858 header matching. Use the shdr_dom() variant for response headers sent by the
8859 server.
8860
8861hdr_end <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008862hdr_end(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008863 Returns true when one of the headers ends with one of the strings. See "hdr"
8864 for more information on header matching. Use the shdr_end() variant for
8865 response headers sent by the server.
8866
8867hdr_ip <ip_address>
Willy Tarreauceb4ac92012-04-28 00:41:46 +02008868hdr_ip(<header>[,<occ>]) <address>
8869 Returns true when one of the headers' values contains an IPv4 or IPv6 address
8870 matching <address>. This is mainly used with headers such as X-Forwarded-For
8871 or X-Client-IP. See "hdr" for more information on header matching. Use the
Willy Tarreaud63335a2010-02-26 12:56:52 +01008872 shdr_ip() variant for response headers sent by the server.
8873
Willy Tarreau0e698542011-09-16 08:32:32 +02008874hdr_len <integer>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008875hdr_len(<header>[,<occ>]) <integer>
Willy Tarreau0e698542011-09-16 08:32:32 +02008876 Returns true when at least one of the headers has a length which matches the
8877 values or ranges specified. This may be used to detect empty or too large
8878 headers. See "hdr" for more information on header matching. Use the
8879 shdr_len() variant for response headers sent by the server.
8880
Willy Tarreaud63335a2010-02-26 12:56:52 +01008881hdr_reg <regex>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008882hdr_reg(<header>[,<occ>]) <regex>
Willy Tarreau04aa6a92012-04-06 18:57:55 +02008883 Returns true it one of the headers matches one of the regular expressions. It
Willy Tarreaud63335a2010-02-26 12:56:52 +01008884 can be used at any time, but it is important to remember that regex matching
8885 is slower than other methods. See also other "hdr_" criteria, as well as
8886 "hdr" for more information on header matching. Use the shdr_reg() variant for
8887 response headers sent by the server.
8888
8889hdr_sub <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008890hdr_sub(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008891 Returns true when one of the headers contains one of the strings. See "hdr"
8892 for more information on header matching. Use the shdr_sub() variant for
8893 response headers sent by the server.
8894
8895hdr_val <integer>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008896hdr_val(<header>[,<occ>]) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008897 Returns true when one of the headers starts with a number which matches the
8898 values or ranges specified. This may be used to limit content-length to
8899 acceptable values for example. See "hdr" for more information on header
8900 matching. Use the shdr_val() variant for response headers sent by the server.
8901
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008902http_auth(<userlist>)
8903http_auth_group(<userlist>) <group> [<group>]*
Willy Tarreaud63335a2010-02-26 12:56:52 +01008904 Returns true when authentication data received from the client matches
8905 username & password stored on the userlist. It is also possible to
8906 use http_auth_group to check if the user is assigned to at least one
8907 of specified groups.
8908
8909 Currently only http basic auth is supported.
8910
Willy Tarreau85c27da2011-09-16 07:53:52 +02008911http_first_req
Willy Tarreau7f18e522010-10-22 20:04:13 +02008912 Returns true when the request being processed is the first one of the
8913 connection. This can be used to add or remove headers that may be missing
8914 from some requests when a request is not the first one, or even to perform
8915 some specific ACL checks only on the first request.
8916
Willy Tarreau6a06a402007-07-15 20:15:28 +02008917method <string>
8918 Applies to the method in the HTTP request, eg: "GET". Some predefined ACL
8919 already check for most common methods.
8920
Willy Tarreau6a06a402007-07-15 20:15:28 +02008921path <string>
8922 Returns true when the path part of the request, which starts at the first
8923 slash and ends before the question mark, equals one of the strings. It may be
8924 used to match known files, such as /favicon.ico.
8925
8926path_beg <string>
Willy Tarreau0ba27502007-12-24 16:55:16 +01008927 Returns true when the path begins with one of the strings. This can be used
8928 to send certain directory names to alternative backends.
Willy Tarreau6a06a402007-07-15 20:15:28 +02008929
Willy Tarreau6a06a402007-07-15 20:15:28 +02008930path_dir <string>
8931 Returns true when one of the strings is found isolated or delimited with
8932 slashes in the path. This is used to perform filename or directory name
8933 matching without the risk of wrong match due to colliding prefixes. See also
8934 "url_dir" and "path_sub".
8935
8936path_dom <string>
8937 Returns true when one of the strings is found isolated or delimited with dots
8938 in the path. This may be used to perform domain name matching in proxy
8939 requests. See also "path_sub" and "url_dom".
8940
Willy Tarreaud63335a2010-02-26 12:56:52 +01008941path_end <string>
8942 Returns true when the path ends with one of the strings. This may be used to
8943 control file name extension.
8944
Willy Tarreau0e698542011-09-16 08:32:32 +02008945path_len <integer>
8946 Returns true when the path length matches the values or ranges specified.
8947 This may be used to detect abusive requests for instance.
8948
Willy Tarreau6a06a402007-07-15 20:15:28 +02008949path_reg <regex>
8950 Returns true when the path matches one of the regular expressions. It can be
8951 used any time, but it is important to remember that regex matching is slower
8952 than other methods. See also "url_reg" and all "path_" criteria.
8953
Willy Tarreaud63335a2010-02-26 12:56:52 +01008954path_sub <string>
8955 Returns true when the path contains one of the strings. It can be used to
8956 detect particular patterns in paths, such as "../" for example. See also
8957 "path_dir".
8958
Willy Tarreau0ce3aa02012-04-25 18:46:33 +02008959payload(<offset>,<length>) <string>
8960 Returns true if the block of <length> bytes, starting at byte <offset> in the
8961 request or response buffer (depending on the rule) exactly matches one of the
8962 strings.
8963
8964payload_lv(<offset1>,<length>[,<offset2>])
8965 Returns true if the block whose size is specified at <offset1> for <length>
8966 bytes, and which starts at <offset2> if specified or just after the length in
8967 the request or response buffer (depending on the rule) exactly matches one of
8968 the strings. The <offset2> parameter also supports relative offsets if
8969 prepended with a '+' or '-' sign.
8970
Willy Tarreaud63335a2010-02-26 12:56:52 +01008971req_ver <string>
8972 Applies to the version string in the HTTP request, eg: "1.0". Some predefined
8973 ACL already check for versions 1.0 and 1.1.
8974
8975status <integer>
8976 Applies to the HTTP status code in the HTTP response, eg: "302". It can be
8977 used to act on responses depending on status ranges, for instance, remove
8978 any Location header if the response is not a 3xx.
8979
Willy Tarreau6a06a402007-07-15 20:15:28 +02008980url <string>
8981 Applies to the whole URL passed in the request. The only real use is to match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02008982 "*", for which there already is a predefined ACL. See also "base".
Willy Tarreau6a06a402007-07-15 20:15:28 +02008983
8984url_beg <string>
8985 Returns true when the URL begins with one of the strings. This can be used to
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02008986 check whether a URL begins with a slash or with a protocol scheme. See also
8987 "base_beg".
Willy Tarreau6a06a402007-07-15 20:15:28 +02008988
Willy Tarreau6a06a402007-07-15 20:15:28 +02008989url_dir <string>
8990 Returns true when one of the strings is found isolated or delimited with
8991 slashes in the URL. This is used to perform filename or directory name
8992 matching without the risk of wrong match due to colliding prefixes. See also
8993 "path_dir" and "url_sub".
8994
8995url_dom <string>
8996 Returns true when one of the strings is found isolated or delimited with dots
8997 in the URL. This is used to perform domain name matching without the risk of
8998 wrong match due to colliding prefixes. See also "url_sub".
8999
Willy Tarreaud63335a2010-02-26 12:56:52 +01009000url_end <string>
9001 Returns true when the URL ends with one of the strings. It has very limited
9002 use. "path_end" should be used instead for filename matching.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009003
Willy Tarreauceb4ac92012-04-28 00:41:46 +02009004url_ip <address>
9005 Applies to the IPv4 or IPv6 address specified in the absolute URI in an HTTP
9006 request. It can be used to prevent access to certain resources such as local
9007 network. It is useful with option "http_proxy".
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01009008
Willy Tarreau0e698542011-09-16 08:32:32 +02009009url_len <integer>
9010 Returns true when the url length matches the values or ranges specified. This
9011 may be used to detect abusive requests for instance.
9012
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01009013url_port <integer>
Willy Tarreau0ba27502007-12-24 16:55:16 +01009014 Applies to the port specified in the absolute URI in an HTTP request. It can
9015 be used to prevent access to certain resources. It is useful with option
Willy Tarreau198a7442008-01-17 12:05:32 +01009016 "http_proxy". Note that if the port is not specified in the request, port 80
Willy Tarreau0ba27502007-12-24 16:55:16 +01009017 is assumed.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01009018
Willy Tarreaud63335a2010-02-26 12:56:52 +01009019url_reg <regex>
9020 Returns true when the URL matches one of the regular expressions. It can be
9021 used any time, but it is important to remember that regex matching is slower
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02009022 than other methods. See also "base_reg", "path_reg" and all "url_" criteria.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01009023
Willy Tarreaud63335a2010-02-26 12:56:52 +01009024url_sub <string>
9025 Returns true when the URL contains one of the strings. It can be used to
9026 detect particular patterns in query strings for example. See also "path_sub".
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01009027
Willy Tarreau25c1ebc2012-04-25 16:21:44 +02009028urlp(<name>) <string>
9029 Note: all "urlp*" matching criteria apply to the first occurrence of the
9030 parameter <name> in the query string. The parameter name is case-sensitive.
9031
9032 The "urlp" matching criteria returns true if the designated URL parameter
9033 matches any of the strings. This can be used to check for exact values.
9034
9035urlp_beg(<name>) <string>
9036 Returns true when the URL parameter "<name>" begins with one of the strings.
9037 This can be used to check whether a URL begins with a slash or with a
9038 protocol scheme.
9039
9040urlp_dir(<name>) <string>
9041 Returns true when the URL parameter "<name>" contains one of the strings
9042 either isolated or delimited with slashes. This is used to perform filename
9043 or directory name matching in a specific URL parameter without the risk of
9044 wrong match due to colliding prefixes. See also "path_dir" and "urlp_sub".
9045
9046urlp_dom(<name>) <string>
9047 Returns true when one of the strings is found isolated or delimited with dots
9048 in the URL parameter "<name>". This is used to perform domain name matching
9049 in a specific URL parameter without the risk of wrong match due to colliding
9050 prefixes. See also "urlp_sub".
9051
9052urlp_end(<name>) <string>
9053 Returns true when the URL parameter "<name>" ends with one of the strings.
9054
9055urlp_ip(<name>) <ip_address>
Willy Tarreauceb4ac92012-04-28 00:41:46 +02009056 Returns true when the URL parameter "<name>" contains an IPv4 or IPv6 address
9057 which matches one of the specified addresses.
Willy Tarreau25c1ebc2012-04-25 16:21:44 +02009058
9059urlp_len(<name>) <integer>
9060 Returns true when the URL parameter "<name>" has a length matching the values
9061 or ranges specified. This is used to detect abusive requests for instance.
9062
9063urlp_reg(<name>) <regex>
9064 Returns true when the URL parameter "<name>" matches one of the regular
9065 expressions. It can be used any time, but it is important to remember that
9066 regex matching is slower than other methods. See also "path_reg" and all
9067 "urlp_" criteria.
9068
9069urlp_sub(<name>) <string>
9070 Returns true when the URL parameter "<name>" contains one of the strings. It
9071 can be used to detect particular patterns in query strings for example. See
9072 also "path_sub" and other "urlp_" criteria.
9073
Willy Tarreaua9fddca2012-07-31 07:51:48 +02009074urlp_val(<name>) <integer>
9075 Returns true when the URL parameter "<name>" starts with a number matching
9076 the values or ranges specified. Note that the absence of the parameter does
9077 not match anything. Integers are unsigned so it is not possible to match
9078 negative data.
9079
Willy Tarreau198a7442008-01-17 12:05:32 +01009080
Willy Tarreauc57f0e22009-05-10 13:12:33 +020090817.6. Pre-defined ACLs
9082---------------------
Willy Tarreauced27012008-01-17 20:35:34 +01009083
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009084Some predefined ACLs are hard-coded so that they do not have to be declared in
9085every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +02009086order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +01009087
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009088ACL name Equivalent to Usage
9089---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009090FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +02009091HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009092HTTP_1.0 req_ver 1.0 match HTTP version 1.0
9093HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +01009094HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
9095HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
9096HTTP_URL_SLASH url_beg / match URL beginning with "/"
9097HTTP_URL_STAR url * match URL equal to "*"
9098LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009099METH_CONNECT method CONNECT match HTTP CONNECT method
9100METH_GET method GET HEAD match HTTP GET or HEAD method
9101METH_HEAD method HEAD match HTTP HEAD method
9102METH_OPTIONS method OPTIONS match HTTP OPTIONS method
9103METH_POST method POST match HTTP POST method
9104METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +02009105RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009106REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +01009107TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009108WAIT_END wait_end wait for end of content analysis
9109---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01009110
Willy Tarreauced27012008-01-17 20:35:34 +01009111
Willy Tarreauc57f0e22009-05-10 13:12:33 +020091127.7. Using ACLs to form conditions
9113----------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01009114
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009115Some actions are only performed upon a valid condition. A condition is a
9116combination of ACLs with operators. 3 operators are supported :
Willy Tarreauced27012008-01-17 20:35:34 +01009117
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009118 - AND (implicit)
9119 - OR (explicit with the "or" keyword or the "||" operator)
9120 - Negation with the exclamation mark ("!")
Willy Tarreauced27012008-01-17 20:35:34 +01009121
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009122A condition is formed as a disjunctive form:
Willy Tarreauced27012008-01-17 20:35:34 +01009123
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009124 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreauced27012008-01-17 20:35:34 +01009125
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009126Such conditions are generally used after an "if" or "unless" statement,
9127indicating when the condition will trigger the action.
Willy Tarreauced27012008-01-17 20:35:34 +01009128
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009129For instance, to block HTTP requests to the "*" URL with methods other than
9130"OPTIONS", as well as POST requests without content-length, and GET or HEAD
9131requests with a content-length greater than 0, and finally every request which
9132is not either GET/HEAD/POST/OPTIONS !
Willy Tarreauced27012008-01-17 20:35:34 +01009133
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009134 acl missing_cl hdr_cnt(Content-length) eq 0
9135 block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
9136 block if METH_GET HTTP_CONTENT
9137 block unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreauced27012008-01-17 20:35:34 +01009138
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009139To select a different backend for requests to static contents on the "www" site
9140and to every request on the "img", "video", "download" and "ftp" hosts :
Willy Tarreauced27012008-01-17 20:35:34 +01009141
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009142 acl url_static path_beg /static /images /img /css
9143 acl url_static path_end .gif .png .jpg .css .js
9144 acl host_www hdr_beg(host) -i www
9145 acl host_static hdr_beg(host) -i img. video. download. ftp.
Willy Tarreauced27012008-01-17 20:35:34 +01009146
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009147 # now use backend "static" for all static-only hosts, and for static urls
9148 # of host "www". Use backend "www" for the rest.
9149 use_backend static if host_static or host_www url_static
9150 use_backend www if host_www
Willy Tarreauced27012008-01-17 20:35:34 +01009151
Willy Tarreau95fa4692010-02-01 13:05:50 +01009152It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
9153expressions that are built on the fly without needing to be declared. They must
9154be enclosed between braces, with a space before and after each brace (because
Jamie Gloudon801a0a32012-08-25 00:18:33 -04009155the braces must be seen as independent words). Example :
Willy Tarreau95fa4692010-02-01 13:05:50 +01009156
9157 The following rule :
9158
9159 acl missing_cl hdr_cnt(Content-length) eq 0
9160 block if METH_POST missing_cl
9161
9162 Can also be written that way :
9163
9164 block if METH_POST { hdr_cnt(Content-length) eq 0 }
9165
9166It is generally not recommended to use this construct because it's a lot easier
9167to leave errors in the configuration when written that way. However, for very
9168simple rules matching only one source IP address for instance, it can make more
9169sense to use them than to declare ACLs with random names. Another example of
9170good use is the following :
9171
9172 With named ACLs :
9173
9174 acl site_dead nbsrv(dynamic) lt 2
9175 acl site_dead nbsrv(static) lt 2
9176 monitor fail if site_dead
9177
9178 With anonymous ACLs :
9179
9180 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
9181
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009182See section 4.2 for detailed help on the "block" and "use_backend" keywords.
Willy Tarreauced27012008-01-17 20:35:34 +01009183
Willy Tarreau5764b382007-11-30 17:46:49 +01009184
Willy Tarreaub937b7e2010-01-12 15:27:54 +010091857.8. Pattern extraction
9186-----------------------
9187
9188The stickiness features relies on pattern extraction in the request and
9189response. Sometimes the data needs to be converted first before being stored,
9190for instance converted from ASCII to IP or upper case to lower case.
9191
9192All these operations of data extraction and conversion are defined as
9193"pattern extraction rules". A pattern rule always has the same format. It
9194begins with a single pattern fetch word, potentially followed by a list of
9195arguments within parenthesis then an optional list of transformations. As
9196much as possible, the pattern fetch functions use the same name as their
9197equivalent used in ACLs.
9198
9199The list of currently supported pattern fetch functions is the following :
9200
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02009201 base This returns the concatenation of the first Host header and the
9202 path part of the request, which starts at the first slash and
9203 ends before the question mark. It can be useful in virtual
9204 hosted environments to detect URL abuses as well as to improve
9205 shared caches efficiency. Using this with a limited size stick
9206 table also allows one to collect statistics about most commonly
9207 requested objects by host/path.
9208
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009209 src This is the source IPv4 address of the client of the session.
David du Colombier9a6d3c92011-03-17 10:40:24 +01009210 It is of type IPv4 and works on both IPv4 and IPv6 tables.
9211 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent,
9212 according to RFC 4291.
9213
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009214 dst This is the destination IPv4 address of the session on the
9215 client side, which is the address the client connected to.
9216 It can be useful when running in transparent mode. It is of
David du Colombier9a6d3c92011-03-17 10:40:24 +01009217 type IPv4 and works on both IPv4 and IPv6 tables.
9218 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent,
9219 according to RFC 4291.
9220
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009221 dst_port This is the destination TCP port of the session on the client
9222 side, which is the port the client connected to. This might be
9223 used when running in transparent mode or when assigning dynamic
9224 ports to some clients for a whole application session. It is of
9225 type integer and only works with such tables.
9226
Willy Tarreau185b5c42012-04-26 15:11:51 +02009227 hdr(<name>[,<occ>])
9228 This extracts the last occurrence of header <name> in an HTTP
9229 request. Optionally, a specific occurrence might be specified as
9230 a position number. Positive values indicate a position from the
9231 first occurrence, with 1 being the first one. Negative values
9232 indicate positions relative to the last one, with -1 being the
9233 last one. A typical use is with the X-Forwarded-For header once
Willy Tarreaue428fb72011-12-16 21:50:30 +01009234 converted to IP, associated with an IP stick-table.
Willy Tarreau4a568972010-05-12 08:08:50 +02009235
Willy Tarreau6812bcf2012-04-29 09:28:50 +02009236 path This extracts the request's URL path (without the host part). A
9237 typical use is with prefetch-capable caches, and with portals
9238 which need to aggregate multiple information from databases and
9239 keep them in caches. Note that with outgoing caches, it would be
9240 wiser to use "url" instead.
9241
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009242 payload(<offset>,<length>)
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009243 This extracts a binary block of <length> bytes, and starting
9244 at bytes <offset> in the buffer of request or response (request
9245 on "stick on" or "stick match" or response in on "stick store
9246 response").
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009247
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009248 payload_lv(<offset1>,<length>[,<offset2>])
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009249 This extracts a binary block. In a first step the size of the
9250 block is read from response or request buffer at <offset>
9251 bytes and considered coded on <length> bytes. In a second step
9252 data of the block are read from buffer at <offset2> bytes
9253 (by default <lengthoffset> + <lengthsize>).
9254 If <offset2> is prefixed by '+' or '-', it is relative to
9255 <lengthoffset> + <lengthsize> else it is absolute.
9256 Ex: see SSL session id example in "stick table" chapter.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009257
Willy Tarreau25c1ebc2012-04-25 16:21:44 +02009258 src_port This is the source TCP port of the session on the client side,
9259 which is the port the client connected from. It is very unlikely
9260 that this function will be useful but it's available at no cost.
9261 It is of type integer and only works with such tables.
9262
Emeric Brun2525b6b2012-10-18 15:59:43 +02009263 ssl_c_ca_err Returns the ID of the first error detected during verify of the
9264 client certificate at depth > 0, or 0 if no error was detected.
9265
9266 ssl_c_ca_err_depth
9267 Returns the depth of the first error detected during verify. If
9268 no error is encountered in the CA chain, zero is returned.
9269
9270 ssl_c_err Returns the ID of the first error detected during verify of the
9271 client certificate at depth == 0, or 0 if no errors.
9272
Emeric Brun87855892012-10-17 17:39:35 +02009273 ssl_c_i_dn[(entry[,occ])]
9274 If no entry specified, returns the full distinguished name of
9275 the issuer of the certificate presented by the client when
9276 the incoming connection was made over an SSL/TLS transport
9277 layer. Otherwise returns the the value of the first given entry
9278 found from the the beginning of the DN. If a positive/negative
9279 occurrence number is specified as the optional second argument,
9280 it returns the value of the nth given entry found from the
9281 beginning/end of the DN. For instance to retrieve the common
9282 name ssl_c_i_dn(CN) and the second organization unit
9283 ssl_c_i_dn(OU,2).
9284
Emeric Brun7f56e742012-10-19 18:15:40 +02009285 ssl_c_key_alg
9286 Returns the name of the algorithm used to generate the key of
9287 the certificate presented by the client when the incoming
9288 connection was made over an SSL/TLS transport layer.
9289
Emeric Brunce5ad802012-10-22 14:11:22 +02009290 ssl_c_notafter
9291 Returns the end date presented by the client as a formatted
9292 string YYMMDDhhmmss[Z] when the incoming connection was made
9293 over an SSL/TLS transport layer.
9294
9295 ssl_c_notbefore
9296 Returns the start date presented by the client as a formatted
9297 string YYMMDDhhmmss[Z] when the incoming connection was made
9298 over an SSL/TLS transport layer.
9299
Emeric Brun87855892012-10-17 17:39:35 +02009300 ssl_c_s_dn[(entry[,occ])]
9301 If no entry specified, returns the full distinguished name of
9302 the subject of the certificate presented by the client when
9303 the incoming connection was made over an SSL/TLS transport
9304 layer. Otherwise returns the the value of the first given entry
9305 found from the the beginning of the DN. If a positive/negative
9306 occurrence number is specified as the optional second argument,
9307 it returns the value of the nth given entry found from the
9308 beginning/end of the DN. For instance to retrieve the common
9309 name ssl_c_s_dn(CN) and the second organization unit
9310 ssl_c_s_dn(OU,2).
9311
Willy Tarreau8d598402012-10-22 17:58:39 +02009312 ssl_c_serial Returns the serial of the certificate presented by the client
9313 when the incoming connection was made over an SSL/TLS transport
9314 layer.
9315
Emeric Brun7f56e742012-10-19 18:15:40 +02009316 ssl_c_sig_alg
9317 Returns the name of the algorithm used to sign the certificate
9318 presented by the client when the incoming connection was made
9319 over an SSL/TLS transport layer.
9320
Emeric Brun2525b6b2012-10-18 15:59:43 +02009321 ssl_c_verify Returns the verify result errorID when the incoming connection
9322 was made over an SSL/TLS transport layer, otherwise zero if no
9323 error is encountered.
9324
Emeric Bruna7359fd2012-10-17 15:03:11 +02009325 ssl_c_version
9326 Returns the version of the certificate presented by the client
9327 when the incoming connection was made over an SSL/TLS transport
9328 layer.
9329
Emeric Brun87855892012-10-17 17:39:35 +02009330 ssl_f_i_dn[(entry[,occ])]
9331 If no entry specified, returns the full distinguished name of
9332 the issuer of the certificate presented by the frontend when
9333 the incoming connection was made over an SSL/TLS transport
9334 layer. Otherwise returns the the value of the first given entry
9335 found from the the beginning of the DN. If a positive/negative
9336 occurrence number is specified as the optional second argument,
9337 it returns the value of the nth given entry found from the
9338 beginning/end of the DN. For instance to retrieve the common
9339 name ssl_f_i_dn(CN) and the second organization unit
9340 ssl_f_i_dn(OU,2).
9341
Emeric Brun7f56e742012-10-19 18:15:40 +02009342 ssl_f_key_alg
9343 Returns the name of the algorithm used to generate the key of
9344 the certificate presented by the frontend when the incoming
9345 connection was made over an SSL/TLS transport layer.
9346
Emeric Brunce5ad802012-10-22 14:11:22 +02009347 ssl_f_notafter
9348 Returns the end date presented by the frontend as a formatted
9349 string YYMMDDhhmmss[Z] when the incoming connection was made
9350 over an SSL/TLS transport layer.
9351
9352 ssl_f_notbefore
9353 Returns the start date presented by the frontend as a formatted
9354 string YYMMDDhhmmss[Z] when the incoming connection was made
9355 over an SSL/TLS transport layer.
9356
Emeric Brun87855892012-10-17 17:39:35 +02009357 ssl_f_s_dn[(entry[,occ])]
9358 If no entry specified, returns the full distinguished name of
9359 the subject of the certificate presented by the frontend when
9360 the incoming connection was made over an SSL/TLS transport
9361 layer. Otherwise returns the the value of the first given entry
9362 found from the the beginning of the DN. If a positive/negative
9363 occurrence number is specified as the optional second argument,
9364 it returns the value of the nth given entry found from the
9365 beginning/end of the DN. For instance to retrieve the common
9366 name ssl_f_s_dn(CN) and the second organization unit
9367 ssl_f_s_dn(OU,2).
9368
Willy Tarreau8d598402012-10-22 17:58:39 +02009369 ssl_f_serial Returns the serial of the certificate presented by the frontend
9370 when the incoming connection was made over an SSL/TLS transport
9371 layer.
9372
Emeric Brun7f56e742012-10-19 18:15:40 +02009373 ssl_f_sig_alg
9374 Returns the name of the algorithm used to sign the certificate
9375 presented by the frontend when the incoming connection was made
9376 over an SSL/TLS transport layer.
9377
Emeric Bruna7359fd2012-10-17 15:03:11 +02009378 ssl_f_version
9379 Returns the version of the certificate presented by the frontend
9380 when the incoming connection was made over an SSL/TLS transport
9381 layer.
9382
Emeric Brun2525b6b2012-10-18 15:59:43 +02009383 ssl_fc This checks the transport layer used on the front connection,
9384 and returns 1 if it was made via an SSL/TLS transport layer,
9385 otherwise zero.
9386
Emeric Brun589fcad2012-10-16 14:13:26 +02009387 ssl_fc_alg_keysize
9388 Returns the symmetric cipher key size support d in bits when the
9389 incoming connection was made over an SSL/TLS transport layer.
9390
9391 ssl_fc_cipher
9392 Returns the name of the used cipher when the incoming connection
9393 was made over an SSL/TLS transport layer.
9394
Emeric Brun2525b6b2012-10-18 15:59:43 +02009395 ssl_fc_has_crt
9396 Returns 1 if a client certificate is present in the front
9397 connection over SSL/TLS transport layer, otherwise 0.
9398
9399 ssl_fc_has_sni
9400 This checks the transport layer used by the front connection, and
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02009401 returns 1 if the connection was made via an SSL/TLS transport
9402 layer and the client sent a Server Name Indication TLS extension,
Willy Tarreau7875d092012-09-10 08:20:03 +02009403 otherwise zero. This requires that the SSL library is build with
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02009404 support for TLS extensions enabled (check haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02009405
Emeric Brun2525b6b2012-10-18 15:59:43 +02009406 ssl_fc_npn This extracts the Next Protocol Negociation field from an
Willy Tarreaua33c6542012-10-15 13:19:06 +02009407 incoming connection made via an SSL/TLS transport layer and
9408 locally deciphered by haproxy. The result is a string containing
9409 the protocol name advertised by the client. The SSL library must
9410 have been built with support for TLS extensions enabled (check
Emeric Brun2525b6b2012-10-18 15:59:43 +02009411 haproxy -vv). See also the "npn" bind keyword.
Willy Tarreaua33c6542012-10-15 13:19:06 +02009412
Emeric Brun589fcad2012-10-16 14:13:26 +02009413 ssl_fc_protocol
Cyril Bonté316a8cf2012-11-11 13:38:27 +01009414 Returns the name of the used protocol when the incoming
9415 connection was made over an SSL/TLS transport layer.
Emeric Brun589fcad2012-10-16 14:13:26 +02009416
Emeric Brunfe68f682012-10-16 14:59:28 +02009417 ssl_fc_session_id
9418 Returns the SSL ID of the front connection when the incoming
9419 connection was made over an SSL/TLS transport layer. Useful to
9420 stick on a given client.
9421
Emeric Brun2525b6b2012-10-18 15:59:43 +02009422 ssl_fc_sni This extracts the Server Name Indication field from an incoming
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02009423 connection made via an SSL/TLS transport layer and locally
9424 deciphered by haproxy. The result typically is a string matching
9425 the HTTPS host name (253 chars or less). The SSL library must
9426 have been built with support for TLS extensions enabled (check
9427 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02009428
Emeric Brun589fcad2012-10-16 14:13:26 +02009429 ssl_fc_use_keysize
9430 Returns the symmetric cipher key size used in bits when the
9431 incoming connection was made over an SSL/TLS transport layer.
9432
Willy Tarreau6812bcf2012-04-29 09:28:50 +02009433 url This extracts the request's URL as presented in the request. A
9434 typical use is with prefetch-capable caches, and with portals
9435 which need to aggregate multiple information from databases and
9436 keep them in caches. See also "path".
9437
9438 url_ip This extracts the IP address from the request's URL when the
9439 host part is presented as an IP address. Its use is very
9440 limited. For instance, a monitoring system might use this field
9441 as an alternative for the source IP in order to test what path a
9442 given source address would follow, or to force an entry in a
9443 table for a given source address.
9444
9445 url_port This extracts the port part from the request's URL. It probably
9446 is totally useless but it was available at no cost.
9447
bedis4c75cca2012-10-05 08:38:24 +02009448 url_param(<name>[,<delim>])
Cyril Bontédc4d9032012-04-08 21:57:39 +02009449 This extracts the first occurrence of the parameter <name> in
bedis4c75cca2012-10-05 08:38:24 +02009450 the parameter string of the request and uses the corresponding
9451 value to match. Optionally, a delimiter can be provided. If not
9452 then the question mark '?' is used by default.
9453 A typical use is to get sticky session through url for cases
9454 where cookies cannot be used.
9455
9456 Example :
9457 # match http://example.com/foo?PHPSESSIONID=some_id
9458 stick on url_param(PHPSESSIONID)
9459 # match http://example.com/foo;JSESSIONID=some_id
9460 stick on url_param(JSESSIONID,;)
David Cournapeau16023ee2010-12-23 20:55:41 +09009461
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009462 rdp_cookie(<name>)
Cyril Bontédc4d9032012-04-08 21:57:39 +02009463 This extracts the value of the rdp cookie <name> as a string
9464 and uses this value to match. This enables implementation of
9465 persistence based on the mstshash cookie. This is typically
9466 done if there is no msts cookie present.
Simon Hormanab814e02011-06-24 14:50:20 +09009467
Cyril Bontédc4d9032012-04-08 21:57:39 +02009468 This differs from "balance rdp-cookie" in that any balancing
9469 algorithm may be used and thus the distribution of clients
9470 to backend servers is not linked to a hash of the RDP
9471 cookie. It is envisaged that using a balancing algorithm
9472 such as "balance roundrobin" or "balance leastconnect" will
9473 lead to a more even distribution of clients to backend
9474 servers than the hash used by "balance rdp-cookie".
Simon Hormanab814e02011-06-24 14:50:20 +09009475
Cyril Bontédc4d9032012-04-08 21:57:39 +02009476 Example :
9477 listen tse-farm
9478 bind 0.0.0.0:3389
9479 # wait up to 5s for an RDP cookie in the request
9480 tcp-request inspect-delay 5s
9481 tcp-request content accept if RDP_COOKIE
9482 # apply RDP cookie persistence
9483 persist rdp-cookie
9484 # Persist based on the mstshash cookie
9485 # This is only useful makes sense if
9486 # balance rdp-cookie is not used
9487 stick-table type string size 204800
9488 stick on rdp_cookie(mstshash)
9489 server srv1 1.1.1.1:3389
9490 server srv1 1.1.1.2:3389
Simon Hormanab814e02011-06-24 14:50:20 +09009491
Cyril Bontédc4d9032012-04-08 21:57:39 +02009492 See also : "balance rdp-cookie", "persist rdp-cookie",
9493 "tcp-request" and the "req_rdp_cookie" ACL.
Simon Hormanab814e02011-06-24 14:50:20 +09009494
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009495 cookie(<name>)
Cyril Bontédc4d9032012-04-08 21:57:39 +02009496 This extracts the last occurrence of the cookie name <name> on a
Willy Tarreau28376d62012-04-26 21:26:10 +02009497 "Cookie" header line from the request, or a "Set-Cookie" header
9498 from the response, and uses the corresponding value to match. A
9499 typical use is to get multiple clients sharing a same profile
9500 use the same server. This can be similar to what "appsession"
9501 does with the "request-learn" statement, but with support for
9502 multi-peer synchronization and state keeping across restarts.
Willy Tarreaub3eb2212011-07-01 16:16:17 +02009503
Cyril Bontédc4d9032012-04-08 21:57:39 +02009504 See also : "appsession"
Willy Tarreaub3eb2212011-07-01 16:16:17 +02009505
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009506 set-cookie(<name>)
Willy Tarreau28376d62012-04-26 21:26:10 +02009507 This fetch function is deprecated and has been superseded by the
9508 "cookie" fetch which is capable of handling both requests and
9509 responses. This keyword will disappear soon.
9510
Cyril Bontédc4d9032012-04-08 21:57:39 +02009511 This extracts the last occurrence of the cookie name <name> on a
9512 "Set-Cookie" header line from the response and uses the
9513 corresponding value to match. This can be comparable to what
9514 "appsession" does with default options, but with support for
9515 multi-peer synchronization and state keeping across restarts.
Willy Tarreaub3eb2212011-07-01 16:16:17 +02009516
Cyril Bontédc4d9032012-04-08 21:57:39 +02009517 See also : "appsession"
Willy Tarreaub3eb2212011-07-01 16:16:17 +02009518
Simon Hormanab814e02011-06-24 14:50:20 +09009519
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009520The currently available list of transformations include :
9521
9522 lower Convert a string pattern to lower case. This can only be placed
9523 after a string pattern fetch function or after a conversion
9524 function returning a string type. The result is of type string.
9525
9526 upper Convert a string pattern to upper case. This can only be placed
9527 after a string pattern fetch function or after a conversion
9528 function returning a string type. The result is of type string.
9529
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009530 ipmask(<mask>) Apply a mask to an IPv4 address, and use the result for lookups
Willy Tarreaud31d6eb2010-01-26 18:01:41 +01009531 and storage. This can be used to make all hosts within a
9532 certain mask to share the same table entries and as such use
9533 the same server. The mask can be passed in dotted form (eg:
9534 255.255.255.0) or in CIDR form (eg: 24).
9535
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009536
Willy Tarreauc57f0e22009-05-10 13:12:33 +020095378. Logging
9538----------
Willy Tarreau844e3c52008-01-11 16:28:18 +01009539
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009540One of HAProxy's strong points certainly lies is its precise logs. It probably
9541provides the finest level of information available for such a product, which is
9542very important for troubleshooting complex environments. Standard information
9543provided in logs include client ports, TCP/HTTP state timers, precise session
9544state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009545to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009546headers.
9547
9548In order to improve administrators reactivity, it offers a great transparency
9549about encountered problems, both internal and external, and it is possible to
9550send logs to different sources at the same time with different level filters :
9551
9552 - global process-level logs (system errors, start/stop, etc..)
9553 - per-instance system and internal errors (lack of resource, bugs, ...)
9554 - per-instance external troubles (servers up/down, max connections)
9555 - per-instance activity (client connections), either at the establishment or
9556 at the termination.
9557
9558The ability to distribute different levels of logs to different log servers
9559allow several production teams to interact and to fix their problems as soon
9560as possible. For example, the system team might monitor system-wide errors,
9561while the application team might be monitoring the up/down for their servers in
9562real time, and the security team might analyze the activity logs with one hour
9563delay.
9564
9565
Willy Tarreauc57f0e22009-05-10 13:12:33 +020095668.1. Log levels
9567---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009568
Simon Hormandf791f52011-05-29 15:01:10 +09009569TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009570source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +09009571HTTP request, HTTP return code, number of bytes transmitted, conditions
9572in which the session ended, and even exchanged cookies values. For example
9573track a particular user's problems. All messages may be sent to up to two
9574syslog servers. Check the "log" keyword in section 4.2 for more information
9575about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009576
9577
Willy Tarreauc57f0e22009-05-10 13:12:33 +020095788.2. Log formats
9579----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009580
William Lallemand48940402012-01-30 16:47:22 +01009581HAProxy supports 5 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +09009582and will be detailed in the following sections. A few of them may vary
9583slightly with the configuration, due to indicators specific to certain
9584options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009585
9586 - the default format, which is very basic and very rarely used. It only
9587 provides very basic information about the incoming connection at the moment
9588 it is accepted : source IP:port, destination IP:port, and frontend-name.
9589 This mode will eventually disappear so it will not be described to great
9590 extents.
9591
9592 - the TCP format, which is more advanced. This format is enabled when "option
9593 tcplog" is set on the frontend. HAProxy will then usually wait for the
9594 connection to terminate before logging. This format provides much richer
9595 information, such as timers, connection counts, queue size, etc... This
9596 format is recommended for pure TCP proxies.
9597
9598 - the HTTP format, which is the most advanced for HTTP proxying. This format
9599 is enabled when "option httplog" is set on the frontend. It provides the
9600 same information as the TCP format with some HTTP-specific fields such as
9601 the request, the status code, and captures of headers and cookies. This
9602 format is recommended for HTTP proxies.
9603
Emeric Brun3a058f32009-06-30 18:26:00 +02009604 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
9605 fields arranged in the same order as the CLF format. In this mode, all
9606 timers, captures, flags, etc... appear one per field after the end of the
9607 common fields, in the same order they appear in the standard HTTP format.
9608
William Lallemand48940402012-01-30 16:47:22 +01009609 - the custom log format, allows you to make your own log line.
9610
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009611Next sections will go deeper into details for each of these formats. Format
9612specification will be performed on a "field" basis. Unless stated otherwise, a
9613field is a portion of text delimited by any number of spaces. Since syslog
9614servers are susceptible of inserting fields at the beginning of a line, it is
9615always assumed that the first field is the one containing the process name and
9616identifier.
9617
9618Note : Since log lines may be quite long, the log examples in sections below
9619 might be broken into multiple lines. The example log lines will be
9620 prefixed with 3 closing angle brackets ('>>>') and each time a log is
9621 broken into multiple lines, each non-final line will end with a
9622 backslash ('\') and the next line will start indented by two characters.
9623
9624
Willy Tarreauc57f0e22009-05-10 13:12:33 +020096258.2.1. Default log format
9626-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009627
9628This format is used when no specific option is set. The log is emitted as soon
9629as the connection is accepted. One should note that this currently is the only
9630format which logs the request's destination IP and ports.
9631
9632 Example :
9633 listen www
9634 mode http
9635 log global
9636 server srv1 127.0.0.1:8000
9637
9638 >>> Feb 6 12:12:09 localhost \
9639 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
9640 (www/HTTP)
9641
9642 Field Format Extract from the example above
9643 1 process_name '[' pid ']:' haproxy[14385]:
9644 2 'Connect from' Connect from
9645 3 source_ip ':' source_port 10.0.1.2:33312
9646 4 'to' to
9647 5 destination_ip ':' destination_port 10.0.3.31:8012
9648 6 '(' frontend_name '/' mode ')' (www/HTTP)
9649
9650Detailed fields description :
9651 - "source_ip" is the IP address of the client which initiated the connection.
9652 - "source_port" is the TCP port of the client which initiated the connection.
9653 - "destination_ip" is the IP address the client connected to.
9654 - "destination_port" is the TCP port the client connected to.
9655 - "frontend_name" is the name of the frontend (or listener) which received
9656 and processed the connection.
9657 - "mode is the mode the frontend is operating (TCP or HTTP).
9658
Willy Tarreauceb24bc2010-11-09 12:46:41 +01009659In case of a UNIX socket, the source and destination addresses are marked as
9660"unix:" and the ports reflect the internal ID of the socket which accepted the
9661connection (the same ID as reported in the stats).
9662
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009663It is advised not to use this deprecated format for newer installations as it
9664will eventually disappear.
9665
9666
Willy Tarreauc57f0e22009-05-10 13:12:33 +020096678.2.2. TCP log format
9668---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009669
9670The TCP format is used when "option tcplog" is specified in the frontend, and
9671is the recommended format for pure TCP proxies. It provides a lot of precious
9672information for troubleshooting. Since this format includes timers and byte
9673counts, the log is normally emitted at the end of the session. It can be
9674emitted earlier if "option logasap" is specified, which makes sense in most
9675environments with long sessions such as remote terminals. Sessions which match
9676the "monitor" rules are never logged. It is also possible not to emit logs for
9677sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02009678specifying "option dontlognull" in the frontend. Successful connections will
9679not be logged if "option dontlog-normal" is specified in the frontend. A few
9680fields may slightly vary depending on some configuration options, those are
9681marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009682
9683 Example :
9684 frontend fnt
9685 mode tcp
9686 option tcplog
9687 log global
9688 default_backend bck
9689
9690 backend bck
9691 server srv1 127.0.0.1:8000
9692
9693 >>> Feb 6 12:12:56 localhost \
9694 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
9695 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
9696
9697 Field Format Extract from the example above
9698 1 process_name '[' pid ']:' haproxy[14387]:
9699 2 client_ip ':' client_port 10.0.1.2:33313
9700 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
9701 4 frontend_name fnt
9702 5 backend_name '/' server_name bck/srv1
9703 6 Tw '/' Tc '/' Tt* 0/0/5007
9704 7 bytes_read* 212
9705 8 termination_state --
9706 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
9707 10 srv_queue '/' backend_queue 0/0
9708
9709Detailed fields description :
9710 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +01009711 connection to haproxy. If the connection was accepted on a UNIX socket
9712 instead, the IP address would be replaced with the word "unix". Note that
9713 when the connection is accepted on a socket configured with "accept-proxy"
9714 and the PROXY protocol is correctly used, then the logs will reflect the
9715 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009716
9717 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +01009718 If the connection was accepted on a UNIX socket instead, the port would be
9719 replaced with the ID of the accepting socket, which is also reported in the
9720 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009721
9722 - "accept_date" is the exact date when the connection was received by haproxy
9723 (which might be very slightly different from the date observed on the
9724 network if there was some queuing in the system's backlog). This is usually
9725 the same date which may appear in any upstream firewall's log.
9726
9727 - "frontend_name" is the name of the frontend (or listener) which received
9728 and processed the connection.
9729
9730 - "backend_name" is the name of the backend (or listener) which was selected
9731 to manage the connection to the server. This will be the same as the
9732 frontend if no switching rule has been applied, which is common for TCP
9733 applications.
9734
9735 - "server_name" is the name of the last server to which the connection was
9736 sent, which might differ from the first one if there were connection errors
9737 and a redispatch occurred. Note that this server belongs to the backend
9738 which processed the request. If the connection was aborted before reaching
9739 a server, "<NOSRV>" is indicated instead of a server name.
9740
9741 - "Tw" is the total time in milliseconds spent waiting in the various queues.
9742 It can be "-1" if the connection was aborted before reaching the queue.
9743 See "Timers" below for more details.
9744
9745 - "Tc" is the total time in milliseconds spent waiting for the connection to
9746 establish to the final server, including retries. It can be "-1" if the
9747 connection was aborted before a connection could be established. See
9748 "Timers" below for more details.
9749
9750 - "Tt" is the total time in milliseconds elapsed between the accept and the
9751 last close. It covers all possible processings. There is one exception, if
9752 "option logasap" was specified, then the time counting stops at the moment
9753 the log is emitted. In this case, a '+' sign is prepended before the value,
9754 indicating that the final one will be larger. See "Timers" below for more
9755 details.
9756
9757 - "bytes_read" is the total number of bytes transmitted from the server to
9758 the client when the log is emitted. If "option logasap" is specified, the
9759 this value will be prefixed with a '+' sign indicating that the final one
9760 may be larger. Please note that this value is a 64-bit counter, so log
9761 analysis tools must be able to handle it without overflowing.
9762
9763 - "termination_state" is the condition the session was in when the session
9764 ended. This indicates the session state, which side caused the end of
9765 session to happen, and for what reason (timeout, error, ...). The normal
9766 flags should be "--", indicating the session was closed by either end with
9767 no data remaining in buffers. See below "Session state at disconnection"
9768 for more details.
9769
9770 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009771 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009772 limits have been reached. For instance, if actconn is close to 512 when
9773 multiple connection errors occur, chances are high that the system limits
9774 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009775 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009776
9777 - "feconn" is the total number of concurrent connections on the frontend when
9778 the session was logged. It is useful to estimate the amount of resource
9779 required to sustain high loads, and to detect when the frontend's "maxconn"
9780 has been reached. Most often when this value increases by huge jumps, it is
9781 because there is congestion on the backend servers, but sometimes it can be
9782 caused by a denial of service attack.
9783
9784 - "beconn" is the total number of concurrent connections handled by the
9785 backend when the session was logged. It includes the total number of
9786 concurrent connections active on servers as well as the number of
9787 connections pending in queues. It is useful to estimate the amount of
9788 additional servers needed to support high loads for a given application.
9789 Most often when this value increases by huge jumps, it is because there is
9790 congestion on the backend servers, but sometimes it can be caused by a
9791 denial of service attack.
9792
9793 - "srv_conn" is the total number of concurrent connections still active on
9794 the server when the session was logged. It can never exceed the server's
9795 configured "maxconn" parameter. If this value is very often close or equal
9796 to the server's "maxconn", it means that traffic regulation is involved a
9797 lot, meaning that either the server's maxconn value is too low, or that
9798 there aren't enough servers to process the load with an optimal response
9799 time. When only one of the server's "srv_conn" is high, it usually means
9800 that this server has some trouble causing the connections to take longer to
9801 be processed than on other servers.
9802
9803 - "retries" is the number of connection retries experienced by this session
9804 when trying to connect to the server. It must normally be zero, unless a
9805 server is being stopped at the same moment the connection was attempted.
9806 Frequent retries generally indicate either a network problem between
9807 haproxy and the server, or a misconfigured system backlog on the server
9808 preventing new connections from being queued. This field may optionally be
9809 prefixed with a '+' sign, indicating that the session has experienced a
9810 redispatch after the maximal retry count has been reached on the initial
9811 server. In this case, the server name appearing in the log is the one the
9812 connection was redispatched to, and not the first one, though both may
9813 sometimes be the same in case of hashing for instance. So as a general rule
9814 of thumb, when a '+' is present in front of the retry count, this count
9815 should not be attributed to the logged server.
9816
9817 - "srv_queue" is the total number of requests which were processed before
9818 this one in the server queue. It is zero when the request has not gone
9819 through the server queue. It makes it possible to estimate the approximate
9820 server's response time by dividing the time spent in queue by the number of
9821 requests in the queue. It is worth noting that if a session experiences a
9822 redispatch and passes through two server queues, their positions will be
9823 cumulated. A request should not pass through both the server queue and the
9824 backend queue unless a redispatch occurs.
9825
9826 - "backend_queue" is the total number of requests which were processed before
9827 this one in the backend's global queue. It is zero when the request has not
9828 gone through the global queue. It makes it possible to estimate the average
9829 queue length, which easily translates into a number of missing servers when
9830 divided by a server's "maxconn" parameter. It is worth noting that if a
9831 session experiences a redispatch, it may pass twice in the backend's queue,
9832 and then both positions will be cumulated. A request should not pass
9833 through both the server queue and the backend queue unless a redispatch
9834 occurs.
9835
9836
Willy Tarreauc57f0e22009-05-10 13:12:33 +020098378.2.3. HTTP log format
9838----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009839
9840The HTTP format is the most complete and the best suited for HTTP proxies. It
9841is enabled by when "option httplog" is specified in the frontend. It provides
9842the same level of information as the TCP format with additional features which
9843are specific to the HTTP protocol. Just like the TCP format, the log is usually
9844emitted at the end of the session, unless "option logasap" is specified, which
9845generally only makes sense for download sites. A session which matches the
9846"monitor" rules will never logged. It is also possible not to log sessions for
9847which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02009848frontend. Successful connections will not be logged if "option dontlog-normal"
9849is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009850
9851Most fields are shared with the TCP log, some being different. A few fields may
9852slightly vary depending on some configuration options. Those ones are marked
9853with a star ('*') after the field name below.
9854
9855 Example :
9856 frontend http-in
9857 mode http
9858 option httplog
9859 log global
9860 default_backend bck
9861
9862 backend static
9863 server srv1 127.0.0.1:8000
9864
9865 >>> Feb 6 12:14:14 localhost \
9866 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
9867 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 +01009868 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009869
9870 Field Format Extract from the example above
9871 1 process_name '[' pid ']:' haproxy[14389]:
9872 2 client_ip ':' client_port 10.0.1.2:33317
9873 3 '[' accept_date ']' [06/Feb/2009:12:14:14.655]
9874 4 frontend_name http-in
9875 5 backend_name '/' server_name static/srv1
9876 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt* 10/0/30/69/109
9877 7 status_code 200
9878 8 bytes_read* 2750
9879 9 captured_request_cookie -
9880 10 captured_response_cookie -
9881 11 termination_state ----
9882 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
9883 13 srv_queue '/' backend_queue 0/0
9884 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
9885 15 '{' captured_response_headers* '}' {}
9886 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +01009887
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009888
9889Detailed fields description :
9890 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +01009891 connection to haproxy. If the connection was accepted on a UNIX socket
9892 instead, the IP address would be replaced with the word "unix". Note that
9893 when the connection is accepted on a socket configured with "accept-proxy"
9894 and the PROXY protocol is correctly used, then the logs will reflect the
9895 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009896
9897 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +01009898 If the connection was accepted on a UNIX socket instead, the port would be
9899 replaced with the ID of the accepting socket, which is also reported in the
9900 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009901
9902 - "accept_date" is the exact date when the TCP connection was received by
9903 haproxy (which might be very slightly different from the date observed on
9904 the network if there was some queuing in the system's backlog). This is
9905 usually the same date which may appear in any upstream firewall's log. This
9906 does not depend on the fact that the client has sent the request or not.
9907
9908 - "frontend_name" is the name of the frontend (or listener) which received
9909 and processed the connection.
9910
9911 - "backend_name" is the name of the backend (or listener) which was selected
9912 to manage the connection to the server. This will be the same as the
9913 frontend if no switching rule has been applied.
9914
9915 - "server_name" is the name of the last server to which the connection was
9916 sent, which might differ from the first one if there were connection errors
9917 and a redispatch occurred. Note that this server belongs to the backend
9918 which processed the request. If the request was aborted before reaching a
9919 server, "<NOSRV>" is indicated instead of a server name. If the request was
9920 intercepted by the stats subsystem, "<STATS>" is indicated instead.
9921
9922 - "Tq" is the total time in milliseconds spent waiting for the client to send
9923 a full HTTP request, not counting data. It can be "-1" if the connection
9924 was aborted before a complete request could be received. It should always
9925 be very small because a request generally fits in one single packet. Large
9926 times here generally indicate network trouble between the client and
9927 haproxy. See "Timers" below for more details.
9928
9929 - "Tw" is the total time in milliseconds spent waiting in the various queues.
9930 It can be "-1" if the connection was aborted before reaching the queue.
9931 See "Timers" below for more details.
9932
9933 - "Tc" is the total time in milliseconds spent waiting for the connection to
9934 establish to the final server, including retries. It can be "-1" if the
9935 request was aborted before a connection could be established. See "Timers"
9936 below for more details.
9937
9938 - "Tr" is the total time in milliseconds spent waiting for the server to send
9939 a full HTTP response, not counting data. It can be "-1" if the request was
9940 aborted before a complete response could be received. It generally matches
9941 the server's processing time for the request, though it may be altered by
9942 the amount of data sent by the client to the server. Large times here on
9943 "GET" requests generally indicate an overloaded server. See "Timers" below
9944 for more details.
9945
9946 - "Tt" is the total time in milliseconds elapsed between the accept and the
9947 last close. It covers all possible processings. There is one exception, if
9948 "option logasap" was specified, then the time counting stops at the moment
9949 the log is emitted. In this case, a '+' sign is prepended before the value,
9950 indicating that the final one will be larger. See "Timers" below for more
9951 details.
9952
9953 - "status_code" is the HTTP status code returned to the client. This status
9954 is generally set by the server, but it might also be set by haproxy when
9955 the server cannot be reached or when its response is blocked by haproxy.
9956
9957 - "bytes_read" is the total number of bytes transmitted to the client when
9958 the log is emitted. This does include HTTP headers. If "option logasap" is
9959 specified, the this value will be prefixed with a '+' sign indicating that
9960 the final one may be larger. Please note that this value is a 64-bit
9961 counter, so log analysis tools must be able to handle it without
9962 overflowing.
9963
9964 - "captured_request_cookie" is an optional "name=value" entry indicating that
9965 the client had this cookie in the request. The cookie name and its maximum
9966 length are defined by the "capture cookie" statement in the frontend
9967 configuration. The field is a single dash ('-') when the option is not
9968 set. Only one cookie may be captured, it is generally used to track session
9969 ID exchanges between a client and a server to detect session crossing
9970 between clients due to application bugs. For more details, please consult
9971 the section "Capturing HTTP headers and cookies" below.
9972
9973 - "captured_response_cookie" is an optional "name=value" entry indicating
9974 that the server has returned a cookie with its response. The cookie name
9975 and its maximum length are defined by the "capture cookie" statement in the
9976 frontend configuration. The field is a single dash ('-') when the option is
9977 not set. Only one cookie may be captured, it is generally used to track
9978 session ID exchanges between a client and a server to detect session
9979 crossing between clients due to application bugs. For more details, please
9980 consult the section "Capturing HTTP headers and cookies" below.
9981
9982 - "termination_state" is the condition the session was in when the session
9983 ended. This indicates the session state, which side caused the end of
9984 session to happen, for what reason (timeout, error, ...), just like in TCP
9985 logs, and information about persistence operations on cookies in the last
9986 two characters. The normal flags should begin with "--", indicating the
9987 session was closed by either end with no data remaining in buffers. See
9988 below "Session state at disconnection" for more details.
9989
9990 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009991 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009992 limits have been reached. For instance, if actconn is close to 512 or 1024
9993 when multiple connection errors occur, chances are high that the system
9994 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009995 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009996 system.
9997
9998 - "feconn" is the total number of concurrent connections on the frontend when
9999 the session was logged. It is useful to estimate the amount of resource
10000 required to sustain high loads, and to detect when the frontend's "maxconn"
10001 has been reached. Most often when this value increases by huge jumps, it is
10002 because there is congestion on the backend servers, but sometimes it can be
10003 caused by a denial of service attack.
10004
10005 - "beconn" is the total number of concurrent connections handled by the
10006 backend when the session was logged. It includes the total number of
10007 concurrent connections active on servers as well as the number of
10008 connections pending in queues. It is useful to estimate the amount of
10009 additional servers needed to support high loads for a given application.
10010 Most often when this value increases by huge jumps, it is because there is
10011 congestion on the backend servers, but sometimes it can be caused by a
10012 denial of service attack.
10013
10014 - "srv_conn" is the total number of concurrent connections still active on
10015 the server when the session was logged. It can never exceed the server's
10016 configured "maxconn" parameter. If this value is very often close or equal
10017 to the server's "maxconn", it means that traffic regulation is involved a
10018 lot, meaning that either the server's maxconn value is too low, or that
10019 there aren't enough servers to process the load with an optimal response
10020 time. When only one of the server's "srv_conn" is high, it usually means
10021 that this server has some trouble causing the requests to take longer to be
10022 processed than on other servers.
10023
10024 - "retries" is the number of connection retries experienced by this session
10025 when trying to connect to the server. It must normally be zero, unless a
10026 server is being stopped at the same moment the connection was attempted.
10027 Frequent retries generally indicate either a network problem between
10028 haproxy and the server, or a misconfigured system backlog on the server
10029 preventing new connections from being queued. This field may optionally be
10030 prefixed with a '+' sign, indicating that the session has experienced a
10031 redispatch after the maximal retry count has been reached on the initial
10032 server. In this case, the server name appearing in the log is the one the
10033 connection was redispatched to, and not the first one, though both may
10034 sometimes be the same in case of hashing for instance. So as a general rule
10035 of thumb, when a '+' is present in front of the retry count, this count
10036 should not be attributed to the logged server.
10037
10038 - "srv_queue" is the total number of requests which were processed before
10039 this one in the server queue. It is zero when the request has not gone
10040 through the server queue. It makes it possible to estimate the approximate
10041 server's response time by dividing the time spent in queue by the number of
10042 requests in the queue. It is worth noting that if a session experiences a
10043 redispatch and passes through two server queues, their positions will be
10044 cumulated. A request should not pass through both the server queue and the
10045 backend queue unless a redispatch occurs.
10046
10047 - "backend_queue" is the total number of requests which were processed before
10048 this one in the backend's global queue. It is zero when the request has not
10049 gone through the global queue. It makes it possible to estimate the average
10050 queue length, which easily translates into a number of missing servers when
10051 divided by a server's "maxconn" parameter. It is worth noting that if a
10052 session experiences a redispatch, it may pass twice in the backend's queue,
10053 and then both positions will be cumulated. A request should not pass
10054 through both the server queue and the backend queue unless a redispatch
10055 occurs.
10056
10057 - "captured_request_headers" is a list of headers captured in the request due
10058 to the presence of the "capture request header" statement in the frontend.
10059 Multiple headers can be captured, they will be delimited by a vertical bar
10060 ('|'). When no capture is enabled, the braces do not appear, causing a
10061 shift of remaining fields. It is important to note that this field may
10062 contain spaces, and that using it requires a smarter log parser than when
10063 it's not used. Please consult the section "Capturing HTTP headers and
10064 cookies" below for more details.
10065
10066 - "captured_response_headers" is a list of headers captured in the response
10067 due to the presence of the "capture response header" statement in the
10068 frontend. Multiple headers can be captured, they will be delimited by a
10069 vertical bar ('|'). When no capture is enabled, the braces do not appear,
10070 causing a shift of remaining fields. It is important to note that this
10071 field may contain spaces, and that using it requires a smarter log parser
10072 than when it's not used. Please consult the section "Capturing HTTP headers
10073 and cookies" below for more details.
10074
10075 - "http_request" is the complete HTTP request line, including the method,
10076 request and HTTP version string. Non-printable characters are encoded (see
10077 below the section "Non-printable characters"). This is always the last
10078 field, and it is always delimited by quotes and is the only one which can
10079 contain quotes. If new fields are added to the log format, they will be
10080 added before this field. This field might be truncated if the request is
10081 huge and does not fit in the standard syslog buffer (1024 characters). This
10082 is the reason why this field must always remain the last one.
10083
10084
Cyril Bontédc4d9032012-04-08 21:57:39 +0200100858.2.4. Custom log format
10086------------------------
William Lallemand48940402012-01-30 16:47:22 +010010087
William Lallemandbddd4fd2012-02-27 11:23:10 +010010088The directive log-format allows you to custom the logs in http mode and tcp
10089mode. It takes a string as argument.
William Lallemand48940402012-01-30 16:47:22 +010010090
10091HAproxy understands some log format variables. % precedes log format variables.
10092Variables can take arguments using braces ('{}'), and multiple arguments are
10093separated by commas within the braces. Flags may be added or removed by
10094prefixing them with a '+' or '-' sign.
10095
10096Special variable "%o" may be used to propagate its flags to all other
10097variables on the same format string. This is particularly handy with quoted
10098string formats ("Q").
10099
10100Note: spaces must be escaped. A space character is considered as a separator.
10101HAproxy will automatically merge consecutive separators.
10102
10103Flags are :
10104 * Q: quote a string
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010105 * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid)
William Lallemand48940402012-01-30 16:47:22 +010010106
10107 Example:
10108
10109 log-format %T\ %t\ Some\ Text
10110 log-format %{+Q}o\ %t\ %s\ %{-Q}r
10111
10112At the moment, the default HTTP format is defined this way :
10113
Willy Tarreau773d65f2012-10-12 14:56:11 +020010114 log-format %Ci:%Cp\ [%t]\ %ft\ %b/%s\ %Tq/%Tw/%Tc/%Tr/%Tt\ %st\ %B\ %cc\ \
Willy Tarreau6580c062012-03-12 15:09:42 +010010115 %cs\ %tsc\ %ac/%fc/%bc/%sc/%rc\ %sq/%bq\ %hr\ %hs\ %{+Q}r
William Lallemand48940402012-01-30 16:47:22 +010010116
William Lallemandbddd4fd2012-02-27 11:23:10 +010010117the default CLF format is defined this way :
William Lallemand48940402012-01-30 16:47:22 +010010118
10119 log-format %{+Q}o\ %{-Q}Ci\ -\ -\ [%T]\ %r\ %st\ %B\ \"\"\ \"\"\ %Cp\ \
Willy Tarreau773d65f2012-10-12 14:56:11 +020010120 %ms\ %ft\ %b\ %s\ \%Tq\ %Tw\ %Tc\ %Tr\ %Tt\ %tsc\ %ac\ %fc\ \
William Lallemand48940402012-01-30 16:47:22 +010010121 %bc\ %sc\ %rc\ %sq\ %bq\ %cc\ %cs\ \%hrl\ %hsl
10122
William Lallemandbddd4fd2012-02-27 11:23:10 +010010123and the default TCP format is defined this way :
10124
Willy Tarreau773d65f2012-10-12 14:56:11 +020010125 log-format %Ci:%Cp\ [%t]\ %ft\ %b/%s\ %Tw/%Tc/%Tt\ %B\ %ts\ \
William Lallemandbddd4fd2012-02-27 11:23:10 +010010126 %ac/%fc/%bc/%sc/%rc\ %sq/%bq
10127
William Lallemand48940402012-01-30 16:47:22 +010010128Please refer to the table below for currently defined variables :
10129
William Lallemandbddd4fd2012-02-27 11:23:10 +010010130 +---+------+-----------------------------------------------+-------------+
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010131 | R | var | field name (8.2.2 and 8.2.3 for description) | type |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010132 +---+------+-----------------------------------------------+-------------+
10133 | | %o | special variable, apply flags on all next var | |
10134 +---+------+-----------------------------------------------+-------------+
10135 | | %B | bytes_read | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020010136 | | %Ci | client_ip | IP |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010137 | | %Cp | client_port | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020010138 | | %Bi | backend_source_ip | IP |
William Lallemandb7ff6a32012-03-02 14:35:21 +010010139 | | %Bp | backend_source_port | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020010140 | | %Fi | frontend_ip | IP |
10141 | | %Fp | frontend_port | numeric |
10142 | | %H | hostname | string |
William Lallemanda73203e2012-03-12 12:48:57 +010010143 | | %ID | unique-id | string |
William Lallemand5f232402012-04-05 18:02:55 +020010144 | | %Si | server_IP | IP |
10145 | | %Sp | server_port | numeric |
10146 | | %T | gmt_date_time | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010147 | | %Tc | Tc | numeric |
Yuxans Yao4e25b012012-10-19 10:36:09 +080010148 | | %Tl | local_date_time | date |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010149 | H | %Tq | Tq | numeric |
10150 | H | %Tr | Tr | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020010151 | | %Ts | timestamp | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010152 | | %Tt | Tt | numeric |
10153 | | %Tw | Tw | numeric |
10154 | | %ac | actconn | numeric |
10155 | | %b | backend_name | string |
10156 | | %bc | beconn | numeric |
10157 | | %bq | backend_queue | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010158 | H | %cc | captured_request_cookie | string |
10159 | H | %rt | http_request_counter | numeric |
10160 | H | %cs | captured_response_cookie | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010161 | | %f | frontend_name | string |
Willy Tarreau773d65f2012-10-12 14:56:11 +020010162 | | %ft | frontend_name_transport ('~' suffix for SSL) | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010163 | | %fc | feconn | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010164 | H | %hr | captured_request_headers default style | string |
10165 | H | %hrl | captured_request_headers CLF style | string list |
10166 | H | %hs | captured_response_headers default style | string |
10167 | H | %hsl | captured_response_headers CLF style | string list |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010168 | | %ms | accept date milliseconds | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020010169 | | %pid | PID | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010170 | H | %r | http_request | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010171 | | %rc | retries | numeric |
10172 | | %s | server_name | string |
10173 | | %sc | srv_conn | numeric |
10174 | | %sq | srv_queue | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010175 | S | %sslc| ssl_ciphers (ex: AES-SHA) | string |
10176 | S | %sslv| ssl_version (ex: TLSv1) | string |
10177 | H | %st | status_code | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020010178 | | %t | date_time | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010179 | | %ts | termination_state | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010180 | H | %tsc | termination_state with cookie status | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010181 +---+------+-----------------------------------------------+-------------+
William Lallemand48940402012-01-30 16:47:22 +010010182
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010183 R = Restrictions : H = mode http only ; S = SSL only
William Lallemand48940402012-01-30 16:47:22 +010010184
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200101858.3. Advanced logging options
10186-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010187
10188Some advanced logging options are often looked for but are not easy to find out
10189just by looking at the various options. Here is an entry point for the few
10190options which can enable better logging. Please refer to the keywords reference
10191for more information about their usage.
10192
10193
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200101948.3.1. Disabling logging of external tests
10195------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010196
10197It is quite common to have some monitoring tools perform health checks on
10198haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
10199commercial load-balancer, and sometimes it will simply be a more complete
10200monitoring system such as Nagios. When the tests are very frequent, users often
10201ask how to disable logging for those checks. There are three possibilities :
10202
10203 - if connections come from everywhere and are just TCP probes, it is often
10204 desired to simply disable logging of connections without data exchange, by
10205 setting "option dontlognull" in the frontend. It also disables logging of
10206 port scans, which may or may not be desired.
10207
10208 - if the connection come from a known source network, use "monitor-net" to
10209 declare this network as monitoring only. Any host in this network will then
10210 only be able to perform health checks, and their requests will not be
10211 logged. This is generally appropriate to designate a list of equipments
10212 such as other load-balancers.
10213
10214 - if the tests are performed on a known URI, use "monitor-uri" to declare
10215 this URI as dedicated to monitoring. Any host sending this request will
10216 only get the result of a health-check, and the request will not be logged.
10217
10218
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200102198.3.2. Logging before waiting for the session to terminate
10220----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010221
10222The problem with logging at end of connection is that you have no clue about
10223what is happening during very long sessions, such as remote terminal sessions
10224or large file downloads. This problem can be worked around by specifying
10225"option logasap" in the frontend. Haproxy will then log as soon as possible,
10226just before data transfer begins. This means that in case of TCP, it will still
10227log the connection status to the server, and in case of HTTP, it will log just
10228after processing the server headers. In this case, the number of bytes reported
10229is the number of header bytes sent to the client. In order to avoid confusion
10230with normal logs, the total time field and the number of bytes are prefixed
10231with a '+' sign which means that real numbers are certainly larger.
10232
10233
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200102348.3.3. Raising log level upon errors
10235------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020010236
10237Sometimes it is more convenient to separate normal traffic from errors logs,
10238for instance in order to ease error monitoring from log files. When the option
10239"log-separate-errors" is used, connections which experience errors, timeouts,
10240retries, redispatches or HTTP status codes 5xx will see their syslog level
10241raised from "info" to "err". This will help a syslog daemon store the log in
10242a separate file. It is very important to keep the errors in the normal traffic
10243file too, so that log ordering is not altered. You should also be careful if
10244you already have configured your syslog daemon to store all logs higher than
10245"notice" in an "admin" file, because the "err" level is higher than "notice".
10246
10247
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200102488.3.4. Disabling logging of successful connections
10249--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020010250
10251Although this may sound strange at first, some large sites have to deal with
10252multiple thousands of logs per second and are experiencing difficulties keeping
10253them intact for a long time or detecting errors within them. If the option
10254"dontlog-normal" is set on the frontend, all normal connections will not be
10255logged. In this regard, a normal connection is defined as one without any
10256error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
10257and a response with a status 5xx is not considered normal and will be logged
10258too. Of course, doing is is really discouraged as it will remove most of the
10259useful information from the logs. Do this only if you have no other
10260alternative.
10261
10262
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200102638.4. Timing events
10264------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010265
10266Timers provide a great help in troubleshooting network problems. All values are
10267reported in milliseconds (ms). These timers should be used in conjunction with
10268the session termination flags. In TCP mode with "option tcplog" set on the
10269frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
10270mode, 5 control points are reported under the form "Tq/Tw/Tc/Tr/Tt" :
10271
10272 - Tq: total time to get the client request (HTTP mode only). It's the time
10273 elapsed between the moment the client connection was accepted and the
10274 moment the proxy received the last HTTP header. The value "-1" indicates
10275 that the end of headers (empty line) has never been seen. This happens when
10276 the client closes prematurely or times out.
10277
10278 - Tw: total time spent in the queues waiting for a connection slot. It
10279 accounts for backend queue as well as the server queues, and depends on the
10280 queue size, and the time needed for the server to complete previous
10281 requests. The value "-1" means that the request was killed before reaching
10282 the queue, which is generally what happens with invalid or denied requests.
10283
10284 - Tc: total time to establish the TCP connection to the server. It's the time
10285 elapsed between the moment the proxy sent the connection request, and the
10286 moment it was acknowledged by the server, or between the TCP SYN packet and
10287 the matching SYN/ACK packet in return. The value "-1" means that the
10288 connection never established.
10289
10290 - Tr: server response time (HTTP mode only). It's the time elapsed between
10291 the moment the TCP connection was established to the server and the moment
10292 the server sent its complete response headers. It purely shows its request
10293 processing time, without the network overhead due to the data transmission.
10294 It is worth noting that when the client has data to send to the server, for
10295 instance during a POST request, the time already runs, and this can distort
10296 apparent response time. For this reason, it's generally wise not to trust
10297 too much this field for POST requests initiated from clients behind an
10298 untrusted network. A value of "-1" here means that the last the response
10299 header (empty line) was never seen, most likely because the server timeout
10300 stroke before the server managed to process the request.
10301
10302 - Tt: total session duration time, between the moment the proxy accepted it
10303 and the moment both ends were closed. The exception is when the "logasap"
10304 option is specified. In this case, it only equals (Tq+Tw+Tc+Tr), and is
10305 prefixed with a '+' sign. From this field, we can deduce "Td", the data
10306 transmission time, by substracting other timers when valid :
10307
10308 Td = Tt - (Tq + Tw + Tc + Tr)
10309
10310 Timers with "-1" values have to be excluded from this equation. In TCP
10311 mode, "Tq" and "Tr" have to be excluded too. Note that "Tt" can never be
10312 negative.
10313
10314These timers provide precious indications on trouble causes. Since the TCP
10315protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
10316that timers close to multiples of 3s are nearly always related to lost packets
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010317due to network problems (wires, negotiation, congestion). Moreover, if "Tt" is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010318close to a timeout value specified in the configuration, it often means that a
10319session has been aborted on timeout.
10320
10321Most common cases :
10322
10323 - If "Tq" is close to 3000, a packet has probably been lost between the
10324 client and the proxy. This is very rare on local networks but might happen
10325 when clients are on far remote networks and send large requests. It may
10326 happen that values larger than usual appear here without any network cause.
10327 Sometimes, during an attack or just after a resource starvation has ended,
10328 haproxy may accept thousands of connections in a few milliseconds. The time
10329 spent accepting these connections will inevitably slightly delay processing
10330 of other connections, and it can happen that request times in the order of
10331 a few tens of milliseconds are measured after a few thousands of new
Patrick Mezard105faca2010-06-12 17:02:46 +020010332 connections have been accepted at once. Setting "option http-server-close"
10333 may display larger request times since "Tq" also measures the time spent
10334 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010335
10336 - If "Tc" is close to 3000, a packet has probably been lost between the
10337 server and the proxy during the server connection phase. This value should
10338 always be very low, such as 1 ms on local networks and less than a few tens
10339 of ms on remote networks.
10340
Willy Tarreau55165fe2009-05-10 12:02:55 +020010341 - If "Tr" is nearly always lower than 3000 except some rare values which seem
10342 to be the average majored by 3000, there are probably some packets lost
10343 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010344
10345 - If "Tt" is large even for small byte counts, it generally is because
10346 neither the client nor the server decides to close the connection, for
10347 instance because both have agreed on a keep-alive connection mode. In order
10348 to solve this issue, it will be needed to specify "option httpclose" on
10349 either the frontend or the backend. If the problem persists, it means that
10350 the server ignores the "close" connection mode and expects the client to
10351 close. Then it will be required to use "option forceclose". Having the
10352 smallest possible 'Tt' is important when connection regulation is used with
10353 the "maxconn" option on the servers, since no new connection will be sent
10354 to the server until another one is released.
10355
10356Other noticeable HTTP log cases ('xx' means any value to be ignored) :
10357
10358 Tq/Tw/Tc/Tr/+Tt The "option logasap" is present on the frontend and the log
10359 was emitted before the data phase. All the timers are valid
10360 except "Tt" which is shorter than reality.
10361
10362 -1/xx/xx/xx/Tt The client was not able to send a complete request in time
10363 or it aborted too early. Check the session termination flags
10364 then "timeout http-request" and "timeout client" settings.
10365
10366 Tq/-1/xx/xx/Tt It was not possible to process the request, maybe because
10367 servers were out of order, because the request was invalid
10368 or forbidden by ACL rules. Check the session termination
10369 flags.
10370
10371 Tq/Tw/-1/xx/Tt The connection could not establish on the server. Either it
10372 actively refused it or it timed out after Tt-(Tq+Tw) ms.
10373 Check the session termination flags, then check the
10374 "timeout connect" setting. Note that the tarpit action might
10375 return similar-looking patterns, with "Tw" equal to the time
10376 the client connection was maintained open.
10377
10378 Tq/Tw/Tc/-1/Tt The server has accepted the connection but did not return
10379 a complete response in time, or it closed its connexion
10380 unexpectedly after Tt-(Tq+Tw+Tc) ms. Check the session
10381 termination flags, then check the "timeout server" setting.
10382
10383
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200103848.5. Session state at disconnection
10385-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010386
10387TCP and HTTP logs provide a session termination indicator in the
10388"termination_state" field, just before the number of active connections. It is
103892-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
10390each of which has a special meaning :
10391
10392 - On the first character, a code reporting the first event which caused the
10393 session to terminate :
10394
10395 C : the TCP session was unexpectedly aborted by the client.
10396
10397 S : the TCP session was unexpectedly aborted by the server, or the
10398 server explicitly refused it.
10399
10400 P : the session was prematurely aborted by the proxy, because of a
10401 connection limit enforcement, because a DENY filter was matched,
10402 because of a security check which detected and blocked a dangerous
10403 error in server response which might have caused information leak
10404 (eg: cacheable cookie), or because the response was processed by
10405 the proxy (redirect, stats, etc...).
10406
10407 R : a resource on the proxy has been exhausted (memory, sockets, source
10408 ports, ...). Usually, this appears during the connection phase, and
10409 system logs should contain a copy of the precise error. If this
10410 happens, it must be considered as a very serious anomaly which
10411 should be fixed as soon as possible by any means.
10412
10413 I : an internal error was identified by the proxy during a self-check.
10414 This should NEVER happen, and you are encouraged to report any log
10415 containing this, because this would almost certainly be a bug. It
10416 would be wise to preventively restart the process after such an
10417 event too, in case it would be caused by memory corruption.
10418
Simon Horman752dc4a2011-06-21 14:34:59 +090010419 D : the session was killed by haproxy because the server was detected
10420 as down and was configured to kill all connections when going down.
10421
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070010422 U : the session was killed by haproxy on this backup server because an
10423 active server was detected as up and was configured to kill all
10424 backup connections when going up.
10425
Willy Tarreaua2a64e92011-09-07 23:01:56 +020010426 K : the session was actively killed by an admin operating on haproxy.
10427
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010428 c : the client-side timeout expired while waiting for the client to
10429 send or receive data.
10430
10431 s : the server-side timeout expired while waiting for the server to
10432 send or receive data.
10433
10434 - : normal session completion, both the client and the server closed
10435 with nothing left in the buffers.
10436
10437 - on the second character, the TCP or HTTP session state when it was closed :
10438
Willy Tarreauf7b30a92010-12-06 22:59:17 +010010439 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010440 (HTTP mode only). Nothing was sent to any server.
10441
10442 Q : the proxy was waiting in the QUEUE for a connection slot. This can
10443 only happen when servers have a 'maxconn' parameter set. It can
10444 also happen in the global queue after a redispatch consecutive to
10445 a failed attempt to connect to a dying server. If no redispatch is
10446 reported, then no connection attempt was made to any server.
10447
10448 C : the proxy was waiting for the CONNECTION to establish on the
10449 server. The server might at most have noticed a connection attempt.
10450
10451 H : the proxy was waiting for complete, valid response HEADERS from the
10452 server (HTTP only).
10453
10454 D : the session was in the DATA phase.
10455
10456 L : the proxy was still transmitting LAST data to the client while the
10457 server had already finished. This one is very rare as it can only
10458 happen when the client dies while receiving the last packets.
10459
10460 T : the request was tarpitted. It has been held open with the client
10461 during the whole "timeout tarpit" duration or until the client
10462 closed, both of which will be reported in the "Tw" timer.
10463
10464 - : normal session completion after end of data transfer.
10465
10466 - the third character tells whether the persistence cookie was provided by
10467 the client (only in HTTP mode) :
10468
10469 N : the client provided NO cookie. This is usually the case for new
10470 visitors, so counting the number of occurrences of this flag in the
10471 logs generally indicate a valid trend for the site frequentation.
10472
10473 I : the client provided an INVALID cookie matching no known server.
10474 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +020010475 cookies between HTTP/HTTPS sites, persistence conditionally
10476 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010477
10478 D : the client provided a cookie designating a server which was DOWN,
10479 so either "option persist" was used and the client was sent to
10480 this server, or it was not set and the client was redispatched to
10481 another server.
10482
Willy Tarreau996a92c2010-10-13 19:30:47 +020010483 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010484 server.
10485
Willy Tarreau996a92c2010-10-13 19:30:47 +020010486 E : the client provided a valid cookie, but with a last date which was
10487 older than what is allowed by the "maxidle" cookie parameter, so
10488 the cookie is consider EXPIRED and is ignored. The request will be
10489 redispatched just as if there was no cookie.
10490
10491 O : the client provided a valid cookie, but with a first date which was
10492 older than what is allowed by the "maxlife" cookie parameter, so
10493 the cookie is consider too OLD and is ignored. The request will be
10494 redispatched just as if there was no cookie.
10495
Willy Tarreauc89ccb62012-04-05 21:18:22 +020010496 U : a cookie was present but was not used to select the server because
10497 some other server selection mechanism was used instead (typically a
10498 "use-server" rule).
10499
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010500 - : does not apply (no cookie set in configuration).
10501
10502 - the last character reports what operations were performed on the persistence
10503 cookie returned by the server (only in HTTP mode) :
10504
10505 N : NO cookie was provided by the server, and none was inserted either.
10506
10507 I : no cookie was provided by the server, and the proxy INSERTED one.
10508 Note that in "cookie insert" mode, if the server provides a cookie,
10509 it will still be overwritten and reported as "I" here.
10510
Willy Tarreau996a92c2010-10-13 19:30:47 +020010511 U : the proxy UPDATED the last date in the cookie that was presented by
10512 the client. This can only happen in insert mode with "maxidle". It
10513 happens everytime there is activity at a different date than the
10514 date indicated in the cookie. If any other change happens, such as
10515 a redispatch, then the cookie will be marked as inserted instead.
10516
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010517 P : a cookie was PROVIDED by the server and transmitted as-is.
10518
10519 R : the cookie provided by the server was REWRITTEN by the proxy, which
10520 happens in "cookie rewrite" or "cookie prefix" modes.
10521
10522 D : the cookie provided by the server was DELETED by the proxy.
10523
10524 - : does not apply (no cookie set in configuration).
10525
Willy Tarreau996a92c2010-10-13 19:30:47 +020010526The combination of the two first flags gives a lot of information about what
10527was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010528helpful to detect server saturation, network troubles, local system resource
10529starvation, attacks, etc...
10530
10531The most common termination flags combinations are indicated below. They are
10532alphabetically sorted, with the lowercase set just after the upper case for
10533easier finding and understanding.
10534
10535 Flags Reason
10536
10537 -- Normal termination.
10538
10539 CC The client aborted before the connection could be established to the
10540 server. This can happen when haproxy tries to connect to a recently
10541 dead (or unchecked) server, and the client aborts while haproxy is
10542 waiting for the server to respond or for "timeout connect" to expire.
10543
10544 CD The client unexpectedly aborted during data transfer. This can be
10545 caused by a browser crash, by an intermediate equipment between the
10546 client and haproxy which decided to actively break the connection,
10547 by network routing issues between the client and haproxy, or by a
10548 keep-alive session between the server and the client terminated first
10549 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +010010550
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010551 cD The client did not send nor acknowledge any data for as long as the
10552 "timeout client" delay. This is often caused by network failures on
Cyril Bontédc4d9032012-04-08 21:57:39 +020010553 the client side, or the client simply leaving the net uncleanly.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010554
10555 CH The client aborted while waiting for the server to start responding.
10556 It might be the server taking too long to respond or the client
10557 clicking the 'Stop' button too fast.
10558
10559 cH The "timeout client" stroke while waiting for client data during a
10560 POST request. This is sometimes caused by too large TCP MSS values
10561 for PPPoE networks which cannot transport full-sized packets. It can
10562 also happen when client timeout is smaller than server timeout and
10563 the server takes too long to respond.
10564
10565 CQ The client aborted while its session was queued, waiting for a server
10566 with enough empty slots to accept it. It might be that either all the
10567 servers were saturated or that the assigned server was taking too
10568 long a time to respond.
10569
10570 CR The client aborted before sending a full HTTP request. Most likely
10571 the request was typed by hand using a telnet client, and aborted
10572 too early. The HTTP status code is likely a 400 here. Sometimes this
10573 might also be caused by an IDS killing the connection between haproxy
10574 and the client.
10575
10576 cR The "timeout http-request" stroke before the client sent a full HTTP
10577 request. This is sometimes caused by too large TCP MSS values on the
10578 client side for PPPoE networks which cannot transport full-sized
10579 packets, or by clients sending requests by hand and not typing fast
10580 enough, or forgetting to enter the empty line at the end of the
10581 request. The HTTP status code is likely a 408 here.
10582
10583 CT The client aborted while its session was tarpitted. It is important to
10584 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +020010585 wrong tarpit rules have been written. If a lot of them happen, it
10586 might make sense to lower the "timeout tarpit" value to something
10587 closer to the average reported "Tw" timer, in order not to consume
10588 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010589
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010590 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010591 the TCP connection (the proxy received a TCP RST or an ICMP message
10592 in return). Under some circumstances, it can also be the network
10593 stack telling the proxy that the server is unreachable (eg: no route,
10594 or no ARP response on local network). When this happens in HTTP mode,
10595 the status code is likely a 502 or 503 here.
10596
10597 sC The "timeout connect" stroke before a connection to the server could
10598 complete. When this happens in HTTP mode, the status code is likely a
10599 503 or 504 here.
10600
10601 SD The connection to the server died with an error during the data
10602 transfer. This usually means that haproxy has received an RST from
10603 the server or an ICMP message from an intermediate equipment while
10604 exchanging data with the server. This can be caused by a server crash
10605 or by a network issue on an intermediate equipment.
10606
10607 sD The server did not send nor acknowledge any data for as long as the
10608 "timeout server" setting during the data phase. This is often caused
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010609 by too short timeouts on L4 equipments before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010610 load-balancers, ...), as well as keep-alive sessions maintained
10611 between the client and the server expiring first on haproxy.
10612
10613 SH The server aborted before sending its full HTTP response headers, or
10614 it crashed while processing the request. Since a server aborting at
10615 this moment is very rare, it would be wise to inspect its logs to
10616 control whether it crashed and why. The logged request may indicate a
10617 small set of faulty requests, demonstrating bugs in the application.
10618 Sometimes this might also be caused by an IDS killing the connection
10619 between haproxy and the server.
10620
10621 sH The "timeout server" stroke before the server could return its
10622 response headers. This is the most common anomaly, indicating too
10623 long transactions, probably caused by server or database saturation.
10624 The immediate workaround consists in increasing the "timeout server"
10625 setting, but it is important to keep in mind that the user experience
10626 will suffer from these long response times. The only long term
10627 solution is to fix the application.
10628
10629 sQ The session spent too much time in queue and has been expired. See
10630 the "timeout queue" and "timeout connect" settings to find out how to
10631 fix this if it happens too often. If it often happens massively in
10632 short periods, it may indicate general problems on the affected
10633 servers due to I/O or database congestion, or saturation caused by
10634 external attacks.
10635
10636 PC The proxy refused to establish a connection to the server because the
10637 process' socket limit has been reached while attempting to connect.
Cyril Bontédc4d9032012-04-08 21:57:39 +020010638 The global "maxconn" parameter may be increased in the configuration
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010639 so that it does not happen anymore. This status is very rare and
10640 might happen when the global "ulimit-n" parameter is forced by hand.
10641
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010010642 PD The proxy blocked an incorrectly formatted chunked encoded message in
10643 a request or a response, after the server has emitted its headers. In
10644 most cases, this will indicate an invalid message from the server to
10645 the client.
10646
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010647 PH The proxy blocked the server's response, because it was invalid,
10648 incomplete, dangerous (cache control), or matched a security filter.
10649 In any case, an HTTP 502 error is sent to the client. One possible
10650 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010010651 containing unauthorized characters. It is also possible but quite
10652 rare, that the proxy blocked a chunked-encoding request from the
10653 client due to an invalid syntax, before the server responded. In this
10654 case, an HTTP 400 error is sent to the client and reported in the
10655 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010656
10657 PR The proxy blocked the client's HTTP request, either because of an
10658 invalid HTTP syntax, in which case it returned an HTTP 400 error to
10659 the client, or because a deny filter matched, in which case it
10660 returned an HTTP 403 error.
10661
10662 PT The proxy blocked the client's request and has tarpitted its
10663 connection before returning it a 500 server error. Nothing was sent
10664 to the server. The connection was maintained open for as long as
10665 reported by the "Tw" timer field.
10666
10667 RC A local resource has been exhausted (memory, sockets, source ports)
10668 preventing the connection to the server from establishing. The error
10669 logs will tell precisely what was missing. This is very rare and can
10670 only be solved by proper system tuning.
10671
Willy Tarreau996a92c2010-10-13 19:30:47 +020010672The combination of the two last flags gives a lot of information about how
10673persistence was handled by the client, the server and by haproxy. This is very
10674important to troubleshoot disconnections, when users complain they have to
10675re-authenticate. The commonly encountered flags are :
10676
10677 -- Persistence cookie is not enabled.
10678
10679 NN No cookie was provided by the client, none was inserted in the
10680 response. For instance, this can be in insert mode with "postonly"
10681 set on a GET request.
10682
10683 II A cookie designating an invalid server was provided by the client,
10684 a valid one was inserted in the response. This typically happens when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010685 a "server" entry is removed from the configuration, since its cookie
Willy Tarreau996a92c2010-10-13 19:30:47 +020010686 value can be presented by a client when no other server knows it.
10687
10688 NI No cookie was provided by the client, one was inserted in the
10689 response. This typically happens for first requests from every user
10690 in "insert" mode, which makes it an easy way to count real users.
10691
10692 VN A cookie was provided by the client, none was inserted in the
10693 response. This happens for most responses for which the client has
10694 already got a cookie.
10695
10696 VU A cookie was provided by the client, with a last visit date which is
10697 not completely up-to-date, so an updated cookie was provided in
10698 response. This can also happen if there was no date at all, or if
10699 there was a date but the "maxidle" parameter was not set, so that the
10700 cookie can be switched to unlimited time.
10701
10702 EI A cookie was provided by the client, with a last visit date which is
10703 too old for the "maxidle" parameter, so the cookie was ignored and a
10704 new cookie was inserted in the response.
10705
10706 OI A cookie was provided by the client, with a first visit date which is
10707 too old for the "maxlife" parameter, so the cookie was ignored and a
10708 new cookie was inserted in the response.
10709
10710 DI The server designated by the cookie was down, a new server was
10711 selected and a new cookie was emitted in the response.
10712
10713 VI The server designated by the cookie was not marked dead but could not
10714 be reached. A redispatch happened and selected another one, which was
10715 then advertised in the response.
10716
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010717
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200107188.6. Non-printable characters
10719-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010720
10721In order not to cause trouble to log analysis tools or terminals during log
10722consulting, non-printable characters are not sent as-is into log files, but are
10723converted to the two-digits hexadecimal representation of their ASCII code,
10724prefixed by the character '#'. The only characters that can be logged without
10725being escaped are comprised between 32 and 126 (inclusive). Obviously, the
10726escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
10727is the same for the character '"' which becomes "#22", as well as '{', '|' and
10728'}' when logging headers.
10729
10730Note that the space character (' ') is not encoded in headers, which can cause
10731issues for tools relying on space count to locate fields. A typical header
10732containing spaces is "User-Agent".
10733
10734Last, it has been observed that some syslog daemons such as syslog-ng escape
10735the quote ('"') with a backslash ('\'). The reverse operation can safely be
10736performed since no quote may appear anywhere else in the logs.
10737
10738
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200107398.7. Capturing HTTP cookies
10740---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010741
10742Cookie capture simplifies the tracking a complete user session. This can be
10743achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010744section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010745cookie will simultaneously be checked in the request ("Cookie:" header) and in
10746the response ("Set-Cookie:" header). The respective values will be reported in
10747the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010748locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010749not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
10750user switches to a new session for example, because the server will reassign it
10751a new cookie. It is also possible to detect if a server unexpectedly sets a
10752wrong cookie to a client, leading to session crossing.
10753
10754 Examples :
10755 # capture the first cookie whose name starts with "ASPSESSION"
10756 capture cookie ASPSESSION len 32
10757
10758 # capture the first cookie whose name is exactly "vgnvisitor"
10759 capture cookie vgnvisitor= len 32
10760
10761
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200107628.8. Capturing HTTP headers
10763---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010764
10765Header captures are useful to track unique request identifiers set by an upper
10766proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
10767the response, one can search for information about the response length, how the
10768server asked the cache to behave, or an object location during a redirection.
10769
10770Header captures are performed using the "capture request header" and "capture
10771response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010772section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010773
10774It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010775time. Non-existent headers are logged as empty strings, and if one header
10776appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010777are grouped within braces '{' and '}' in the same order as they were declared,
10778and delimited with a vertical bar '|' without any space. Response headers
10779follow the same representation, but are displayed after a space following the
10780request headers block. These blocks are displayed just before the HTTP request
10781in the logs.
10782
10783 Example :
10784 # This instance chains to the outgoing proxy
10785 listen proxy-out
10786 mode http
10787 option httplog
10788 option logasap
10789 log global
10790 server cache1 192.168.1.1:3128
10791
10792 # log the name of the virtual server
10793 capture request header Host len 20
10794
10795 # log the amount of data uploaded during a POST
10796 capture request header Content-Length len 10
10797
10798 # log the beginning of the referrer
10799 capture request header Referer len 20
10800
10801 # server name (useful for outgoing proxies only)
10802 capture response header Server len 20
10803
10804 # logging the content-length is useful with "option logasap"
10805 capture response header Content-Length len 10
10806
10807 # log the expected cache behaviour on the response
10808 capture response header Cache-Control len 8
10809
10810 # the Via header will report the next proxy's name
10811 capture response header Via len 20
10812
10813 # log the URL location during a redirection
10814 capture response header Location len 20
10815
10816 >>> Aug 9 20:26:09 localhost \
10817 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
10818 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
10819 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
10820 "GET http://fr.adserver.yahoo.com/"
10821
10822 >>> Aug 9 20:30:46 localhost \
10823 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
10824 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
10825 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010010826 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010827
10828 >>> Aug 9 20:30:46 localhost \
10829 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
10830 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
10831 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
10832 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010010833 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010834
10835
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200108368.9. Examples of logs
10837---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010838
10839These are real-world examples of logs accompanied with an explanation. Some of
10840them have been made up by hand. The syslog part has been removed for better
10841reading. Their sole purpose is to explain how to decipher them.
10842
10843 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
10844 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
10845 "HEAD / HTTP/1.0"
10846
10847 => long request (6.5s) entered by hand through 'telnet'. The server replied
10848 in 147 ms, and the session ended normally ('----')
10849
10850 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
10851 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
10852 0/9 "HEAD / HTTP/1.0"
10853
10854 => Idem, but the request was queued in the global queue behind 9 other
10855 requests, and waited there for 1230 ms.
10856
10857 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
10858 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
10859 "GET /image.iso HTTP/1.0"
10860
10861 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010862 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010863 14 ms, 243 bytes of headers were sent to the client, and total time from
10864 accept to first data byte is 30 ms.
10865
10866 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
10867 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
10868 "GET /cgi-bin/bug.cgi? HTTP/1.0"
10869
10870 => the proxy blocked a server response either because of an "rspdeny" or
10871 "rspideny" filter, or because the response was improperly formatted and
Willy Tarreau3c92c5f2011-08-28 09:45:47 +020010872 not HTTP-compliant, or because it blocked sensitive information which
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010873 risked being cached. In this case, the response is replaced with a "502
10874 bad gateway". The flags ("PH--") tell us that it was haproxy who decided
10875 to return the 502 and not the server.
10876
10877 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +010010878 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 +010010879
10880 => the client never completed its request and aborted itself ("C---") after
10881 8.5s, while the proxy was waiting for the request headers ("-R--").
10882 Nothing was sent to any server.
10883
10884 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
10885 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
10886
10887 => The client never completed its request, which was aborted by the
10888 time-out ("c---") after 50s, while the proxy was waiting for the request
10889 headers ("-R--"). Nothing was sent to any server, but the proxy could
10890 send a 408 return code to the client.
10891
10892 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
10893 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
10894
10895 => This log was produced with "option tcplog". The client timed out after
10896 5 seconds ("c----").
10897
10898 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
10899 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +010010900 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010901
10902 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010903 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010904 (config says 'retries 3'), and no redispatch (otherwise we would have
10905 seen "/+3"). Status code 503 was returned to the client. There were 115
10906 connections on this server, 202 connections on this proxy, and 205 on
10907 the global process. It is possible that the server refused the
10908 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +010010909
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010010910
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200109119. Statistics and monitoring
10912----------------------------
10913
10914It is possible to query HAProxy about its status. The most commonly used
10915mechanism is the HTTP statistics page. This page also exposes an alternative
10916CSV output format for monitoring tools. The same format is provided on the
10917Unix socket.
10918
10919
109209.1. CSV format
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010010921---------------
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010010922
Willy Tarreau7f062c42009-03-05 18:43:00 +010010923The statistics may be consulted either from the unix socket or from the HTTP
10924page. Both means provide a CSV format whose fields follow.
10925
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010010926 0. pxname: proxy name
10927 1. svname: service name (FRONTEND for frontend, BACKEND for backend, any name
10928 for server)
10929 2. qcur: current queued requests
10930 3. qmax: max queued requests
10931 4. scur: current sessions
10932 5. smax: max sessions
10933 6. slim: sessions limit
10934 7. stot: total sessions
10935 8. bin: bytes in
10936 9. bout: bytes out
10937 10. dreq: denied requests
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010010938 11. dresp: denied responses
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010010939 12. ereq: request errors
10940 13. econ: connection errors
Willy Tarreauae526782010-03-04 20:34:23 +010010941 14. eresp: response errors (among which srv_abrt)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010010942 15. wretr: retries (warning)
10943 16. wredis: redispatches (warning)
Cyril Bonté0dae5852010-02-03 00:26:28 +010010944 17. status: status (UP/DOWN/NOLB/MAINT/MAINT(via)...)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010010945 18. weight: server weight (server), total weight (backend)
10946 19. act: server is active (server), number of active servers (backend)
10947 20. bck: server is backup (server), number of backup servers (backend)
10948 21. chkfail: number of failed checks
10949 22. chkdown: number of UP->DOWN transitions
10950 23. lastchg: last status change (in seconds)
10951 24. downtime: total downtime (in seconds)
10952 25. qlimit: queue limit
10953 26. pid: process id (0 for first instance, 1 for second, ...)
10954 27. iid: unique proxy id
10955 28. sid: service id (unique inside a proxy)
10956 29. throttle: warm up status
10957 30. lbtot: total number of times a server was selected
10958 31. tracked: id of proxy/server if tracking is enabled
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +020010959 32. type (0=frontend, 1=backend, 2=server, 3=socket)
Krzysztof Piotr Oledzkidb57c6b2009-08-31 21:23:27 +020010960 33. rate: number of sessions per second over last elapsed second
10961 34. rate_lim: limit on new sessions per second
10962 35. rate_max: max number of new sessions per second
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +020010963 36. check_status: status of last health check, one of:
Cyril Bontéf0c60612010-02-06 14:44:47 +010010964 UNK -> unknown
10965 INI -> initializing
10966 SOCKERR -> socket error
10967 L4OK -> check passed on layer 4, no upper layers testing enabled
10968 L4TMOUT -> layer 1-4 timeout
10969 L4CON -> layer 1-4 connection problem, for example
10970 "Connection refused" (tcp rst) or "No route to host" (icmp)
10971 L6OK -> check passed on layer 6
10972 L6TOUT -> layer 6 (SSL) timeout
10973 L6RSP -> layer 6 invalid response - protocol error
10974 L7OK -> check passed on layer 7
10975 L7OKC -> check conditionally passed on layer 7, for example 404 with
10976 disable-on-404
10977 L7TOUT -> layer 7 (HTTP/SMTP) timeout
10978 L7RSP -> layer 7 invalid response - protocol error
10979 L7STS -> layer 7 response error, for example HTTP 5xx
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +020010980 37. check_code: layer5-7 code, if available
10981 38. check_duration: time in ms took to finish last health check
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010982 39. hrsp_1xx: http responses with 1xx code
10983 40. hrsp_2xx: http responses with 2xx code
10984 41. hrsp_3xx: http responses with 3xx code
10985 42. hrsp_4xx: http responses with 4xx code
10986 43. hrsp_5xx: http responses with 5xx code
10987 44. hrsp_other: http responses with other codes (protocol error)
Willy Tarreaud63335a2010-02-26 12:56:52 +010010988 45. hanafail: failed health checks details
10989 46. req_rate: HTTP requests per second over last elapsed second
10990 47. req_rate_max: max number of HTTP requests per second observed
10991 48. req_tot: total number of HTTP requests received
Willy Tarreauae526782010-03-04 20:34:23 +010010992 49. cli_abrt: number of data transfers aborted by the client
10993 50. srv_abrt: number of data transfers aborted by the server (inc. in eresp)
Willy Tarreau844e3c52008-01-11 16:28:18 +010010994
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010010995
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200109969.2. Unix Socket commands
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010010997-------------------------
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010010998
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010010999The following commands are supported on the UNIX stats socket ; all of them
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011000must be terminated by a line feed. The socket supports pipelining, so that it
11001is possible to chain multiple commands at once provided they are delimited by
11002a semi-colon or a line feed, although the former is more reliable as it has no
11003risk of being truncated over the network. The responses themselves will each be
11004followed by an empty line, so it will be easy for an external script to match a
11005given response with a given request. By default one command line is processed
11006then the connection closes, but there is an interactive allowing multiple lines
11007to be issued one at a time.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011008
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011009It is important to understand that when multiple haproxy processes are started
11010on the same sockets, any process may pick up the request and will output its
11011own stats.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011012
Willy Tarreaud63335a2010-02-26 12:56:52 +010011013clear counters
11014 Clear the max values of the statistics counters in each proxy (frontend &
11015 backend) and in each server. The cumulated counters are not affected. This
11016 can be used to get clean counters after an incident, without having to
11017 restart nor to clear traffic counters. This command is restricted and can
11018 only be issued on sockets configured for levels "operator" or "admin".
11019
11020clear counters all
11021 Clear all statistics counters in each proxy (frontend & backend) and in each
11022 server. This has the same effect as restarting. This command is restricted
11023 and can only be issued on sockets configured for level "admin".
11024
Simon Hormanc88b8872011-06-15 15:18:49 +090011025clear table <table> [ data.<type> <operator> <value> ] | [ key <key> ]
11026 Remove entries from the stick-table <table>.
11027
11028 This is typically used to unblock some users complaining they have been
11029 abusively denied access to a service, but this can also be used to clear some
11030 stickiness entries matching a server that is going to be replaced (see "show
11031 table" below for details). Note that sometimes, removal of an entry will be
11032 refused because it is currently tracked by a session. Retrying a few seconds
11033 later after the session ends is usual enough.
11034
11035 In the case where no options arguments are given all entries will be removed.
11036
11037 When the "data." form is used entries matching a filter applied using the
11038 stored data (see "stick-table" in section 4.2) are removed. A stored data
11039 type must be specified in <type>, and this data type must be stored in the
11040 table otherwise an error is reported. The data is compared according to
11041 <operator> with the 64-bit integer <value>. Operators are the same as with
11042 the ACLs :
11043
11044 - eq : match entries whose data is equal to this value
11045 - ne : match entries whose data is not equal to this value
11046 - le : match entries whose data is less than or equal to this value
11047 - ge : match entries whose data is greater than or equal to this value
11048 - lt : match entries whose data is less than this value
11049 - gt : match entries whose data is greater than this value
11050
11051 When the key form is used the entry <key> is removed. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +090011052 same type as the table, which currently is limited to IPv4, IPv6, integer and
11053 string.
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011054
11055 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020011056 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +020011057 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020011058 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
11059 bytes_out_rate(60000)=187
11060 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
11061 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011062
11063 $ echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1
11064
11065 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +020011066 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau62a36c42010-08-17 15:53:10 +020011067 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
11068 bytes_out_rate(60000)=191
Simon Hormanc88b8872011-06-15 15:18:49 +090011069 $ echo "clear table http_proxy data.gpc0 eq 1" | socat stdio /tmp/sock1
11070 $ echo "show table http_proxy" | socat stdio /tmp/sock1
11071 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011072
Willy Tarreau532a4502011-09-07 22:37:44 +020011073disable frontend <frontend>
11074 Mark the frontend as temporarily stopped. This corresponds to the mode which
11075 is used during a soft restart : the frontend releases the port but can be
11076 enabled again if needed. This should be used with care as some non-Linux OSes
11077 are unable to enable it back. This is intended to be used in environments
11078 where stopping a proxy is not even imaginable but a misconfigured proxy must
11079 be fixed. That way it's possible to release the port and bind it into another
11080 process to restore operations. The frontend will appear with status "STOP"
11081 on the stats page.
11082
11083 The frontend may be specified either by its name or by its numeric ID,
11084 prefixed with a sharp ('#').
11085
11086 This command is restricted and can only be issued on sockets configured for
11087 level "admin".
11088
Willy Tarreaud63335a2010-02-26 12:56:52 +010011089disable server <backend>/<server>
11090 Mark the server DOWN for maintenance. In this mode, no more checks will be
11091 performed on the server until it leaves maintenance.
11092 If the server is tracked by other servers, those servers will be set to DOWN
11093 during the maintenance.
11094
11095 In the statistics page, a server DOWN for maintenance will appear with a
11096 "MAINT" status, its tracking servers with the "MAINT(via)" one.
11097
11098 Both the backend and the server may be specified either by their name or by
Willy Tarreauf5f31922011-08-02 11:32:07 +020011099 their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010011100
11101 This command is restricted and can only be issued on sockets configured for
11102 level "admin".
11103
Willy Tarreau532a4502011-09-07 22:37:44 +020011104enable frontend <frontend>
11105 Resume a frontend which was temporarily stopped. It is possible that some of
11106 the listening ports won't be able to bind anymore (eg: if another process
11107 took them since the 'disable frontend' operation). If this happens, an error
11108 is displayed. Some operating systems might not be able to resume a frontend
11109 which was disabled.
11110
11111 The frontend may be specified either by its name or by its numeric ID,
11112 prefixed with a sharp ('#').
11113
11114 This command is restricted and can only be issued on sockets configured for
11115 level "admin".
11116
Willy Tarreaud63335a2010-02-26 12:56:52 +010011117enable server <backend>/<server>
11118 If the server was previously marked as DOWN for maintenance, this marks the
11119 server UP and checks are re-enabled.
11120
11121 Both the backend and the server may be specified either by their name or by
Willy Tarreauf5f31922011-08-02 11:32:07 +020011122 their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010011123
11124 This command is restricted and can only be issued on sockets configured for
11125 level "admin".
11126
11127get weight <backend>/<server>
11128 Report the current weight and the initial weight of server <server> in
11129 backend <backend> or an error if either doesn't exist. The initial weight is
11130 the one that appears in the configuration file. Both are normally equal
11131 unless the current weight has been changed. Both the backend and the server
11132 may be specified either by their name or by their numeric ID, prefixed with a
Willy Tarreauf5f31922011-08-02 11:32:07 +020011133 sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010011134
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011135help
11136 Print the list of known keywords and their basic usage. The same help screen
11137 is also displayed for unknown commands.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011138
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011139prompt
11140 Toggle the prompt at the beginning of the line and enter or leave interactive
11141 mode. In interactive mode, the connection is not closed after a command
11142 completes. Instead, the prompt will appear again, indicating the user that
11143 the interpreter is waiting for a new command. The prompt consists in a right
11144 angle bracket followed by a space "> ". This mode is particularly convenient
11145 when one wants to periodically check information such as stats or errors.
11146 It is also a good idea to enter interactive mode before issuing a "help"
11147 command.
11148
11149quit
11150 Close the connection when in interactive mode.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010011151
Willy Tarreau2a0f4d22011-08-02 11:49:05 +020011152set maxconn frontend <frontend> <value>
Willy Tarreau3c7a79d2012-09-26 21:07:15 +020011153 Dynamically change the specified frontend's maxconn setting. Any positive
11154 value is allowed including zero, but setting values larger than the global
11155 maxconn does not make much sense. If the limit is increased and connections
11156 were pending, they will immediately be accepted. If it is lowered to a value
11157 below the current number of connections, new connections acceptation will be
Willy Tarreau2a0f4d22011-08-02 11:49:05 +020011158 delayed until the threshold is reached. The frontend might be specified by
11159 either its name or its numeric ID prefixed with a sharp ('#').
11160
Willy Tarreau91886b62011-09-07 14:38:31 +020011161set maxconn global <maxconn>
11162 Dynamically change the global maxconn setting within the range defined by the
11163 initial global maxconn setting. If it is increased and connections were
11164 pending, they will immediately be accepted. If it is lowered to a value below
11165 the current number of connections, new connections acceptation will be
11166 delayed until the threshold is reached. A value of zero restores the initial
11167 setting.
11168
Willy Tarreauf5b22872011-09-07 16:13:44 +020011169set rate-limit connections global <value>
11170 Change the process-wide connection rate limit, which is set by the global
11171 'maxconnrate' setting. A value of zero disables the limitation. This limit
11172 applies to all frontends and the change has an immediate effect. The value
11173 is passed in number of connections per second.
11174
William Lallemandd85f9172012-11-09 17:05:39 +010011175set rate-limit http-compression global <value>
11176 Change the maximum input compression rate, which is set by the global
11177 'maxcomprate' setting. A value of zero disables the limitation. The value is
11178 passed in number of kilobytes per second.
11179
Willy Tarreau654694e2012-06-07 01:03:16 +020011180set table <table> key <key> data.<data_type> <value>
11181 Create or update a stick-table entry in the table. If the key is not present,
11182 an entry is inserted. See stick-table in section 4.2 to find all possible
11183 values for <data_type>. The most likely use consists in dynamically entering
11184 entries for source IP addresses, with a flag in gpc0 to dynamically block an
11185 IP address or affect its quality of service.
11186
Willy Tarreaud63335a2010-02-26 12:56:52 +010011187set timeout cli <delay>
11188 Change the CLI interface timeout for current connection. This can be useful
11189 during long debugging sessions where the user needs to constantly inspect
11190 some indicators without being disconnected. The delay is passed in seconds.
11191
11192set weight <backend>/<server> <weight>[%]
11193 Change a server's weight to the value passed in argument. If the value ends
11194 with the '%' sign, then the new weight will be relative to the initially
11195 configured weight. Relative weights are only permitted between 0 and 100%,
11196 and absolute weights are permitted between 0 and 256. Servers which are part
11197 of a farm running a static load-balancing algorithm have stricter limitations
11198 because the weight cannot change once set. Thus for these servers, the only
11199 accepted values are 0 and 100% (or 0 and the initial weight). Changes take
11200 effect immediately, though certain LB algorithms require a certain amount of
11201 requests to consider changes. A typical usage of this command is to disable
11202 a server during an update by setting its weight to zero, then to enable it
11203 again after the update by setting it back to 100%. This command is restricted
11204 and can only be issued on sockets configured for level "admin". Both the
11205 backend and the server may be specified either by their name or by their
Willy Tarreauf5f31922011-08-02 11:32:07 +020011206 numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010011207
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010011208show errors [<iid>]
11209 Dump last known request and response errors collected by frontends and
11210 backends. If <iid> is specified, the limit the dump to errors concerning
Willy Tarreau6162db22009-10-10 17:13:00 +020011211 either frontend or backend whose ID is <iid>. This command is restricted
11212 and can only be issued on sockets configured for levels "operator" or
11213 "admin".
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010011214
11215 The errors which may be collected are the last request and response errors
11216 caused by protocol violations, often due to invalid characters in header
11217 names. The report precisely indicates what exact character violated the
11218 protocol. Other important information such as the exact date the error was
11219 detected, frontend and backend names, the server name (when known), the
11220 internal session ID and the source address which has initiated the session
11221 are reported too.
11222
11223 All characters are returned, and non-printable characters are encoded. The
11224 most common ones (\t = 9, \n = 10, \r = 13 and \e = 27) are encoded as one
11225 letter following a backslash. The backslash itself is encoded as '\\' to
11226 avoid confusion. Other non-printable characters are encoded '\xNN' where
11227 NN is the two-digits hexadecimal representation of the character's ASCII
11228 code.
11229
11230 Lines are prefixed with the position of their first character, starting at 0
11231 for the beginning of the buffer. At most one input line is printed per line,
11232 and large lines will be broken into multiple consecutive output lines so that
11233 the output never goes beyond 79 characters wide. It is easy to detect if a
11234 line was broken, because it will not end with '\n' and the next line's offset
11235 will be followed by a '+' sign, indicating it is a continuation of previous
11236 line.
11237
11238 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020011239 $ echo "show errors" | socat stdio /tmp/sock1
11240 >>> [04/Mar/2009:15:46:56.081] backend http-in (#2) : invalid response
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010011241 src 127.0.0.1, session #54, frontend fe-eth0 (#1), server s2 (#1)
11242 response length 213 bytes, error at position 23:
11243
11244 00000 HTTP/1.0 200 OK\r\n
11245 00017 header/bizarre:blah\r\n
11246 00038 Location: blah\r\n
11247 00054 Long-line: this is a very long line which should b
11248 00104+ e broken into multiple lines on the output buffer,
11249 00154+ otherwise it would be too large to print in a ter
11250 00204+ minal\r\n
11251 00211 \r\n
11252
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011253 In the example above, we see that the backend "http-in" which has internal
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010011254 ID 2 has blocked an invalid response from its server s2 which has internal
11255 ID 1. The request was on session 54 initiated by source 127.0.0.1 and
11256 received by frontend fe-eth0 whose ID is 1. The total response length was
11257 213 bytes when the error was detected, and the error was at byte 23. This
11258 is the slash ('/') in header name "header/bizarre", which is not a valid
11259 HTTP character for a header name.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010011260
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011261show info
11262 Dump info about haproxy status on current process.
11263
11264show sess
11265 Dump all known sessions. Avoid doing this on slow connections as this can
Willy Tarreau6162db22009-10-10 17:13:00 +020011266 be huge. This command is restricted and can only be issued on sockets
11267 configured for levels "operator" or "admin".
11268
Willy Tarreau66dc20a2010-03-05 17:53:32 +010011269show sess <id>
11270 Display a lot of internal information about the specified session identifier.
11271 This identifier is the first field at the beginning of the lines in the dumps
11272 of "show sess" (it corresponds to the session pointer). Those information are
11273 useless to most users but may be used by haproxy developers to troubleshoot a
11274 complex bug. The output format is intentionally not documented so that it can
11275 freely evolve depending on demands.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011276
11277show stat [<iid> <type> <sid>]
11278 Dump statistics in the CSV format. By passing <id>, <type> and <sid>, it is
11279 possible to dump only selected items :
11280 - <iid> is a proxy ID, -1 to dump everything
11281 - <type> selects the type of dumpable objects : 1 for frontends, 2 for
11282 backends, 4 for servers, -1 for everything. These values can be ORed,
11283 for example:
11284 1 + 2 = 3 -> frontend + backend.
11285 1 + 2 + 4 = 7 -> frontend + backend + server.
11286 - <sid> is a server ID, -1 to dump everything from the selected proxy.
11287
11288 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020011289 $ echo "show info;show stat" | socat stdio unix-connect:/tmp/sock1
11290 >>> Name: HAProxy
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011291 Version: 1.4-dev2-49
11292 Release_date: 2009/09/23
11293 Nbproc: 1
11294 Process_num: 1
11295 (...)
11296
11297 # pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,dreq, (...)
11298 stats,FRONTEND,,,0,0,1000,0,0,0,0,0,0,,,,,OPEN,,,,,,,,,1,1,0, (...)
11299 stats,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,0,0,0,,0,250,(...)
11300 (...)
11301 www1,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,1,1,0,,0,250, (...)
11302
11303 $
11304
11305 Here, two commands have been issued at once. That way it's easy to find
11306 which process the stats apply to in multi-process mode. Notice the empty
11307 line after the information output which marks the end of the first block.
11308 A similar empty line appears at the end of the second block (stats) so that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011309 the reader knows the output has not been truncated.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011310
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011311show table
11312 Dump general information on all known stick-tables. Their name is returned
11313 (the name of the proxy which holds them), their type (currently zero, always
11314 IP), their size in maximum possible number of entries, and the number of
11315 entries currently in use.
11316
11317 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020011318 $ echo "show table" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090011319 >>> # table: front_pub, type: ip, size:204800, used:171454
11320 >>> # table: back_rdp, type: ip, size:204800, used:0
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011321
Simon Horman17bce342011-06-15 15:18:47 +090011322show table <name> [ data.<type> <operator> <value> ] | [ key <key> ]
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011323 Dump contents of stick-table <name>. In this mode, a first line of generic
11324 information about the table is reported as with "show table", then all
11325 entries are dumped. Since this can be quite heavy, it is possible to specify
Simon Horman17bce342011-06-15 15:18:47 +090011326 a filter in order to specify what entries to display.
11327
11328 When the "data." form is used the filter applies to the stored data (see
11329 "stick-table" in section 4.2). A stored data type must be specified
11330 in <type>, and this data type must be stored in the table otherwise an
11331 error is reported. The data is compared according to <operator> with the
11332 64-bit integer <value>. Operators are the same as with the ACLs :
11333
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011334 - eq : match entries whose data is equal to this value
11335 - ne : match entries whose data is not equal to this value
11336 - le : match entries whose data is less than or equal to this value
11337 - ge : match entries whose data is greater than or equal to this value
11338 - lt : match entries whose data is less than this value
11339 - gt : match entries whose data is greater than this value
11340
Simon Hormanc88b8872011-06-15 15:18:49 +090011341
11342 When the key form is used the entry <key> is shown. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +090011343 same type as the table, which currently is limited to IPv4, IPv6, integer,
11344 and string.
Simon Horman17bce342011-06-15 15:18:47 +090011345
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011346 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020011347 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090011348 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020011349 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
11350 bytes_out_rate(60000)=187
11351 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
11352 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011353
Willy Tarreau62a36c42010-08-17 15:53:10 +020011354 $ echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090011355 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020011356 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
11357 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011358
Willy Tarreau62a36c42010-08-17 15:53:10 +020011359 $ echo "show table http_proxy data.conn_rate gt 5" | \
11360 socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090011361 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020011362 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
11363 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011364
Simon Horman17bce342011-06-15 15:18:47 +090011365 $ echo "show table http_proxy key 127.0.0.2" | \
11366 socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090011367 >>> # table: http_proxy, type: ip, size:204800, used:2
Simon Horman17bce342011-06-15 15:18:47 +090011368 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
11369 bytes_out_rate(60000)=191
11370
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011371 When the data criterion applies to a dynamic value dependent on time such as
11372 a bytes rate, the value is dynamically computed during the evaluation of the
11373 entry in order to decide whether it has to be dumped or not. This means that
11374 such a filter could match for some time then not match anymore because as
11375 time goes, the average event rate drops.
11376
11377 It is possible to use this to extract lists of IP addresses abusing the
11378 service, in order to monitor them or even blacklist them in a firewall.
11379 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020011380 $ echo "show table http_proxy data.gpc0 gt 0" \
11381 | socat stdio /tmp/sock1 \
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011382 | fgrep 'key=' | cut -d' ' -f2 | cut -d= -f2 > abusers-ip.txt
11383 ( or | awk '/key/{ print a[split($2,a,"=")]; }' )
Krzysztof Piotr Oledzki719e7262009-10-04 15:02:46 +020011384
Willy Tarreau532a4502011-09-07 22:37:44 +020011385shutdown frontend <frontend>
11386 Completely delete the specified frontend. All the ports it was bound to will
11387 be released. It will not be possible to enable the frontend anymore after
11388 this operation. This is intended to be used in environments where stopping a
11389 proxy is not even imaginable but a misconfigured proxy must be fixed. That
11390 way it's possible to release the port and bind it into another process to
11391 restore operations. The frontend will not appear at all on the stats page
11392 once it is terminated.
11393
11394 The frontend may be specified either by its name or by its numeric ID,
11395 prefixed with a sharp ('#').
11396
11397 This command is restricted and can only be issued on sockets configured for
11398 level "admin".
11399
Willy Tarreaua295edc2011-09-07 23:21:03 +020011400shutdown session <id>
11401 Immediately terminate the session matching the specified session identifier.
11402 This identifier is the first field at the beginning of the lines in the dumps
11403 of "show sess" (it corresponds to the session pointer). This can be used to
11404 terminate a long-running session without waiting for a timeout or when an
11405 endless transfer is ongoing. Such terminated sessions are reported with a 'K'
11406 flag in the logs.
11407
Willy Tarreau52b2d222011-09-07 23:48:48 +020011408shutdown sessions <backend>/<server>
11409 Immediately terminate all the sessions attached to the specified server. This
11410 can be used to terminate long-running sessions after a server is put into
11411 maintenance mode, for instance. Such terminated sessions are reported with a
11412 'K' flag in the logs.
11413
Willy Tarreau0ba27502007-12-24 16:55:16 +010011414/*
11415 * Local variables:
11416 * fill-column: 79
11417 * End:
11418 */