blob: 6d4df7db7882291f18d0617eaa42ef46907e1f4e [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 Tarreau1a34d572014-02-03 00:41:29 +01007 2014/02/03
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
Willy Tarreau74ca5042013-06-11 23:12:07 +0200627. Using ACLs and fetching samples
637.1. ACL basics
647.1.1. Matching booleans
657.1.2. Matching integers
667.1.3. Matching strings
677.1.4. Matching regular expressions (regexes)
687.1.5. Matching arbitrary data blocks
697.1.6. Matching IPv4 and IPv6 addresses
707.2. Using ACLs to form conditions
717.3. Fetching samples
727.3.1. Fetching samples from internal states
737.3.2. Fetching samples at Layer 4
747.3.3. Fetching samples at Layer 5
757.3.4. Fetching samples from buffer contents (Layer 6)
767.3.5. Fetching HTTP samples (Layer 7)
777.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020078
798. Logging
808.1. Log levels
818.2. Log formats
828.2.1. Default log format
838.2.2. TCP log format
848.2.3. HTTP log format
William Lallemand48940402012-01-30 16:47:22 +0100858.2.4. Custom log format
Willy Tarreau5f51e1a2012-12-03 18:40:10 +0100868.2.5. Error log format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200878.3. Advanced logging options
888.3.1. Disabling logging of external tests
898.3.2. Logging before waiting for the session to terminate
908.3.3. Raising log level upon errors
918.3.4. Disabling logging of successful connections
928.4. Timing events
938.5. Session state at disconnection
948.6. Non-printable characters
958.7. Capturing HTTP cookies
968.8. Capturing HTTP headers
978.9. Examples of logs
98
999. Statistics and monitoring
1009.1. CSV format
1019.2. Unix Socket commands
102
103
1041. Quick reminder about HTTP
105----------------------------
106
107When haproxy is running in HTTP mode, both the request and the response are
108fully analyzed and indexed, thus it becomes possible to build matching criteria
109on almost anything found in the contents.
110
111However, it is important to understand how HTTP requests and responses are
112formed, and how HAProxy decomposes them. It will then become easier to write
113correct rules and to debug existing configurations.
114
115
1161.1. The HTTP transaction model
117-------------------------------
118
119The HTTP protocol is transaction-driven. This means that each request will lead
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100120to one and only one response. Traditionally, a TCP connection is established
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200121from the client to the server, a request is sent by the client on the
122connection, the server responds and the connection is closed. A new request
123will involve a new connection :
124
125 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
126
127In this mode, called the "HTTP close" mode, there are as many connection
128establishments as there are HTTP transactions. Since the connection is closed
129by the server after the response, the client does not need to know the content
130length.
131
132Due to the transactional nature of the protocol, it was possible to improve it
133to avoid closing a connection between two subsequent transactions. In this mode
134however, it is mandatory that the server indicates the content length for each
135response so that the client does not wait indefinitely. For this, a special
136header is used: "Content-length". This mode is called the "keep-alive" mode :
137
138 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
139
140Its advantages are a reduced latency between transactions, and less processing
141power required on the server side. It is generally better than the close mode,
142but not always because the clients often limit their concurrent connections to
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200143a smaller value.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200144
145A last improvement in the communications is the pipelining mode. It still uses
146keep-alive, but the client does not wait for the first response to send the
147second request. This is useful for fetching large number of images composing a
148page :
149
150 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
151
152This can obviously have a tremendous benefit on performance because the network
153latency is eliminated between subsequent requests. Many HTTP agents do not
154correctly support pipelining since there is no way to associate a response with
155the corresponding request in HTTP. For this reason, it is mandatory for the
Cyril Bonté78caf842010-03-10 22:41:43 +0100156server to reply in the exact same order as the requests were received.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200157
Willy Tarreau70dffda2014-01-30 03:07:23 +0100158By default HAProxy operates in keep-alive mode with regards to persistent
159connections: for each connection it processes each request and response, and
160leaves the connection idle on both sides between the end of a response and the
161start of a new request.
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200162
Willy Tarreau70dffda2014-01-30 03:07:23 +0100163HAProxy supports 5 connection modes :
164 - keep alive : all requests and responses are processed (default)
165 - tunnel : only the first request and response are processed,
166 everything else is forwarded with no analysis.
167 - passive close : tunnel with "Connection: close" added in both directions.
168 - server close : the server-facing connection is closed after the response.
169 - forced close : the connection is actively closed after end of response.
170
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200171
1721.2. HTTP request
173-----------------
174
175First, let's consider this HTTP request :
176
177 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100178 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200179 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
180 2 Host: www.mydomain.com
181 3 User-agent: my small browser
182 4 Accept: image/jpeg, image/gif
183 5 Accept: image/png
184
185
1861.2.1. The Request line
187-----------------------
188
189Line 1 is the "request line". It is always composed of 3 fields :
190
191 - a METHOD : GET
192 - a URI : /serv/login.php?lang=en&profile=2
193 - a version tag : HTTP/1.1
194
195All of them are delimited by what the standard calls LWS (linear white spaces),
196which are commonly spaces, but can also be tabs or line feeds/carriage returns
197followed by spaces/tabs. The method itself cannot contain any colon (':') and
198is limited to alphabetic letters. All those various combinations make it
199desirable that HAProxy performs the splitting itself rather than leaving it to
200the user to write a complex or inaccurate regular expression.
201
202The URI itself can have several forms :
203
204 - A "relative URI" :
205
206 /serv/login.php?lang=en&profile=2
207
208 It is a complete URL without the host part. This is generally what is
209 received by servers, reverse proxies and transparent proxies.
210
211 - An "absolute URI", also called a "URL" :
212
213 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
214
215 It is composed of a "scheme" (the protocol name followed by '://'), a host
216 name or address, optionally a colon (':') followed by a port number, then
217 a relative URI beginning at the first slash ('/') after the address part.
218 This is generally what proxies receive, but a server supporting HTTP/1.1
219 must accept this form too.
220
221 - a star ('*') : this form is only accepted in association with the OPTIONS
222 method and is not relayable. It is used to inquiry a next hop's
223 capabilities.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100224
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200225 - an address:port combination : 192.168.0.12:80
226 This is used with the CONNECT method, which is used to establish TCP
227 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
228 other protocols too.
229
230In a relative URI, two sub-parts are identified. The part before the question
231mark is called the "path". It is typically the relative path to static objects
232on the server. The part after the question mark is called the "query string".
233It is mostly used with GET requests sent to dynamic scripts and is very
234specific to the language, framework or application in use.
235
236
2371.2.2. The request headers
238--------------------------
239
240The headers start at the second line. They are composed of a name at the
241beginning of the line, immediately followed by a colon (':'). Traditionally,
242an LWS is added after the colon but that's not required. Then come the values.
243Multiple identical headers may be folded into one single line, delimiting the
244values with commas, provided that their order is respected. This is commonly
245encountered in the "Cookie:" field. A header may span over multiple lines if
246the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
247define a total of 3 values for the "Accept:" header.
248
249Contrary to a common mis-conception, header names are not case-sensitive, and
250their values are not either if they refer to other header names (such as the
251"Connection:" header).
252
253The end of the headers is indicated by the first empty line. People often say
254that it's a double line feed, which is not exact, even if a double line feed
255is one valid form of empty line.
256
257Fortunately, HAProxy takes care of all these complex combinations when indexing
258headers, checking values and counting them, so there is no reason to worry
259about the way they could be written, but it is important not to accuse an
260application of being buggy if it does unusual, valid things.
261
262Important note:
263 As suggested by RFC2616, HAProxy normalizes headers by replacing line breaks
264 in the middle of headers by LWS in order to join multi-line headers. This
265 is necessary for proper analysis and helps less capable HTTP parsers to work
266 correctly and not to be fooled by such complex constructs.
267
268
2691.3. HTTP response
270------------------
271
272An HTTP response looks very much like an HTTP request. Both are called HTTP
273messages. Let's consider this HTTP response :
274
275 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100276 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200277 1 HTTP/1.1 200 OK
278 2 Content-length: 350
279 3 Content-Type: text/html
280
Willy Tarreau816b9792009-09-15 21:25:21 +0200281As a special case, HTTP supports so called "Informational responses" as status
282codes 1xx. These messages are special in that they don't convey any part of the
283response, they're just used as sort of a signaling message to ask a client to
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100284continue to post its request for instance. In the case of a status 100 response
285the requested information will be carried by the next non-100 response message
286following the informational one. This implies that multiple responses may be
287sent to a single request, and that this only works when keep-alive is enabled
288(1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to
289correctly forward and skip them, and only process the next non-100 response. As
290such, these messages are neither logged nor transformed, unless explicitly
291state otherwise. Status 101 messages indicate that the protocol is changing
292over the same connection and that haproxy must switch to tunnel mode, just as
293if a CONNECT had occurred. Then the Upgrade header would contain additional
294information about the type of protocol the connection is switching to.
Willy Tarreau816b9792009-09-15 21:25:21 +0200295
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200296
2971.3.1. The Response line
298------------------------
299
300Line 1 is the "response line". It is always composed of 3 fields :
301
302 - a version tag : HTTP/1.1
303 - a status code : 200
304 - a reason : OK
305
306The status code is always 3-digit. The first digit indicates a general status :
Willy Tarreau816b9792009-09-15 21:25:21 +0200307 - 1xx = informational message to be skipped (eg: 100, 101)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200308 - 2xx = OK, content is following (eg: 200, 206)
309 - 3xx = OK, no content following (eg: 302, 304)
310 - 4xx = error caused by the client (eg: 401, 403, 404)
311 - 5xx = error caused by the server (eg: 500, 502, 503)
312
313Please refer to RFC2616 for the detailed meaning of all such codes. The
Willy Tarreaud72758d2010-01-12 10:42:19 +0100314"reason" field is just a hint, but is not parsed by clients. Anything can be
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200315found there, but it's a common practice to respect the well-established
316messages. It can be composed of one or multiple words, such as "OK", "Found",
317or "Authentication Required".
318
319Haproxy may emit the following status codes by itself :
320
321 Code When / reason
322 200 access to stats page, and when replying to monitoring requests
323 301 when performing a redirection, depending on the configured code
324 302 when performing a redirection, depending on the configured code
325 303 when performing a redirection, depending on the configured code
Willy Tarreaub67fdc42013-03-29 19:28:11 +0100326 307 when performing a redirection, depending on the configured code
327 308 when performing a redirection, depending on the configured code
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200328 400 for an invalid or too large request
329 401 when an authentication is required to perform the action (when
330 accessing the stats page)
331 403 when a request is forbidden by a "block" ACL or "reqdeny" filter
332 408 when the request timeout strikes before the request is complete
333 500 when haproxy encounters an unrecoverable internal error, such as a
334 memory allocation failure, which should never happen
335 502 when the server returns an empty, invalid or incomplete response, or
336 when an "rspdeny" filter blocks the response.
337 503 when no server was available to handle the request, or in response to
338 monitoring requests which match the "monitor fail" condition
339 504 when the response timeout strikes before the server responds
340
341The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3424.2).
343
344
3451.3.2. The response headers
346---------------------------
347
348Response headers work exactly like request headers, and as such, HAProxy uses
349the same parsing function for both. Please refer to paragraph 1.2.2 for more
350details.
351
352
3532. Configuring HAProxy
354----------------------
355
3562.1. Configuration file format
357------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200358
359HAProxy's configuration process involves 3 major sources of parameters :
360
361 - the arguments from the command-line, which always take precedence
362 - the "global" section, which sets process-wide parameters
363 - the proxies sections which can take form of "defaults", "listen",
364 "frontend" and "backend".
365
Willy Tarreau0ba27502007-12-24 16:55:16 +0100366The configuration file syntax consists in lines beginning with a keyword
367referenced in this manual, optionally followed by one or several parameters
368delimited by spaces. If spaces have to be entered in strings, then they must be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100369preceded by a backslash ('\') to be escaped. Backslashes also have to be
Willy Tarreau0ba27502007-12-24 16:55:16 +0100370escaped by doubling them.
371
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200372
3732.2. Time format
374----------------
375
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100376Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100377values are generally expressed in milliseconds (unless explicitly stated
378otherwise) but may be expressed in any other unit by suffixing the unit to the
379numeric value. It is important to consider this because it will not be repeated
380for every keyword. Supported units are :
381
382 - us : microseconds. 1 microsecond = 1/1000000 second
383 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
384 - s : seconds. 1s = 1000ms
385 - m : minutes. 1m = 60s = 60000ms
386 - h : hours. 1h = 60m = 3600s = 3600000ms
387 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
388
389
Patrick Mezard35da19c2010-06-12 17:02:47 +02003902.3. Examples
391-------------
392
393 # Simple configuration for an HTTP proxy listening on port 80 on all
394 # interfaces and forwarding requests to a single backend "servers" with a
395 # single server "server1" listening on 127.0.0.1:8000
396 global
397 daemon
398 maxconn 256
399
400 defaults
401 mode http
402 timeout connect 5000ms
403 timeout client 50000ms
404 timeout server 50000ms
405
406 frontend http-in
407 bind *:80
408 default_backend servers
409
410 backend servers
411 server server1 127.0.0.1:8000 maxconn 32
412
413
414 # The same configuration defined with a single listen block. Shorter but
415 # less expressive, especially in HTTP mode.
416 global
417 daemon
418 maxconn 256
419
420 defaults
421 mode http
422 timeout connect 5000ms
423 timeout client 50000ms
424 timeout server 50000ms
425
426 listen http-in
427 bind *:80
428 server server1 127.0.0.1:8000 maxconn 32
429
430
431Assuming haproxy is in $PATH, test these configurations in a shell with:
432
Willy Tarreauccb289d2010-12-11 20:19:38 +0100433 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200434
435
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004363. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200437--------------------
438
439Parameters in the "global" section are process-wide and often OS-specific. They
440are generally set once for all and do not need being changed once correct. Some
441of them have command-line equivalents.
442
443The following keywords are supported in the "global" section :
444
445 * Process management and security
Emeric Brunc8e8d122012-10-02 18:42:10 +0200446 - ca-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200447 - chroot
Emeric Brunc8e8d122012-10-02 18:42:10 +0200448 - crt-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200449 - daemon
450 - gid
451 - group
452 - log
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100453 - log-send-hostname
Willy Tarreau6a06a402007-07-15 20:15:28 +0200454 - nbproc
455 - pidfile
456 - uid
457 - ulimit-n
458 - user
Willy Tarreaufbee7132007-10-18 13:53:22 +0200459 - stats
Emeric Brun850efd52014-01-29 12:24:34 +0100460 - ssl-server-verify
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200461 - node
462 - description
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100463 - unix-bind
Willy Tarreaud72758d2010-01-12 10:42:19 +0100464
Willy Tarreau6a06a402007-07-15 20:15:28 +0200465 * Performance tuning
466 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +0200467 - maxconnrate
William Lallemandd85f9172012-11-09 17:05:39 +0100468 - maxcomprate
William Lallemand072a2bf2012-11-20 17:01:01 +0100469 - maxcompcpuusage
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100470 - maxpipes
Willy Tarreau93e7c002013-10-07 18:51:07 +0200471 - maxsessrate
Willy Tarreau403edff2012-09-06 11:58:37 +0200472 - maxsslconn
Willy Tarreaue43d5322013-10-07 20:01:52 +0200473 - maxsslrate
Willy Tarreau6a06a402007-07-15 20:15:28 +0200474 - noepoll
475 - nokqueue
476 - nopoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100477 - nosplice
Willy Tarreaufe255b72007-10-14 23:09:26 +0200478 - spread-checks
Willy Tarreau27a674e2009-08-17 07:23:33 +0200479 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200480 - tune.chksize
William Lallemandf3747832012-11-09 12:33:10 +0100481 - tune.comp.maxlevel
Willy Tarreau193b8c62012-11-22 00:17:38 +0100482 - tune.http.cookielen
Willy Tarreauac1932d2011-10-24 19:14:41 +0200483 - tune.http.maxhdr
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100484 - tune.maxaccept
485 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200486 - tune.maxrewrite
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200487 - tune.pipesize
Willy Tarreaue803de22010-01-21 17:43:04 +0100488 - tune.rcvbuf.client
489 - tune.rcvbuf.server
490 - tune.sndbuf.client
491 - tune.sndbuf.server
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100492 - tune.ssl.cachesize
Willy Tarreaubfd59462013-02-21 07:46:09 +0100493 - tune.ssl.lifetime
494 - tune.ssl.maxrecord
William Lallemanda509e4c2012-11-07 16:54:34 +0100495 - tune.zlib.memlevel
496 - tune.zlib.windowsize
Willy Tarreaud72758d2010-01-12 10:42:19 +0100497
Willy Tarreau6a06a402007-07-15 20:15:28 +0200498 * Debugging
499 - debug
500 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200501
502
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005033.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200504------------------------------------
505
Emeric Brunc8e8d122012-10-02 18:42:10 +0200506ca-base <dir>
507 Assigns a default directory to fetch SSL CA certificates and CRLs from when a
Emeric Brunfd33a262012-10-11 16:28:27 +0200508 relative path is used with "ca-file" or "crl-file" directives. Absolute
509 locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200510
Willy Tarreau6a06a402007-07-15 20:15:28 +0200511chroot <jail dir>
512 Changes current directory to <jail dir> and performs a chroot() there before
513 dropping privileges. This increases the security level in case an unknown
514 vulnerability would be exploited, since it would make it very hard for the
515 attacker to exploit the system. This only works when the process is started
516 with superuser privileges. It is important to ensure that <jail_dir> is both
517 empty and unwritable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100518
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100519cpu-map <"all"|"odd"|"even"|process_num> <cpu-set>...
520 On Linux 2.6 and above, it is possible to bind a process to a specific CPU
521 set. This means that the process will never run on other CPUs. The "cpu-map"
522 directive specifies CPU sets for process sets. The first argument is the
523 process number to bind. This process must have a number between 1 and 32,
524 and any process IDs above nbproc are ignored. It is possible to specify all
525 processes at once using "all", only odd numbers using "odd" or even numbers
526 using "even", just like with the "bind-process" directive. The second and
527 forthcoming arguments are CPU sets. Each CPU set is either a unique number
528 between 0 and 31 or a range with two such numbers delimited by a dash ('-').
529 Multiple CPU numbers or ranges may be specified, and the processes will be
530 allowed to bind to all of them. Obviously, multiple "cpu-map" directives may
531 be specified. Each "cpu-map" directive will replace the previous ones when
532 they overlap.
533
Emeric Brunc8e8d122012-10-02 18:42:10 +0200534crt-base <dir>
535 Assigns a default directory to fetch SSL certificates from when a relative
536 path is used with "crtfile" directives. Absolute locations specified after
537 "crtfile" prevail and ignore "crt-base".
538
Willy Tarreau6a06a402007-07-15 20:15:28 +0200539daemon
540 Makes the process fork into background. This is the recommended mode of
541 operation. It is equivalent to the command line "-D" argument. It can be
542 disabled by the command line "-db" argument.
543
544gid <number>
545 Changes the process' group ID to <number>. It is recommended that the group
546 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
547 be started with a user belonging to this group, or with superuser privileges.
Michael Schererab012dd2013-01-12 18:35:19 +0100548 Note that if haproxy is started from a user having supplementary groups, it
549 will only be able to drop these groups if started with superuser privileges.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200550 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100551
Willy Tarreau6a06a402007-07-15 20:15:28 +0200552group <group name>
553 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
554 See also "gid" and "user".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100555
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200556log <address> <facility> [max level [min level]]
Willy Tarreau6a06a402007-07-15 20:15:28 +0200557 Adds a global syslog server. Up to two global servers can be defined. They
558 will receive logs for startups and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100559 configured with "log global".
560
561 <address> can be one of:
562
Willy Tarreau2769aa02007-12-27 18:26:09 +0100563 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100564 no port is specified, 514 is used by default (the standard syslog
565 port).
566
David du Colombier24bb5f52011-03-17 10:40:23 +0100567 - An IPv6 address followed by a colon and optionally a UDP port. If
568 no port is specified, 514 is used by default (the standard syslog
569 port).
570
Robert Tsai81ae1952007-12-05 10:47:29 +0100571 - A filesystem path to a UNIX domain socket, keeping in mind
572 considerations for chroot (be sure the path is accessible inside
573 the chroot) and uid/gid (be sure the path is appropriately
574 writeable).
575
Willy Tarreaudad36a32013-03-11 01:20:04 +0100576 Any part of the address string may reference any number of environment
577 variables by preceding their name with a dollar sign ('$') and
578 optionally enclosing them with braces ('{}'), similarly to what is done
579 in Bourne shell.
580
Robert Tsai81ae1952007-12-05 10:47:29 +0100581 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200582
583 kern user mail daemon auth syslog lpr news
584 uucp cron auth2 ftp ntp audit alert cron2
585 local0 local1 local2 local3 local4 local5 local6 local7
586
587 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200588 all messages are sent. If a maximum level is specified, only messages with a
589 severity at least as important as this level will be sent. An optional minimum
590 level can be specified. If it is set, logs emitted with a more severe level
591 than this one will be capped to this level. This is used to avoid sending
592 "emerg" messages on all terminals on some default syslog configurations.
593 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200594
Cyril Bontédc4d9032012-04-08 21:57:39 +0200595 emerg alert crit err warning notice info debug
Willy Tarreau6a06a402007-07-15 20:15:28 +0200596
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100597log-send-hostname [<string>]
598 Sets the hostname field in the syslog header. If optional "string" parameter
599 is set the header is set to the string contents, otherwise uses the hostname
600 of the system. Generally used if one is not relaying logs through an
601 intermediate syslog server or for simply customizing the hostname printed in
602 the logs.
603
Kevinm48936af2010-12-22 16:08:21 +0000604log-tag <string>
605 Sets the tag field in the syslog header to this string. It defaults to the
606 program name as launched from the command line, which usually is "haproxy".
607 Sometimes it can be useful to differentiate between multiple processes
608 running on the same host.
609
Willy Tarreau6a06a402007-07-15 20:15:28 +0200610nbproc <number>
611 Creates <number> processes when going daemon. This requires the "daemon"
612 mode. By default, only one process is created, which is the recommended mode
613 of operation. For systems limited to small sets of file descriptors per
614 process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES
615 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon".
616
617pidfile <pidfile>
618 Writes pids of all daemons into file <pidfile>. This option is equivalent to
619 the "-p" command line argument. The file must be accessible to the user
620 starting the process. See also "daemon".
621
Willy Tarreau110ecc12012-11-15 17:50:01 +0100622stats bind-process [ all | odd | even | <number 1-32>[-<number 1-32>] ] ...
Willy Tarreau35b7b162012-10-22 23:17:18 +0200623 Limits the stats socket to a certain set of processes numbers. By default the
624 stats socket is bound to all processes, causing a warning to be emitted when
625 nbproc is greater than 1 because there is no way to select the target process
626 when connecting. However, by using this setting, it becomes possible to pin
627 the stats socket to a specific set of processes, typically the first one. The
628 warning will automatically be disabled when this setting is used, whatever
629 the number of processes used.
630
Emeric Brun850efd52014-01-29 12:24:34 +0100631ssl-server-verify [none|required]
632 The default behavior for SSL verify on servers side. If specified to 'none',
633 servers certificates are not verified. The default is 'required' except if
634 forced using cmdline option '-dV'.
635
Willy Tarreauabb175f2012-09-24 12:43:26 +0200636stats socket [<address:port>|<path>] [param*]
637 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
638 Connections to this socket will return various statistics outputs and even
639 allow some commands to be issued to change some runtime settings. Please
640 consult section 9.2 "Unix Socket commands" for more details.
Willy Tarreau6162db22009-10-10 17:13:00 +0200641
Willy Tarreauabb175f2012-09-24 12:43:26 +0200642 All parameters supported by "bind" lines are supported, for instance to
643 restrict access to some users or their access rights. Please consult
644 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200645
646stats timeout <timeout, in milliseconds>
647 The default timeout on the stats socket is set to 10 seconds. It is possible
648 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +0100649 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200650
651stats maxconn <connections>
652 By default, the stats socket is limited to 10 concurrent connections. It is
653 possible to change this value with "stats maxconn".
654
Willy Tarreau6a06a402007-07-15 20:15:28 +0200655uid <number>
656 Changes the process' user ID to <number>. It is recommended that the user ID
657 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
658 be started with superuser privileges in order to be able to switch to another
659 one. See also "gid" and "user".
660
661ulimit-n <number>
662 Sets the maximum number of per-process file-descriptors to <number>. By
663 default, it is automatically computed, so it is recommended not to use this
664 option.
665
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100666unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
667 [ group <group> ] [ gid <gid> ]
668
669 Fixes common settings to UNIX listening sockets declared in "bind" statements.
670 This is mainly used to simplify declaration of those UNIX sockets and reduce
671 the risk of errors, since those settings are most commonly required but are
672 also process-specific. The <prefix> setting can be used to force all socket
673 path to be relative to that directory. This might be needed to access another
674 component's chroot. Note that those paths are resolved before haproxy chroots
675 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
676 all have the same meaning as their homonyms used by the "bind" statement. If
677 both are specified, the "bind" statement has priority, meaning that the
678 "unix-bind" settings may be seen as process-wide default settings.
679
Willy Tarreau6a06a402007-07-15 20:15:28 +0200680user <user name>
681 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
682 See also "uid" and "group".
683
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200684node <name>
685 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
686
687 This statement is useful in HA configurations where two or more processes or
688 servers share the same IP address. By setting a different node-name on all
689 nodes, it becomes easy to immediately spot what server is handling the
690 traffic.
691
692description <text>
693 Add a text that describes the instance.
694
695 Please note that it is required to escape certain characters (# for example)
696 and this text is inserted into a html page so you should avoid using
697 "<" and ">" characters.
698
Willy Tarreau6a06a402007-07-15 20:15:28 +0200699
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007003.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +0200701-----------------------
702
703maxconn <number>
704 Sets the maximum per-process number of concurrent connections to <number>. It
705 is equivalent to the command-line argument "-n". Proxies will stop accepting
706 connections when this limit is reached. The "ulimit-n" parameter is
707 automatically adjusted according to this value. See also "ulimit-n".
708
Willy Tarreau81c25d02011-09-07 15:17:21 +0200709maxconnrate <number>
710 Sets the maximum per-process number of connections per second to <number>.
711 Proxies will stop accepting connections when this limit is reached. It can be
712 used to limit the global capacity regardless of each frontend capacity. It is
713 important to note that this can only be used as a service protection measure,
714 as there will not necessarily be a fair share between frontends when the
715 limit is reached, so it's a good idea to also limit each frontend to some
716 value close to its expected share. Also, lowering tune.maxaccept can improve
717 fairness.
718
William Lallemandd85f9172012-11-09 17:05:39 +0100719maxcomprate <number>
720 Sets the maximum per-process input compression rate to <number> kilobytes
721 pers second. For each session, if the maximum is reached, the compression
722 level will be decreased during the session. If the maximum is reached at the
723 beginning of a session, the session will not compress at all. If the maximum
724 is not reached, the compression level will be increased up to
725 tune.comp.maxlevel. A value of zero means there is no limit, this is the
726 default value.
727
William Lallemand072a2bf2012-11-20 17:01:01 +0100728maxcompcpuusage <number>
729 Sets the maximum CPU usage HAProxy can reach before stopping the compression
730 for new requests or decreasing the compression level of current requests.
731 It works like 'maxcomprate' but measures CPU usage instead of incoming data
732 bandwidth. The value is expressed in percent of the CPU used by haproxy. In
733 case of multiple processes (nbproc > 1), each process manages its individual
734 usage. A value of 100 disable the limit. The default value is 100. Setting
735 a lower value will prevent the compression work from slowing the whole
736 process down and from introducing high latencies.
737
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100738maxpipes <number>
739 Sets the maximum per-process number of pipes to <number>. Currently, pipes
740 are only used by kernel-based tcp splicing. Since a pipe contains two file
741 descriptors, the "ulimit-n" value will be increased accordingly. The default
742 value is maxconn/4, which seems to be more than enough for most heavy usages.
743 The splice code dynamically allocates and releases pipes, and can fall back
744 to standard copy, so setting this value too low may only impact performance.
745
Willy Tarreau93e7c002013-10-07 18:51:07 +0200746maxsessrate <number>
747 Sets the maximum per-process number of sessions per second to <number>.
748 Proxies will stop accepting connections when this limit is reached. It can be
749 used to limit the global capacity regardless of each frontend capacity. It is
750 important to note that this can only be used as a service protection measure,
751 as there will not necessarily be a fair share between frontends when the
752 limit is reached, so it's a good idea to also limit each frontend to some
753 value close to its expected share. Also, lowering tune.maxaccept can improve
754 fairness.
755
Willy Tarreau403edff2012-09-06 11:58:37 +0200756maxsslconn <number>
757 Sets the maximum per-process number of concurrent SSL connections to
758 <number>. By default there is no SSL-specific limit, which means that the
759 global maxconn setting will apply to all connections. Setting this limit
760 avoids having openssl use too much memory and crash when malloc returns NULL
761 (since it unfortunately does not reliably check for such conditions). Note
762 that the limit applies both to incoming and outgoing connections, so one
763 connection which is deciphered then ciphered accounts for 2 SSL connections.
764
Willy Tarreaue43d5322013-10-07 20:01:52 +0200765maxsslrate <number>
766 Sets the maximum per-process number of SSL sessions per second to <number>.
767 SSL listeners will stop accepting connections when this limit is reached. It
768 can be used to limit the global SSL CPU usage regardless of each frontend
769 capacity. It is important to note that this can only be used as a service
770 protection measure, as there will not necessarily be a fair share between
771 frontends when the limit is reached, so it's a good idea to also limit each
772 frontend to some value close to its expected share. It is also important to
773 note that the sessions are accounted before they enter the SSL stack and not
774 after, which also protects the stack against bad handshakes. Also, lowering
775 tune.maxaccept can improve fairness.
776
William Lallemand9d5f5482012-11-07 16:12:57 +0100777maxzlibmem <number>
778 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
779 When the maximum amount is reached, future sessions will not compress as long
780 as RAM is unavailable. When sets to 0, there is no limit.
William Lallemande3a7d992012-11-20 11:25:20 +0100781 The default value is 0. The value is available in bytes on the UNIX socket
782 with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is
783 "ZlibMemUsage" in bytes.
784
Willy Tarreau6a06a402007-07-15 20:15:28 +0200785noepoll
786 Disables the use of the "epoll" event polling system on Linux. It is
787 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100788 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +0200789
790nokqueue
791 Disables the use of the "kqueue" event polling system on BSD. It is
792 equivalent to the command-line argument "-dk". The next polling system
793 used will generally be "poll". See also "nopoll".
794
795nopoll
796 Disables the use of the "poll" event polling system. It is equivalent to the
797 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +0100798 It should never be needed to disable "poll" since it's available on all
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100799 platforms supported by HAProxy. See also "nokqueue" and "noepoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +0200800
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100801nosplice
802 Disables the use of kernel tcp splicing between sockets on Linux. It is
803 equivalent to the command line argument "-dS". Data will then be copied
804 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100805 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100806 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
807 be used. This option makes it easier to globally disable kernel splicing in
808 case of doubt. See also "option splice-auto", "option splice-request" and
809 "option splice-response".
810
Willy Tarreaufe255b72007-10-14 23:09:26 +0200811spread-checks <0..50, in percent>
Simon Hormand60d6912013-11-25 10:46:36 +0900812 Sometimes it is desirable to avoid sending agent and health checks to
813 servers at exact intervals, for instance when many logical servers are
814 located on the same physical server. With the help of this parameter, it
815 becomes possible to add some randomness in the check interval between 0
816 and +/- 50%. A value between 2 and 5 seems to show good results. The
817 default value remains at 0.
Willy Tarreaufe255b72007-10-14 23:09:26 +0200818
Willy Tarreau27a674e2009-08-17 07:23:33 +0200819tune.bufsize <number>
820 Sets the buffer size to this size (in bytes). Lower values allow more
821 sessions to coexist in the same amount of RAM, and higher values allow some
822 applications with very large cookies to work. The default value is 16384 and
823 can be changed at build time. It is strongly recommended not to change this
824 from the default value, as very low values will break some services such as
825 statistics, and values larger than default size will increase memory usage,
826 possibly causing the system to run out of memory. At least the global maxconn
827 parameter should be decreased by the same factor as this one is increased.
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +0400828 If HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will
829 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
830 than this size, haproxy will return HTTP 502 (Bad Gateway).
Willy Tarreau27a674e2009-08-17 07:23:33 +0200831
Willy Tarreau43961d52010-10-04 20:39:20 +0200832tune.chksize <number>
833 Sets the check buffer size to this size (in bytes). Higher values may help
834 find string or regex patterns in very large pages, though doing so may imply
835 more memory and CPU usage. The default value is 16384 and can be changed at
836 build time. It is not recommended to change this value, but to use better
837 checks whenever possible.
838
William Lallemandf3747832012-11-09 12:33:10 +0100839tune.comp.maxlevel <number>
840 Sets the maximum compression level. The compression level affects CPU
841 usage during compression. This value affects CPU usage during compression.
842 Each session using compression initializes the compression algorithm with
843 this value. The default value is 1.
844
Willy Tarreau193b8c62012-11-22 00:17:38 +0100845tune.http.cookielen <number>
846 Sets the maximum length of captured cookies. This is the maximum value that
847 the "capture cookie xxx len yyy" will be allowed to take, and any upper value
848 will automatically be truncated to this one. It is important not to set too
849 high a value because all cookie captures still allocate this size whatever
850 their configured value (they share a same pool). This value is per request
851 per response, so the memory allocated is twice this value per connection.
852 When not specified, the limit is set to 63 characters. It is recommended not
853 to change this value.
854
Willy Tarreauac1932d2011-10-24 19:14:41 +0200855tune.http.maxhdr <number>
856 Sets the maximum number of headers in a request. When a request comes with a
857 number of headers greater than this value (including the first line), it is
858 rejected with a "400 Bad Request" status code. Similarly, too large responses
859 are blocked with "502 Bad Gateway". The default value is 101, which is enough
860 for all usages, considering that the widely deployed Apache server uses the
861 same limit. It can be useful to push this limit further to temporarily allow
862 a buggy application to work by the time it gets fixed. Keep in mind that each
863 new header consumes 32bits of memory for each session, so don't push this
864 limit too high.
865
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100866tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +0100867 Sets the maximum number of consecutive connections a process may accept in a
868 row before switching to other work. In single process mode, higher numbers
869 give better performance at high connection rates. However in multi-process
870 modes, keeping a bit of fairness between processes generally is better to
871 increase performance. This value applies individually to each listener, so
872 that the number of processes a listener is bound to is taken into account.
873 This value defaults to 64. In multi-process mode, it is divided by twice
874 the number of processes the listener is bound to. Setting this value to -1
875 completely disables the limitation. It should normally not be needed to tweak
876 this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100877
878tune.maxpollevents <number>
879 Sets the maximum amount of events that can be processed at once in a call to
880 the polling system. The default value is adapted to the operating system. It
881 has been noticed that reducing it below 200 tends to slightly decrease
882 latency at the expense of network bandwidth, and increasing it above 200
883 tends to trade latency for slightly increased bandwidth.
884
Willy Tarreau27a674e2009-08-17 07:23:33 +0200885tune.maxrewrite <number>
886 Sets the reserved buffer space to this size in bytes. The reserved space is
887 used for header rewriting or appending. The first reads on sockets will never
888 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
889 bufsize, though that does not make much sense since there are rarely large
890 numbers of headers to add. Setting it too high prevents processing of large
891 requests or responses. Setting it too low prevents addition of new headers
892 to already large requests or to POST requests. It is generally wise to set it
893 to about 1024. It is automatically readjusted to half of bufsize if it is
894 larger than that. This means you don't have to worry about it when changing
895 bufsize.
896
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200897tune.pipesize <number>
898 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
899 are the default size for the system. But sometimes when using TCP splicing,
900 it can improve performance to increase pipe sizes, especially if it is
901 suspected that pipes are not filled and that many calls to splice() are
902 performed. This has an impact on the kernel's memory footprint, so this must
903 not be changed if impacts are not understood.
904
Willy Tarreaue803de22010-01-21 17:43:04 +0100905tune.rcvbuf.client <number>
906tune.rcvbuf.server <number>
907 Forces the kernel socket receive buffer size on the client or the server side
908 to the specified value in bytes. This value applies to all TCP/HTTP frontends
909 and backends. It should normally never be set, and the default size (0) lets
910 the kernel autotune this value depending on the amount of available memory.
911 However it can sometimes help to set it to very low values (eg: 4096) in
912 order to save kernel memory by preventing it from buffering too large amounts
913 of received data. Lower values will significantly increase CPU usage though.
914
915tune.sndbuf.client <number>
916tune.sndbuf.server <number>
917 Forces the kernel socket send buffer size on the client or the server side to
918 the specified value in bytes. This value applies to all TCP/HTTP frontends
919 and backends. It should normally never be set, and the default size (0) lets
920 the kernel autotune this value depending on the amount of available memory.
921 However it can sometimes help to set it to very low values (eg: 4096) in
922 order to save kernel memory by preventing it from buffering too large amounts
923 of received data. Lower values will significantly increase CPU usage though.
924 Another use case is to prevent write timeouts with extremely slow clients due
925 to the kernel waiting for a large part of the buffer to be read before
926 notifying haproxy again.
927
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100928tune.ssl.cachesize <number>
Emeric Brunaf9619d2012-11-28 18:47:52 +0100929 Sets the size of the global SSL session cache, in a number of blocks. A block
930 is large enough to contain an encoded session without peer certificate.
931 An encoded session with peer certificate is stored in multiple blocks
932 depending on the size of the peer certificate. A block use approximatively
933 200 bytes of memory. The default value may be forced at build time, otherwise
934 defaults to 20000. When the cache is full, the most idle entries are purged
935 and reassigned. Higher values reduce the occurrence of such a purge, hence
936 the number of CPU-intensive SSL handshakes by ensuring that all users keep
937 their session as long as possible. All entries are pre-allocated upon startup
Emeric Brun22890a12012-12-28 14:41:32 +0100938 and are shared between all processes if "nbproc" is greater than 1. Setting
939 this value to 0 disables the SSL session cache.
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100940
Emeric Brun4f65bff2012-11-16 15:11:00 +0100941tune.ssl.lifetime <timeout>
942 Sets how long a cached SSL session may remain valid. This time is expressed
943 in seconds and defaults to 300 (5 mn). It is important to understand that it
944 does not guarantee that sessions will last that long, because if the cache is
945 full, the longest idle sessions will be purged despite their configured
946 lifetime. The real usefulness of this setting is to prevent sessions from
947 being used for too long.
948
Willy Tarreaubfd59462013-02-21 07:46:09 +0100949tune.ssl.maxrecord <number>
950 Sets the maximum amount of bytes passed to SSL_write() at a time. Default
951 value 0 means there is no limit. Over SSL/TLS, the client can decipher the
952 data only once it has received a full record. With large records, it means
953 that clients might have to download up to 16kB of data before starting to
954 process them. Limiting the value can improve page load times on browsers
955 located over high latency or low bandwidth networks. It is suggested to find
956 optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over
957 Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled),
958 keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and
959 2859 gave good results during tests. Use "strace -e trace=write" to find the
960 best value.
961
William Lallemanda509e4c2012-11-07 16:54:34 +0100962tune.zlib.memlevel <number>
963 Sets the memLevel parameter in zlib initialization for each session. It
964 defines how much memory should be allocated for the intenal compression
965 state. A value of 1 uses minimum memory but is slow and reduces compression
966 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
967 between 1 and 9. The default value is 8.
968
969tune.zlib.windowsize <number>
970 Sets the window size (the size of the history buffer) as a parameter of the
971 zlib initialization for each session. Larger values of this parameter result
972 in better compression at the expense of memory usage. Can be a value between
973 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200974
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009753.3. Debugging
976--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200977
978debug
979 Enables debug mode which dumps to stdout all exchanges, and disables forking
980 into background. It is the equivalent of the command-line argument "-d". It
981 should never be used in a production configuration since it may prevent full
982 system startup.
983
984quiet
985 Do not display any message during startup. It is equivalent to the command-
986 line argument "-q".
987
Emeric Brunf099e792010-09-27 12:05:28 +0200988
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01009893.4. Userlists
990--------------
991It is possible to control access to frontend/backend/listen sections or to
992http stats by allowing only authenticated and authorized users. To do this,
993it is required to create at least one userlist and to define users.
994
995userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +0100996 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100997 used to store authentication & authorization data for independent customers.
998
999group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +01001000 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001001 attach users to this group by using a comma separated list of names
1002 proceeded by "users" keyword.
1003
Cyril Bontéf0c60612010-02-06 14:44:47 +01001004user <username> [password|insecure-password <password>]
1005 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001006 Adds user <username> to the current userlist. Both secure (encrypted) and
1007 insecure (unencrypted) passwords can be used. Encrypted passwords are
Cyril Bonté78caf842010-03-10 22:41:43 +01001008 evaluated using the crypt(3) function so depending of the system's
1009 capabilities, different algorithms are supported. For example modern Glibc
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001010 based Linux system supports MD5, SHA-256, SHA-512 and of course classic,
1011 DES-based method of crypting passwords.
1012
1013
1014 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +01001015 userlist L1
1016 group G1 users tiger,scott
1017 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001018
Cyril Bontéf0c60612010-02-06 14:44:47 +01001019 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
1020 user scott insecure-password elgato
1021 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001022
Cyril Bontéf0c60612010-02-06 14:44:47 +01001023 userlist L2
1024 group G1
1025 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001026
Cyril Bontéf0c60612010-02-06 14:44:47 +01001027 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
1028 user scott insecure-password elgato groups G1,G2
1029 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01001030
1031 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001032
Emeric Brunf099e792010-09-27 12:05:28 +02001033
10343.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +02001035----------
Emeric Brunf099e792010-09-27 12:05:28 +02001036It is possible to synchronize server entries in stick tables between several
1037haproxy instances over TCP connections in a multi-master fashion. Each instance
1038pushes its local updates and insertions to remote peers. Server IDs are used to
1039identify servers remotely, so it is important that configurations look similar
1040or at least that the same IDs are forced on each server on all participants.
1041Interrupted exchanges are automatically detected and recovered from the last
1042known point. In addition, during a soft restart, the old process connects to
1043the new one using such a TCP connection to push all its entries before the new
1044process tries to connect to other peers. That ensures very fast replication
1045during a reload, it typically takes a fraction of a second even for large
1046tables.
1047
1048peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001049 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +02001050 which is referenced by one or more stick-tables.
1051
1052peer <peername> <ip>:<port>
1053 Defines a peer inside a peers section.
1054 If <peername> is set to the local peer name (by default hostname, or forced
1055 using "-L" command line option), haproxy will listen for incoming remote peer
1056 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
1057 to join the remote peer, and <peername> is used at the protocol level to
1058 identify and validate the remote peer on the server side.
1059
1060 During a soft restart, local peer <ip>:<port> is used by the old instance to
1061 connect the new one and initiate a complete replication (teaching process).
1062
1063 It is strongly recommended to have the exact same peers declaration on all
1064 peers and to only rely on the "-L" command line argument to change the local
1065 peer name. This makes it easier to maintain coherent configuration files
1066 across all peers.
1067
Willy Tarreaudad36a32013-03-11 01:20:04 +01001068 Any part of the address string may reference any number of environment
1069 variables by preceding their name with a dollar sign ('$') and optionally
1070 enclosing them with braces ('{}'), similarly to what is done in Bourne shell.
1071
Cyril Bontédc4d9032012-04-08 21:57:39 +02001072 Example:
Emeric Brunf099e792010-09-27 12:05:28 +02001073 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001074 peer haproxy1 192.168.0.1:1024
1075 peer haproxy2 192.168.0.2:1024
1076 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +02001077
1078 backend mybackend
1079 mode tcp
1080 balance roundrobin
1081 stick-table type ip size 20k peers mypeers
1082 stick on src
1083
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001084 server srv1 192.168.0.30:80
1085 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +02001086
1087
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010884. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +02001089----------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001090
Willy Tarreau6a06a402007-07-15 20:15:28 +02001091Proxy configuration can be located in a set of sections :
1092 - defaults <name>
1093 - frontend <name>
1094 - backend <name>
1095 - listen <name>
1096
1097A "defaults" section sets default parameters for all other sections following
1098its declaration. Those default parameters are reset by the next "defaults"
1099section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +01001100section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001101
1102A "frontend" section describes a set of listening sockets accepting client
1103connections.
1104
1105A "backend" section describes a set of servers to which the proxy will connect
1106to forward incoming connections.
1107
1108A "listen" section defines a complete proxy with its frontend and backend
1109parts combined in one section. It is generally useful for TCP-only traffic.
1110
Willy Tarreau0ba27502007-12-24 16:55:16 +01001111All proxy names must be formed from upper and lower case letters, digits,
1112'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
1113case-sensitive, which means that "www" and "WWW" are two different proxies.
1114
1115Historically, all proxy names could overlap, it just caused troubles in the
1116logs. Since the introduction of content switching, it is mandatory that two
1117proxies with overlapping capabilities (frontend/backend) have different names.
1118However, it is still permitted that a frontend and a backend share the same
1119name, as this configuration seems to be commonly encountered.
1120
1121Right now, two major proxy modes are supported : "tcp", also known as layer 4,
1122and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001123bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01001124protocol, and can interact with it by allowing, blocking, switching, adding,
1125modifying, or removing arbitrary contents in requests or responses, based on
1126arbitrary criteria.
1127
Willy Tarreau70dffda2014-01-30 03:07:23 +01001128In HTTP mode, the processing applied to requests and responses flowing over
1129a connection depends in the combination of the frontend's HTTP options and
1130the backend's. HAProxy supports 5 connection modes :
1131
1132 - KAL : keep alive ("option http-keep-alive") which is the default mode : all
1133 requests and responses are processed, and connections remain open but idle
1134 between responses and new requests.
1135
1136 - TUN: tunnel ("option http-tunnel") : this was the default mode for versions
1137 1.0 to 1.5-dev21 : only the first request and response are processed, and
1138 everything else is forwarded with no analysis at all. This mode should not
1139 be used as it creates lots of trouble with logging and HTTP processing.
1140
1141 - PCL: passive close ("option httpclose") : exactly the same as tunnel mode,
1142 but with "Connection: close" appended in both directions to try to make
1143 both ends close after the first request/response exchange.
1144
1145 - SCL: server close ("option http-server-close") : the server-facing
1146 connection is closed after the end of the response is received, but the
1147 client-facing connection remains open.
1148
1149 - FCL: forced close ("option forceclose") : the connection is actively closed
1150 after the end of the response.
1151
1152The effective mode that will be applied to a connection passing through a
1153frontend and a backend can be determined by both proxy modes according to the
1154following matrix, but in short, the modes are symmetric, keep-alive is the
1155weakest option and force close is the strongest.
1156
1157 Backend mode
1158
1159 | KAL | TUN | PCL | SCL | FCL
1160 ----+-----+-----+-----+-----+----
1161 KAL | KAL | TUN | PCL | SCL | FCL
1162 ----+-----+-----+-----+-----+----
1163 TUN | TUN | TUN | PCL | SCL | FCL
1164 Frontend ----+-----+-----+-----+-----+----
1165 mode PCL | PCL | PCL | PCL | FCL | FCL
1166 ----+-----+-----+-----+-----+----
1167 SCL | SCL | SCL | FCL | SCL | FCL
1168 ----+-----+-----+-----+-----+----
1169 FCL | FCL | FCL | FCL | FCL | FCL
1170
Willy Tarreau0ba27502007-12-24 16:55:16 +01001171
Willy Tarreau70dffda2014-01-30 03:07:23 +01001172
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011734.1. Proxy keywords matrix
1174--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001175
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001176The following list of keywords is supported. Most of them may only be used in a
1177limited set of section types. Some of them are marked as "deprecated" because
1178they are inherited from an old syntax which may be confusing or functionally
1179limited, and there are new recommended keywords to replace them. Keywords
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001180marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001181option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02001182and must be disabled for a specific instance. Such options may also be prefixed
1183with "default" in order to restore default settings regardless of what has been
1184specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001185
Willy Tarreau6a06a402007-07-15 20:15:28 +02001186
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001187 keyword defaults frontend listen backend
1188------------------------------------+----------+----------+---------+---------
1189acl - X X X
1190appsession - - X X
1191backlog X X X -
1192balance X - X X
1193bind - X X -
1194bind-process X X X X
1195block - X X X
1196capture cookie - X X -
1197capture request header - X X -
1198capture response header - X X -
1199clitimeout (deprecated) X X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02001200compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001201contimeout (deprecated) X - X X
1202cookie X - X X
1203default-server X - X X
1204default_backend X X X -
1205description - X X X
1206disabled X X X X
1207dispatch - - X X
1208enabled X X X X
1209errorfile X X X X
1210errorloc X X X X
1211errorloc302 X X X X
1212-- keyword -------------------------- defaults - frontend - listen -- backend -
1213errorloc303 X X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001214force-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001215fullconn X - X X
1216grace X X X X
1217hash-type X - X X
1218http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +01001219http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02001220http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001221http-request - X X X
Willy Tarreaue365c0b2013-06-11 16:06:12 +02001222http-response - X X X
Baptiste Assmann69e273f2013-12-11 00:52:19 +01001223tcp-check connect - - X X
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02001224tcp-check expect - - X X
1225tcp-check send - - X X
1226tcp-check send-binary - - X X
Baptiste Assmann2c42ef52013-10-09 21:57:02 +02001227http-send-name-header - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001228id - X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001229ignore-persist - X X X
William Lallemand0f99e342011-10-12 17:50:54 +02001230log (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001231maxconn X X X -
1232mode X X X X
1233monitor fail - X X -
1234monitor-net X X X -
1235monitor-uri X X X -
1236option abortonclose (*) X - X X
1237option accept-invalid-http-request (*) X X X -
1238option accept-invalid-http-response (*) X - X X
1239option allbackups (*) X - X X
1240option checkcache (*) X - X X
1241option clitcpka (*) X X X -
1242option contstats (*) X X X -
1243option dontlog-normal (*) X X X -
1244option dontlognull (*) X X X -
1245option forceclose (*) X X X X
1246-- keyword -------------------------- defaults - frontend - listen -- backend -
1247option forwardfor X X X X
Willy Tarreau16bfb022010-01-16 19:48:41 +01001248option http-keep-alive (*) X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02001249option http-no-delay (*) X X X X
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02001250option http-pretend-keepalive (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001251option http-server-close (*) X X X X
Willy Tarreau02bce8b2014-01-30 00:15:28 +01001252option http-tunnel (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001253option http-use-proxy-header (*) X X X -
1254option httpchk X - X X
1255option httpclose (*) X X X X
1256option httplog X X X X
1257option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001258option independent-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02001259option ldap-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001260option log-health-checks (*) X - X X
1261option log-separate-errors (*) X X X -
1262option logasap (*) X X X -
1263option mysql-check X - X X
Rauf Kuliyev38b41562011-01-04 15:14:13 +01001264option pgsql-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001265option nolinger (*) X X X X
1266option originalto X X X X
1267option persist (*) X - X X
1268option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02001269option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001270option smtpchk X - X X
1271option socket-stats (*) X X X -
1272option splice-auto (*) X X X X
1273option splice-request (*) X X X X
1274option splice-response (*) X X X X
1275option srvtcpka (*) X - X X
1276option ssl-hello-chk X - X X
1277-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreaued179852013-12-16 01:07:00 +01001278option tcp-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001279option tcp-smart-accept (*) X X X -
1280option tcp-smart-connect (*) X - X X
1281option tcpka X X X X
1282option tcplog X X X X
1283option transparent (*) X - X X
1284persist rdp-cookie X - X X
1285rate-limit sessions X X X -
1286redirect - X X X
1287redisp (deprecated) X - X X
1288redispatch (deprecated) X - X X
1289reqadd - X X X
1290reqallow - X X X
1291reqdel - X X X
1292reqdeny - X X X
1293reqiallow - X X X
1294reqidel - X X X
1295reqideny - X X X
1296reqipass - X X X
1297reqirep - X X X
1298reqisetbe - X X X
1299reqitarpit - X X X
1300reqpass - X X X
1301reqrep - X X X
1302-- keyword -------------------------- defaults - frontend - listen -- backend -
1303reqsetbe - X X X
1304reqtarpit - X X X
1305retries X - X X
1306rspadd - X X X
1307rspdel - X X X
1308rspdeny - X X X
1309rspidel - X X X
1310rspideny - X X X
1311rspirep - X X X
1312rsprep - X X X
1313server - - X X
1314source X - X X
1315srvtimeout (deprecated) X - X X
Cyril Bonté66c327d2010-10-12 00:14:37 +02001316stats admin - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001317stats auth X - X X
1318stats enable X - X X
1319stats hide-version X - X X
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02001320stats http-request - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001321stats realm X - X X
1322stats refresh X - X X
1323stats scope X - X X
1324stats show-desc X - X X
1325stats show-legends X - X X
1326stats show-node X - X X
1327stats uri X - X X
1328-- keyword -------------------------- defaults - frontend - listen -- backend -
1329stick match - - X X
1330stick on - - X X
1331stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02001332stick store-response - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001333stick-table - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02001334tcp-request connection - X X -
1335tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02001336tcp-request inspect-delay - X X X
Emeric Brun0a3b67f2010-09-24 15:34:53 +02001337tcp-response content - - X X
1338tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001339timeout check X - X X
1340timeout client X X X -
1341timeout clitimeout (deprecated) X X X -
1342timeout connect X - X X
1343timeout contimeout (deprecated) X - X X
1344timeout http-keep-alive X X X X
1345timeout http-request X X X X
1346timeout queue X - X X
1347timeout server X - X X
1348timeout srvtimeout (deprecated) X - X X
1349timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02001350timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001351transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01001352unique-id-format X X X -
1353unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001354use_backend - X X -
Willy Tarreau4a5cade2012-04-05 21:09:48 +02001355use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001356------------------------------------+----------+----------+---------+---------
1357 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02001358
Willy Tarreau0ba27502007-12-24 16:55:16 +01001359
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013604.2. Alphabetically sorted keywords reference
1361---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001362
1363This section provides a description of each keyword and its usage.
1364
1365
1366acl <aclname> <criterion> [flags] [operator] <value> ...
1367 Declare or complete an access list.
1368 May be used in sections : defaults | frontend | listen | backend
1369 no | yes | yes | yes
1370 Example:
1371 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1372 acl invalid_src src_port 0:1023
1373 acl local_dst hdr(host) -i localhost
1374
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001375 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001376
1377
Cyril Bontéb21570a2009-11-29 20:04:48 +01001378appsession <cookie> len <length> timeout <holdtime>
1379 [request-learn] [prefix] [mode <path-parameters|query-string>]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001380 Define session stickiness on an existing application cookie.
1381 May be used in sections : defaults | frontend | listen | backend
1382 no | no | yes | yes
1383 Arguments :
1384 <cookie> this is the name of the cookie used by the application and which
1385 HAProxy will have to learn for each new session.
1386
Cyril Bontéb21570a2009-11-29 20:04:48 +01001387 <length> this is the max number of characters that will be memorized and
Willy Tarreau0ba27502007-12-24 16:55:16 +01001388 checked in each cookie value.
1389
1390 <holdtime> this is the time after which the cookie will be removed from
1391 memory if unused. If no unit is specified, this time is in
1392 milliseconds.
1393
Cyril Bontébf47aeb2009-10-15 00:15:40 +02001394 request-learn
1395 If this option is specified, then haproxy will be able to learn
1396 the cookie found in the request in case the server does not
1397 specify any in response. This is typically what happens with
1398 PHPSESSID cookies, or when haproxy's session expires before
1399 the application's session and the correct server is selected.
1400 It is recommended to specify this option to improve reliability.
1401
Cyril Bontéb21570a2009-11-29 20:04:48 +01001402 prefix When this option is specified, haproxy will match on the cookie
1403 prefix (or URL parameter prefix). The appsession value is the
1404 data following this prefix.
1405
1406 Example :
1407 appsession ASPSESSIONID len 64 timeout 3h prefix
1408
1409 This will match the cookie ASPSESSIONIDXXXX=XXXXX,
1410 the appsession value will be XXXX=XXXXX.
1411
1412 mode This option allows to change the URL parser mode.
1413 2 modes are currently supported :
1414 - path-parameters :
1415 The parser looks for the appsession in the path parameters
1416 part (each parameter is separated by a semi-colon), which is
1417 convenient for JSESSIONID for example.
1418 This is the default mode if the option is not set.
1419 - query-string :
1420 In this mode, the parser will look for the appsession in the
1421 query string.
1422
Willy Tarreau0ba27502007-12-24 16:55:16 +01001423 When an application cookie is defined in a backend, HAProxy will check when
1424 the server sets such a cookie, and will store its value in a table, and
1425 associate it with the server's identifier. Up to <length> characters from
1426 the value will be retained. On each connection, haproxy will look for this
Cyril Bontéb21570a2009-11-29 20:04:48 +01001427 cookie both in the "Cookie:" headers, and as a URL parameter (depending on
1428 the mode used). If a known value is found, the client will be directed to the
1429 server associated with this value. Otherwise, the load balancing algorithm is
Willy Tarreau0ba27502007-12-24 16:55:16 +01001430 applied. Cookies are automatically removed from memory when they have been
1431 unused for a duration longer than <holdtime>.
1432
1433 The definition of an application cookie is limited to one per backend.
1434
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001435 Note : Consider not using this feature in multi-process mode (nbproc > 1)
1436 unless you know what you do : memory is not shared between the
1437 processes, which can result in random behaviours.
1438
Willy Tarreau0ba27502007-12-24 16:55:16 +01001439 Example :
1440 appsession JSESSIONID len 52 timeout 3h
1441
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001442 See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
1443 "ignore-persist", "nbproc" and "bind-process".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001444
1445
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001446backlog <conns>
1447 Give hints to the system about the approximate listen backlog desired size
1448 May be used in sections : defaults | frontend | listen | backend
1449 yes | yes | yes | no
1450 Arguments :
1451 <conns> is the number of pending connections. Depending on the operating
1452 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02001453 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001454
1455 In order to protect against SYN flood attacks, one solution is to increase
1456 the system's SYN backlog size. Depending on the system, sometimes it is just
1457 tunable via a system parameter, sometimes it is not adjustable at all, and
1458 sometimes the system relies on hints given by the application at the time of
1459 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
1460 to the listen() syscall. On systems which can make use of this value, it can
1461 sometimes be useful to be able to specify a different value, hence this
1462 backlog parameter.
1463
1464 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
1465 used as a hint and the system accepts up to the smallest greater power of
1466 two, and never more than some limits (usually 32768).
1467
1468 See also : "maxconn" and the target operating system's tuning guide.
1469
1470
Willy Tarreau0ba27502007-12-24 16:55:16 +01001471balance <algorithm> [ <arguments> ]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001472balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001473 Define the load balancing algorithm to be used in a backend.
1474 May be used in sections : defaults | frontend | listen | backend
1475 yes | no | yes | yes
1476 Arguments :
1477 <algorithm> is the algorithm used to select a server when doing load
1478 balancing. This only applies when no persistence information
1479 is available, or when a connection is redispatched to another
1480 server. <algorithm> may be one of the following :
1481
1482 roundrobin Each server is used in turns, according to their weights.
1483 This is the smoothest and fairest algorithm when the server's
1484 processing time remains equally distributed. This algorithm
1485 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02001486 on the fly for slow starts for instance. It is limited by
Godbacha34bdc02013-07-22 07:44:53 +08001487 design to 4095 active servers per backend. Note that in some
Willy Tarreau9757a382009-10-03 12:56:50 +02001488 large farms, when a server becomes up after having been down
1489 for a very short time, it may sometimes take a few hundreds
1490 requests for it to be re-integrated into the farm and start
1491 receiving traffic. This is normal, though very rare. It is
1492 indicated here in case you would have the chance to observe
1493 it, so that you don't worry.
1494
1495 static-rr Each server is used in turns, according to their weights.
1496 This algorithm is as similar to roundrobin except that it is
1497 static, which means that changing a server's weight on the
1498 fly will have no effect. On the other hand, it has no design
1499 limitation on the number of servers, and when a server goes
1500 up, it is always immediately reintroduced into the farm, once
1501 the full map is recomputed. It also uses slightly less CPU to
1502 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01001503
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01001504 leastconn The server with the lowest number of connections receives the
1505 connection. Round-robin is performed within groups of servers
1506 of the same load to ensure that all servers will be used. Use
1507 of this algorithm is recommended where very long sessions are
1508 expected, such as LDAP, SQL, TSE, etc... but is not very well
1509 suited for protocols using short sessions such as HTTP. This
1510 algorithm is dynamic, which means that server weights may be
1511 adjusted on the fly for slow starts for instance.
1512
Willy Tarreauf09c6602012-02-13 17:12:08 +01001513 first The first server with available connection slots receives the
1514 connection. The servers are choosen from the lowest numeric
1515 identifier to the highest (see server parameter "id"), which
1516 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02001517 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01001518 not make sense to use this algorithm without setting maxconn.
1519 The purpose of this algorithm is to always use the smallest
1520 number of servers so that extra servers can be powered off
1521 during non-intensive hours. This algorithm ignores the server
1522 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02001523 or IMAP than HTTP, though it can be useful there too. In
1524 order to use this algorithm efficiently, it is recommended
1525 that a cloud controller regularly checks server usage to turn
1526 them off when unused, and regularly checks backend queue to
1527 turn new servers on when the queue inflates. Alternatively,
1528 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01001529
Willy Tarreau0ba27502007-12-24 16:55:16 +01001530 source The source IP address is hashed and divided by the total
1531 weight of the running servers to designate which server will
1532 receive the request. This ensures that the same client IP
1533 address will always reach the same server as long as no
1534 server goes down or up. If the hash result changes due to the
1535 number of running servers changing, many clients will be
1536 directed to a different server. This algorithm is generally
1537 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001538 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01001539 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001540 static by default, which means that changing a server's
1541 weight on the fly will have no effect, but this can be
1542 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001543
Oskar Stolc8dc41842012-05-19 10:19:54 +01001544 uri This algorithm hashes either the left part of the URI (before
1545 the question mark) or the whole URI (if the "whole" parameter
1546 is present) and divides the hash value by the total weight of
1547 the running servers. The result designates which server will
1548 receive the request. This ensures that the same URI will
1549 always be directed to the same server as long as no server
1550 goes up or down. This is used with proxy caches and
1551 anti-virus proxies in order to maximize the cache hit rate.
1552 Note that this algorithm may only be used in an HTTP backend.
1553 This algorithm is static by default, which means that
1554 changing a server's weight on the fly will have no effect,
1555 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001556
Oskar Stolc8dc41842012-05-19 10:19:54 +01001557 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001558 "depth", both followed by a positive integer number. These
1559 options may be helpful when it is needed to balance servers
1560 based on the beginning of the URI only. The "len" parameter
1561 indicates that the algorithm should only consider that many
1562 characters at the beginning of the URI to compute the hash.
1563 Note that having "len" set to 1 rarely makes sense since most
1564 URIs start with a leading "/".
1565
1566 The "depth" parameter indicates the maximum directory depth
1567 to be used to compute the hash. One level is counted for each
1568 slash in the request. If both parameters are specified, the
1569 evaluation stops when either is reached.
1570
Willy Tarreau0ba27502007-12-24 16:55:16 +01001571 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001572 the query string of each HTTP GET request.
1573
1574 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02001575 request entity will be searched for the parameter argument,
1576 when it is not found in a query string after a question mark
1577 ('?') in the URL. Optionally, specify a number of octets to
1578 wait for before attempting to search the message body. If the
1579 entity can not be searched, then round robin is used for each
1580 request. For instance, if your clients always send the LB
1581 parameter in the first 128 bytes, then specify that. The
1582 default is 48. The entity data will not be scanned until the
1583 required number of octets have arrived at the gateway, this
1584 is the minimum of: (default/max_wait, Content-Length or first
1585 chunk length). If Content-Length is missing or zero, it does
1586 not need to wait for more data than the client promised to
1587 send. When Content-Length is present and larger than
1588 <max_wait>, then waiting is limited to <max_wait> and it is
1589 assumed that this will be enough data to search for the
1590 presence of the parameter. In the unlikely event that
1591 Transfer-Encoding: chunked is used, only the first chunk is
1592 scanned. Parameter values separated by a chunk boundary, may
1593 be randomly balanced if at all.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001594
1595 If the parameter is found followed by an equal sign ('=') and
1596 a value, then the value is hashed and divided by the total
1597 weight of the running servers. The result designates which
1598 server will receive the request.
1599
1600 This is used to track user identifiers in requests and ensure
1601 that a same user ID will always be sent to the same server as
1602 long as no server goes up or down. If no value is found or if
1603 the parameter is not found, then a round robin algorithm is
1604 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001605 backend. This algorithm is static by default, which means
1606 that changing a server's weight on the fly will have no
1607 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001608
Cyril Bontédc4d9032012-04-08 21:57:39 +02001609 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
1610 request. Just as with the equivalent ACL 'hdr()' function,
1611 the header name in parenthesis is not case sensitive. If the
1612 header is absent or if it does not contain any value, the
1613 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01001614
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001615 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01001616 reducing the hash algorithm to the main domain part with some
1617 specific headers such as 'Host'. For instance, in the Host
1618 value "haproxy.1wt.eu", only "1wt" will be considered.
1619
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001620 This algorithm is static by default, which means that
1621 changing a server's weight on the fly will have no effect,
1622 but this can be changed using "hash-type".
1623
Emeric Brun736aa232009-06-30 17:56:00 +02001624 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02001625 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02001626 The RDP cookie <name> (or "mstshash" if omitted) will be
1627 looked up and hashed for each incoming TCP request. Just as
1628 with the equivalent ACL 'req_rdp_cookie()' function, the name
1629 is not case-sensitive. This mechanism is useful as a degraded
1630 persistence mode, as it makes it possible to always send the
1631 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001632 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02001633 used instead.
1634
1635 Note that for this to work, the frontend must ensure that an
1636 RDP cookie is already present in the request buffer. For this
1637 you must use 'tcp-request content accept' rule combined with
1638 a 'req_rdp_cookie_cnt' ACL.
1639
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001640 This algorithm is static by default, which means that
1641 changing a server's weight on the fly will have no effect,
1642 but this can be changed using "hash-type".
1643
Cyril Bontédc4d9032012-04-08 21:57:39 +02001644 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09001645
Willy Tarreau0ba27502007-12-24 16:55:16 +01001646 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001647 algorithms. Right now, only "url_param" and "uri" support an
1648 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001649
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001650 balance uri [len <len>] [depth <depth>]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001651 balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001652
Willy Tarreau3cd9af22009-03-15 14:06:41 +01001653 The load balancing algorithm of a backend is set to roundrobin when no other
1654 algorithm, mode nor option have been set. The algorithm may only be set once
1655 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001656
1657 Examples :
1658 balance roundrobin
1659 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001660 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01001661 balance hdr(User-Agent)
1662 balance hdr(host)
1663 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001664
1665 Note: the following caveats and limitations on using the "check_post"
1666 extension with "url_param" must be considered :
1667
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001668 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001669 to determine if the parameters will be found in the body or entity which
1670 may contain binary data. Therefore another method may be required to
1671 restrict consideration of POST requests that have no URL parameters in
1672 the body. (see acl reqideny http_end)
1673
1674 - using a <max_wait> value larger than the request buffer size does not
1675 make sense and is useless. The buffer size is set at build time, and
1676 defaults to 16 kB.
1677
1678 - Content-Encoding is not supported, the parameter search will probably
1679 fail; and load balancing will fall back to Round Robin.
1680
1681 - Expect: 100-continue is not supported, load balancing will fall back to
1682 Round Robin.
1683
1684 - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk.
1685 If the entire parameter value is not present in the first chunk, the
1686 selection of server is undefined (actually, defined by how little
1687 actually appeared in the first chunk).
1688
1689 - This feature does not support generation of a 100, 411 or 501 response.
1690
1691 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001692 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001693 white space or control characters are found, indicating the end of what
1694 might be a URL parameter list. This is probably not a concern with SGML
1695 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001696
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001697 See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and
1698 "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001699
1700
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001701bind [<address>]:<port_range> [, ...] [param*]
1702bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001703 Define one or several listening addresses and/or ports in a frontend.
1704 May be used in sections : defaults | frontend | listen | backend
1705 no | yes | yes | no
1706 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001707 <address> is optional and can be a host name, an IPv4 address, an IPv6
1708 address, or '*'. It designates the address the frontend will
1709 listen on. If unset, all IPv4 addresses of the system will be
1710 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01001711 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreau24709282013-03-10 21:32:12 +01001712 Optionally, an address family prefix may be used before the
1713 address to force the family regardless of the address format,
1714 which can be useful to specify a path to a unix socket with
1715 no slash ('/'). Currently supported prefixes are :
1716 - 'ipv4@' -> address is always IPv4
1717 - 'ipv6@' -> address is always IPv6
1718 - 'unix@' -> address is a path to a local unix socket
Willy Tarreau40aa0702013-03-10 23:51:38 +01001719 - 'fd@<n>' -> use file descriptor <n> inherited from the
1720 parent. The fd must be bound and may or may not already
1721 be listening.
Willy Tarreaudad36a32013-03-11 01:20:04 +01001722 Any part of the address string may reference any number of
1723 environment variables by preceding their name with a dollar
1724 sign ('$') and optionally enclosing them with braces ('{}'),
1725 similarly to what is done in Bourne shell.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001726
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001727 <port_range> is either a unique TCP port, or a port range for which the
1728 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001729 above. The port is mandatory for TCP listeners. Note that in
1730 the case of an IPv6 address, the port is always the number
1731 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001732 - a numerical port (ex: '80')
1733 - a dash-delimited ports range explicitly stating the lower
1734 and upper bounds (ex: '2000-2100') which are included in
1735 the range.
1736
1737 Particular care must be taken against port ranges, because
1738 every <address:port> couple consumes one socket (= a file
1739 descriptor), so it's easy to consume lots of descriptors
1740 with a simple range, and to run out of sockets. Also, each
1741 <address:port> couple must be used only once among all
1742 instances running on a same system. Please note that binding
1743 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001744 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001745 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001746
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001747 <path> is a UNIX socket path beginning with a slash ('/'). This is
1748 alternative to the TCP listening port. Haproxy will then
1749 receive UNIX connections on the socket located at this place.
1750 The path must begin with a slash and by default is absolute.
1751 It can be relative to the prefix defined by "unix-bind" in
1752 the global section. Note that the total length of the prefix
1753 followed by the socket path cannot exceed some system limits
1754 for UNIX sockets, which commonly are set to 107 characters.
1755
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001756 <param*> is a list of parameters common to all sockets declared on the
1757 same line. These numerous parameters depend on OS and build
1758 options and have a complete section dedicated to them. Please
1759 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001760
Willy Tarreau0ba27502007-12-24 16:55:16 +01001761 It is possible to specify a list of address:port combinations delimited by
1762 commas. The frontend will then listen on all of these addresses. There is no
1763 fixed limit to the number of addresses and ports which can be listened on in
1764 a frontend, as well as there is no limit to the number of "bind" statements
1765 in a frontend.
1766
1767 Example :
1768 listen http_proxy
1769 bind :80,:443
1770 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001771 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01001772
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001773 listen http_https_proxy
1774 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02001775 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001776
Willy Tarreau24709282013-03-10 21:32:12 +01001777 listen http_https_proxy_explicit
1778 bind ipv6@:80
1779 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
1780 bind unix@ssl-frontend.sock user root mode 600 accept-proxy
1781
Willy Tarreaudad36a32013-03-11 01:20:04 +01001782 listen external_bind_app1
1783 bind fd@${FD_APP1}
1784
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001785 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001786 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001787
1788
Willy Tarreau110ecc12012-11-15 17:50:01 +01001789bind-process [ all | odd | even | <number 1-32>[-<number 1-32>] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001790 Limit visibility of an instance to a certain set of processes numbers.
1791 May be used in sections : defaults | frontend | listen | backend
1792 yes | yes | yes | yes
1793 Arguments :
1794 all All process will see this instance. This is the default. It
1795 may be used to override a default value.
1796
1797 odd This instance will be enabled on processes 1,3,5,...31. This
1798 option may be combined with other numbers.
1799
1800 even This instance will be enabled on processes 2,4,6,...32. This
1801 option may be combined with other numbers. Do not use it
1802 with less than 2 processes otherwise some instances might be
1803 missing from all processes.
1804
Willy Tarreau110ecc12012-11-15 17:50:01 +01001805 number The instance will be enabled on this process number or range,
1806 whose values must all be between 1 and 32. You must be
1807 careful not to reference a process number greater than the
1808 configured global.nbproc, otherwise some instances might be
1809 missing from all processes.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001810
1811 This keyword limits binding of certain instances to certain processes. This
1812 is useful in order not to have too many processes listening to the same
1813 ports. For instance, on a dual-core machine, it might make sense to set
1814 'nbproc 2' in the global section, then distributes the listeners among 'odd'
1815 and 'even' instances.
1816
1817 At the moment, it is not possible to reference more than 32 processes using
1818 this keyword, but this should be more than enough for most setups. Please
1819 note that 'all' really means all processes and is not limited to the first
1820 32.
1821
1822 If some backends are referenced by frontends bound to other processes, the
1823 backend automatically inherits the frontend's processes.
1824
1825 Example :
1826 listen app_ip1
1827 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001828 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001829
1830 listen app_ip2
1831 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001832 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001833
1834 listen management
1835 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001836 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001837
Willy Tarreau110ecc12012-11-15 17:50:01 +01001838 listen management
1839 bind 10.0.0.4:80
1840 bind-process 1-4
1841
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001842 See also : "nbproc" in global section.
1843
1844
Willy Tarreau0ba27502007-12-24 16:55:16 +01001845block { if | unless } <condition>
1846 Block a layer 7 request if/unless a condition is matched
1847 May be used in sections : defaults | frontend | listen | backend
1848 no | yes | yes | yes
1849
1850 The HTTP request will be blocked very early in the layer 7 processing
1851 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001852 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02001853 typically used to deny access to certain sensitive resources if some
Willy Tarreau0ba27502007-12-24 16:55:16 +01001854 conditions are met or not met. There is no fixed limit to the number of
1855 "block" statements per instance.
1856
1857 Example:
1858 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1859 acl invalid_src src_port 0:1023
1860 acl local_dst hdr(host) -i localhost
1861 block if invalid_src || local_dst
1862
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001863 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001864
1865
1866capture cookie <name> len <length>
1867 Capture and log a cookie in the request and in the response.
1868 May be used in sections : defaults | frontend | listen | backend
1869 no | yes | yes | no
1870 Arguments :
1871 <name> is the beginning of the name of the cookie to capture. In order
1872 to match the exact name, simply suffix the name with an equal
1873 sign ('='). The full name will appear in the logs, which is
1874 useful with application servers which adjust both the cookie name
1875 and value (eg: ASPSESSIONXXXXX).
1876
1877 <length> is the maximum number of characters to report in the logs, which
1878 include the cookie name, the equal sign and the value, all in the
1879 standard "name=value" form. The string will be truncated on the
1880 right if it exceeds <length>.
1881
1882 Only the first cookie is captured. Both the "cookie" request headers and the
1883 "set-cookie" response headers are monitored. This is particularly useful to
1884 check for application bugs causing session crossing or stealing between
1885 users, because generally the user's cookies can only change on a login page.
1886
1887 When the cookie was not presented by the client, the associated log column
1888 will report "-". When a request does not cause a cookie to be assigned by the
1889 server, a "-" is reported in the response column.
1890
1891 The capture is performed in the frontend only because it is necessary that
1892 the log format does not change for a given frontend depending on the
1893 backends. This may change in the future. Note that there can be only one
Willy Tarreau193b8c62012-11-22 00:17:38 +01001894 "capture cookie" statement in a frontend. The maximum capture length is set
1895 by the global "tune.http.cookielen" setting and defaults to 63 characters. It
1896 is not possible to specify a capture in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001897
1898 Example:
1899 capture cookie ASPSESSION len 32
1900
1901 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001902 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001903
1904
1905capture request header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01001906 Capture and log the last occurrence of the specified request header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001907 May be used in sections : defaults | frontend | listen | backend
1908 no | yes | yes | no
1909 Arguments :
1910 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001911 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001912 appear in the requests, with the first letter of each word in
1913 upper case. The header name will not appear in the logs, only the
1914 value is reported, but the position in the logs is respected.
1915
1916 <length> is the maximum number of characters to extract from the value and
1917 report in the logs. The string will be truncated on the right if
1918 it exceeds <length>.
1919
Willy Tarreau4460d032012-11-21 23:37:37 +01001920 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001921 value will be added to the logs between braces ('{}'). If multiple headers
1922 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001923 in the same order they were declared in the configuration. Non-existent
1924 headers will be logged just as an empty string. Common uses for request
1925 header captures include the "Host" field in virtual hosting environments, the
1926 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001927 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001928 environments to find where the request came from.
1929
1930 Note that when capturing headers such as "User-agent", some spaces may be
1931 logged, making the log analysis more difficult. Thus be careful about what
1932 you log if you know your log parser is not smart enough to rely on the
1933 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001934
Willy Tarreau0900abb2012-11-22 00:21:46 +01001935 There is no limit to the number of captured request headers nor to their
1936 length, though it is wise to keep them low to limit memory usage per session.
1937 In order to keep log format consistent for a same frontend, header captures
1938 can only be declared in a frontend. It is not possible to specify a capture
1939 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001940
1941 Example:
1942 capture request header Host len 15
1943 capture request header X-Forwarded-For len 15
1944 capture request header Referrer len 15
1945
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001946 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001947 about logging.
1948
1949
1950capture response header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01001951 Capture and log the last occurrence of the specified response header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001952 May be used in sections : defaults | frontend | listen | backend
1953 no | yes | yes | no
1954 Arguments :
1955 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001956 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001957 appear in the response, with the first letter of each word in
1958 upper case. The header name will not appear in the logs, only the
1959 value is reported, but the position in the logs is respected.
1960
1961 <length> is the maximum number of characters to extract from the value and
1962 report in the logs. The string will be truncated on the right if
1963 it exceeds <length>.
1964
Willy Tarreau4460d032012-11-21 23:37:37 +01001965 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001966 result will be added to the logs between braces ('{}') after the captured
1967 request headers. If multiple headers are captured, they will be delimited by
1968 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001969 the configuration. Non-existent headers will be logged just as an empty
1970 string. Common uses for response header captures include the "Content-length"
1971 header which indicates how many bytes are expected to be returned, the
1972 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001973
Willy Tarreau0900abb2012-11-22 00:21:46 +01001974 There is no limit to the number of captured response headers nor to their
1975 length, though it is wise to keep them low to limit memory usage per session.
1976 In order to keep log format consistent for a same frontend, header captures
1977 can only be declared in a frontend. It is not possible to specify a capture
1978 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001979
1980 Example:
1981 capture response header Content-length len 9
1982 capture response header Location len 15
1983
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001984 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001985 about logging.
1986
1987
Cyril Bontéf0c60612010-02-06 14:44:47 +01001988clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01001989 Set the maximum inactivity time on the client side.
1990 May be used in sections : defaults | frontend | listen | backend
1991 yes | yes | yes | no
1992 Arguments :
1993 <timeout> is the timeout value is specified in milliseconds by default, but
1994 can be in any other unit if the number is suffixed by the unit,
1995 as explained at the top of this document.
1996
1997 The inactivity timeout applies when the client is expected to acknowledge or
1998 send data. In HTTP mode, this timeout is particularly important to consider
1999 during the first phase, when the client sends the request, and during the
2000 response while it is reading data sent by the server. The value is specified
2001 in milliseconds by default, but can be in any other unit if the number is
2002 suffixed by the unit, as specified at the top of this document. In TCP mode
2003 (and to a lesser extent, in HTTP mode), it is highly recommended that the
2004 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002005 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01002006 losses by specifying timeouts that are slightly above multiples of 3 seconds
2007 (eg: 4 or 5 seconds).
2008
2009 This parameter is specific to frontends, but can be specified once for all in
2010 "defaults" sections. This is in fact one of the easiest solutions not to
2011 forget about it. An unspecified timeout results in an infinite timeout, which
2012 is not recommended. Such a usage is accepted and works but reports a warning
2013 during startup because it may results in accumulation of expired sessions in
2014 the system if the system's timeouts are not configured either.
2015
2016 This parameter is provided for compatibility but is currently deprecated.
2017 Please use "timeout client" instead.
2018
Willy Tarreau036fae02008-01-06 13:24:40 +01002019 See also : "timeout client", "timeout http-request", "timeout server", and
2020 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002021
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002022compression algo <algorithm> ...
2023compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02002024compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02002025 Enable HTTP compression.
2026 May be used in sections : defaults | frontend | listen | backend
2027 yes | yes | yes | yes
2028 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002029 algo is followed by the list of supported compression algorithms.
2030 type is followed by the list of MIME types that will be compressed.
2031 offload makes haproxy work as a compression offloader only (see notes).
2032
2033 The currently supported algorithms are :
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04002034 identity this is mostly for debugging, and it was useful for developing
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002035 the compression feature. Identity does not apply any change on
2036 data.
2037
2038 gzip applies gzip compression. This setting is only available when
2039 support for zlib was built in.
2040
2041 deflate same as gzip, but with deflate algorithm and zlib format.
2042 Note that this algorithm has ambiguous support on many browsers
2043 and no support at all from recent ones. It is strongly
2044 recommended not to use it for anything else than experimentation.
2045 This setting is only available when support for zlib was built
2046 in.
2047
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04002048 Compression will be activated depending on the Accept-Encoding request
Cyril Bonté316a8cf2012-11-11 13:38:27 +01002049 header. With identity, it does not take care of that header.
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04002050 If backend servers support HTTP compression, these directives
2051 will be no-op: haproxy will see the compressed response and will not
2052 compress again. If backend servers do not support HTTP compression and
2053 there is Accept-Encoding header in request, haproxy will compress the
2054 matching response.
Willy Tarreau70737d12012-10-27 00:34:28 +02002055
2056 The "offload" setting makes haproxy remove the Accept-Encoding header to
2057 prevent backend servers from compressing responses. It is strongly
2058 recommended not to do this because this means that all the compression work
2059 will be done on the single point where haproxy is located. However in some
2060 deployment scenarios, haproxy may be installed in front of a buggy gateway
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04002061 with broken HTTP compression implementation which can't be turned off.
2062 In that case haproxy can be used to prevent that gateway from emitting
2063 invalid payloads. In this case, simply removing the header in the
2064 configuration does not work because it applies before the header is parsed,
2065 so that prevents haproxy from compressing. The "offload" setting should
2066 then be used for such scenarios.
William Lallemand82fe75c2012-10-23 10:25:10 +02002067
William Lallemand05097442012-11-20 12:14:28 +01002068 Compression is disabled when:
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002069 * the request does not advertise a supported compression algorithm in the
2070 "Accept-Encoding" header
2071 * the response message is not HTTP/1.1
William Lallemandd3002612012-11-26 14:34:47 +01002072 * HTTP status code is not 200
William Lallemand8bb4e342013-12-10 17:28:48 +01002073 * response header "Transfer-Encoding" contains "chunked" (Temporary
2074 Workaround)
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002075 * response contain neither a "Content-Length" header nor a
2076 "Transfer-Encoding" whose last value is "chunked"
2077 * response contains a "Content-Type" header whose first value starts with
2078 "multipart"
2079 * the response contains the "no-transform" value in the "Cache-control"
2080 header
2081 * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7
2082 and later
2083 * The response contains a "Content-Encoding" header, indicating that the
2084 response is already compressed (see compression offload)
William Lallemand05097442012-11-20 12:14:28 +01002085
Baptiste Assmann650d53d2013-01-05 15:44:44 +01002086 Note: The compression does not rewrite Etag headers, and does not emit the
2087 Warning header.
William Lallemand05097442012-11-20 12:14:28 +01002088
William Lallemand82fe75c2012-10-23 10:25:10 +02002089 Examples :
2090 compression algo gzip
2091 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01002092
Cyril Bontéf0c60612010-02-06 14:44:47 +01002093contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002094 Set the maximum time to wait for a connection attempt to a server to succeed.
2095 May be used in sections : defaults | frontend | listen | backend
2096 yes | no | yes | yes
2097 Arguments :
2098 <timeout> is the timeout value is specified in milliseconds by default, but
2099 can be in any other unit if the number is suffixed by the unit,
2100 as explained at the top of this document.
2101
2102 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002103 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01002104 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01002105 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
2106 connect timeout also presets the queue timeout to the same value if this one
2107 has not been specified. Historically, the contimeout was also used to set the
2108 tarpit timeout in a listen section, which is not possible in a pure frontend.
2109
2110 This parameter is specific to backends, but can be specified once for all in
2111 "defaults" sections. This is in fact one of the easiest solutions not to
2112 forget about it. An unspecified timeout results in an infinite timeout, which
2113 is not recommended. Such a usage is accepted and works but reports a warning
2114 during startup because it may results in accumulation of failed sessions in
2115 the system if the system's timeouts are not configured either.
2116
2117 This parameter is provided for backwards compatibility but is currently
2118 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
2119 instead.
2120
2121 See also : "timeout connect", "timeout queue", "timeout tarpit",
2122 "timeout server", "contimeout".
2123
2124
Willy Tarreau55165fe2009-05-10 12:02:55 +02002125cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02002126 [ postonly ] [ preserve ] [ httponly ] [ secure ]
2127 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002128 Enable cookie-based persistence in a backend.
2129 May be used in sections : defaults | frontend | listen | backend
2130 yes | no | yes | yes
2131 Arguments :
2132 <name> is the name of the cookie which will be monitored, modified or
2133 inserted in order to bring persistence. This cookie is sent to
2134 the client via a "Set-Cookie" header in the response, and is
2135 brought back by the client in a "Cookie" header in all requests.
2136 Special care should be taken to choose a name which does not
2137 conflict with any likely application cookie. Also, if the same
2138 backends are subject to be used by the same clients (eg:
2139 HTTP/HTTPS), care should be taken to use different cookie names
2140 between all backends if persistence between them is not desired.
2141
2142 rewrite This keyword indicates that the cookie will be provided by the
2143 server and that haproxy will have to modify its value to set the
2144 server's identifier in it. This mode is handy when the management
2145 of complex combinations of "Set-cookie" and "Cache-control"
2146 headers is left to the application. The application can then
2147 decide whether or not it is appropriate to emit a persistence
2148 cookie. Since all responses should be monitored, this mode only
2149 works in HTTP close mode. Unless the application behaviour is
2150 very complex and/or broken, it is advised not to start with this
2151 mode for new deployments. This keyword is incompatible with
2152 "insert" and "prefix".
2153
2154 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02002155 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002156
Willy Tarreaua79094d2010-08-31 22:54:15 +02002157 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002158 server. When used without the "preserve" option, if the server
2159 emits a cookie with the same name, it will be remove before
2160 processing. For this reason, this mode can be used to upgrade
2161 existing configurations running in the "rewrite" mode. The cookie
2162 will only be a session cookie and will not be stored on the
2163 client's disk. By default, unless the "indirect" option is added,
2164 the server will see the cookies emitted by the client. Due to
2165 caching effects, it is generally wise to add the "nocache" or
2166 "postonly" keywords (see below). The "insert" keyword is not
2167 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002168
2169 prefix This keyword indicates that instead of relying on a dedicated
2170 cookie for the persistence, an existing one will be completed.
2171 This may be needed in some specific environments where the client
2172 does not support more than one single cookie and the application
2173 already needs it. In this case, whenever the server sets a cookie
2174 named <name>, it will be prefixed with the server's identifier
2175 and a delimiter. The prefix will be removed from all client
2176 requests so that the server still finds the cookie it emitted.
2177 Since all requests and responses are subject to being modified,
2178 this mode requires the HTTP close mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02002179 not compatible with "rewrite" and "insert". Note: it is highly
2180 recommended not to use "indirect" with "prefix", otherwise server
2181 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002182
Willy Tarreaua79094d2010-08-31 22:54:15 +02002183 indirect When this option is specified, no cookie will be emitted to a
2184 client which already has a valid one for the server which has
2185 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002186 it will be removed, unless the "preserve" option is also set. In
2187 "insert" mode, this will additionally remove cookies from the
2188 requests transmitted to the server, making the persistence
2189 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02002190 Note: it is highly recommended not to use "indirect" with
2191 "prefix", otherwise server cookie updates would not be sent to
2192 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002193
2194 nocache This option is recommended in conjunction with the insert mode
2195 when there is a cache between the client and HAProxy, as it
2196 ensures that a cacheable response will be tagged non-cacheable if
2197 a cookie needs to be inserted. This is important because if all
2198 persistence cookies are added on a cacheable home page for
2199 instance, then all customers will then fetch the page from an
2200 outer cache and will all share the same persistence cookie,
2201 leading to one server receiving much more traffic than others.
2202 See also the "insert" and "postonly" options.
2203
2204 postonly This option ensures that cookie insertion will only be performed
2205 on responses to POST requests. It is an alternative to the
2206 "nocache" option, because POST responses are not cacheable, so
2207 this ensures that the persistence cookie will never get cached.
2208 Since most sites do not need any sort of persistence before the
2209 first POST which generally is a login request, this is a very
2210 efficient method to optimize caching without risking to find a
2211 persistence cookie in the cache.
2212 See also the "insert" and "nocache" options.
2213
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002214 preserve This option may only be used with "insert" and/or "indirect". It
2215 allows the server to emit the persistence cookie itself. In this
2216 case, if a cookie is found in the response, haproxy will leave it
2217 untouched. This is useful in order to end persistence after a
2218 logout request for instance. For this, the server just has to
2219 emit a cookie with an invalid value (eg: empty) or with a date in
2220 the past. By combining this mechanism with the "disable-on-404"
2221 check option, it is possible to perform a completely graceful
2222 shutdown because users will definitely leave the server after
2223 they logout.
2224
Willy Tarreau4992dd22012-05-31 21:02:17 +02002225 httponly This option tells haproxy to add an "HttpOnly" cookie attribute
2226 when a cookie is inserted. This attribute is used so that a
2227 user agent doesn't share the cookie with non-HTTP components.
2228 Please check RFC6265 for more information on this attribute.
2229
2230 secure This option tells haproxy to add a "Secure" cookie attribute when
2231 a cookie is inserted. This attribute is used so that a user agent
2232 never emits this cookie over non-secure channels, which means
2233 that a cookie learned with this flag will be presented only over
2234 SSL/TLS connections. Please check RFC6265 for more information on
2235 this attribute.
2236
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002237 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002238 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01002239 name. If the domain begins with a dot, the browser is allowed to
2240 use it for any host ending with that name. It is also possible to
2241 specify several domain names by invoking this option multiple
2242 times. Some browsers might have small limits on the number of
2243 domains, so be careful when doing that. For the record, sending
2244 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002245
Willy Tarreau996a92c2010-10-13 19:30:47 +02002246 maxidle This option allows inserted cookies to be ignored after some idle
2247 time. It only works with insert-mode cookies. When a cookie is
2248 sent to the client, the date this cookie was emitted is sent too.
2249 Upon further presentations of this cookie, if the date is older
2250 than the delay indicated by the parameter (in seconds), it will
2251 be ignored. Otherwise, it will be refreshed if needed when the
2252 response is sent to the client. This is particularly useful to
2253 prevent users who never close their browsers from remaining for
2254 too long on the same server (eg: after a farm size change). When
2255 this option is set and a cookie has no date, it is always
2256 accepted, but gets refreshed in the response. This maintains the
2257 ability for admins to access their sites. Cookies that have a
2258 date in the future further than 24 hours are ignored. Doing so
2259 lets admins fix timezone issues without risking kicking users off
2260 the site.
2261
2262 maxlife This option allows inserted cookies to be ignored after some life
2263 time, whether they're in use or not. It only works with insert
2264 mode cookies. When a cookie is first sent to the client, the date
2265 this cookie was emitted is sent too. Upon further presentations
2266 of this cookie, if the date is older than the delay indicated by
2267 the parameter (in seconds), it will be ignored. If the cookie in
2268 the request has no date, it is accepted and a date will be set.
2269 Cookies that have a date in the future further than 24 hours are
2270 ignored. Doing so lets admins fix timezone issues without risking
2271 kicking users off the site. Contrary to maxidle, this value is
2272 not refreshed, only the first visit date counts. Both maxidle and
2273 maxlife may be used at the time. This is particularly useful to
2274 prevent users who never close their browsers from remaining for
2275 too long on the same server (eg: after a farm size change). This
2276 is stronger than the maxidle method in that it forces a
2277 redispatch after some absolute delay.
2278
Willy Tarreau0ba27502007-12-24 16:55:16 +01002279 There can be only one persistence cookie per HTTP backend, and it can be
2280 declared in a defaults section. The value of the cookie will be the value
2281 indicated after the "cookie" keyword in a "server" statement. If no cookie
2282 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002283
Willy Tarreau0ba27502007-12-24 16:55:16 +01002284 Examples :
2285 cookie JSESSIONID prefix
2286 cookie SRV insert indirect nocache
2287 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02002288 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01002289
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002290 See also : "appsession", "balance source", "capture cookie", "server"
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002291 and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002292
Willy Tarreau983e01e2010-01-11 18:42:06 +01002293
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002294default-server [param*]
2295 Change default options for a server in a backend
2296 May be used in sections : defaults | frontend | listen | backend
2297 yes | no | yes | yes
2298 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01002299 <param*> is a list of parameters for this server. The "default-server"
2300 keyword accepts an important number of options and has a complete
2301 section dedicated to it. Please refer to section 5 for more
2302 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002303
Willy Tarreau983e01e2010-01-11 18:42:06 +01002304 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002305 default-server inter 1000 weight 13
2306
2307 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01002308
Willy Tarreau983e01e2010-01-11 18:42:06 +01002309
Willy Tarreau0ba27502007-12-24 16:55:16 +01002310default_backend <backend>
2311 Specify the backend to use when no "use_backend" rule has been matched.
2312 May be used in sections : defaults | frontend | listen | backend
2313 yes | yes | yes | no
2314 Arguments :
2315 <backend> is the name of the backend to use.
2316
2317 When doing content-switching between frontend and backends using the
2318 "use_backend" keyword, it is often useful to indicate which backend will be
2319 used when no rule has matched. It generally is the dynamic backend which
2320 will catch all undetermined requests.
2321
Willy Tarreau0ba27502007-12-24 16:55:16 +01002322 Example :
2323
2324 use_backend dynamic if url_dyn
2325 use_backend static if url_css url_img extension_img
2326 default_backend dynamic
2327
Willy Tarreau2769aa02007-12-27 18:26:09 +01002328 See also : "use_backend", "reqsetbe", "reqisetbe"
2329
Willy Tarreau0ba27502007-12-24 16:55:16 +01002330
Baptiste Assmann27f51342013-10-09 06:51:49 +02002331description <string>
2332 Describe a listen, frontend or backend.
2333 May be used in sections : defaults | frontend | listen | backend
2334 no | yes | yes | yes
2335 Arguments : string
2336
2337 Allows to add a sentence to describe the related object in the HAProxy HTML
2338 stats page. The description will be printed on the right of the object name
2339 it describes.
2340 No need to backslash spaces in the <string> arguments.
2341
2342
Willy Tarreau0ba27502007-12-24 16:55:16 +01002343disabled
2344 Disable a proxy, frontend or backend.
2345 May be used in sections : defaults | frontend | listen | backend
2346 yes | yes | yes | yes
2347 Arguments : none
2348
2349 The "disabled" keyword is used to disable an instance, mainly in order to
2350 liberate a listening port or to temporarily disable a service. The instance
2351 will still be created and its configuration will be checked, but it will be
2352 created in the "stopped" state and will appear as such in the statistics. It
2353 will not receive any traffic nor will it send any health-checks or logs. It
2354 is possible to disable many instances at once by adding the "disabled"
2355 keyword in a "defaults" section.
2356
2357 See also : "enabled"
2358
2359
Willy Tarreau5ce94572010-06-07 14:35:41 +02002360dispatch <address>:<port>
2361 Set a default server address
2362 May be used in sections : defaults | frontend | listen | backend
2363 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002364 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02002365
2366 <address> is the IPv4 address of the default server. Alternatively, a
2367 resolvable hostname is supported, but this name will be resolved
2368 during start-up.
2369
2370 <ports> is a mandatory port specification. All connections will be sent
2371 to this port, and it is not permitted to use port offsets as is
2372 possible with normal servers.
2373
Willy Tarreau787aed52011-04-15 06:45:37 +02002374 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02002375 server can take the connection. In the past it was used to forward non
2376 persistent connections to an auxiliary load balancer. Due to its simple
2377 syntax, it has also been used for simple TCP relays. It is recommended not to
2378 use it for more clarity, and to use the "server" directive instead.
2379
2380 See also : "server"
2381
2382
Willy Tarreau0ba27502007-12-24 16:55:16 +01002383enabled
2384 Enable a proxy, frontend or backend.
2385 May be used in sections : defaults | frontend | listen | backend
2386 yes | yes | yes | yes
2387 Arguments : none
2388
2389 The "enabled" keyword is used to explicitly enable an instance, when the
2390 defaults has been set to "disabled". This is very rarely used.
2391
2392 See also : "disabled"
2393
2394
2395errorfile <code> <file>
2396 Return a file contents instead of errors generated by HAProxy
2397 May be used in sections : defaults | frontend | listen | backend
2398 yes | yes | yes | yes
2399 Arguments :
2400 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002401 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002402
2403 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002404 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01002405 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01002406 error pages, and to use absolute paths, since files are read
2407 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002408
2409 It is important to understand that this keyword is not meant to rewrite
2410 errors returned by the server, but errors detected and returned by HAProxy.
2411 This is why the list of supported errors is limited to a small set.
2412
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002413 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2414
Willy Tarreau0ba27502007-12-24 16:55:16 +01002415 The files are returned verbatim on the TCP socket. This allows any trick such
2416 as redirections to another URL or site, as well as tricks to clean cookies,
2417 force enable or disable caching, etc... The package provides default error
2418 files returning the same contents as default errors.
2419
Willy Tarreau59140a22009-02-22 12:02:30 +01002420 The files should not exceed the configured buffer size (BUFSIZE), which
2421 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
2422 not to put any reference to local contents (eg: images) in order to avoid
2423 loops between the client and HAProxy when all servers are down, causing an
2424 error to be returned instead of an image. For better HTTP compliance, it is
2425 recommended that all header lines end with CR-LF and not LF alone.
2426
Willy Tarreau0ba27502007-12-24 16:55:16 +01002427 The files are read at the same time as the configuration and kept in memory.
2428 For this reason, the errors continue to be returned even when the process is
2429 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01002430 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002431 403 status code and interrogating a blocked URL.
2432
2433 See also : "errorloc", "errorloc302", "errorloc303"
2434
Willy Tarreau59140a22009-02-22 12:02:30 +01002435 Example :
2436 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
2437 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
2438 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
2439
Willy Tarreau2769aa02007-12-27 18:26:09 +01002440
2441errorloc <code> <url>
2442errorloc302 <code> <url>
2443 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2444 May be used in sections : defaults | frontend | listen | backend
2445 yes | yes | yes | yes
2446 Arguments :
2447 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002448 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002449
2450 <url> it is the exact contents of the "Location" header. It may contain
2451 either a relative URI to an error page hosted on the same site,
2452 or an absolute URI designating an error page on another site.
2453 Special care should be given to relative URIs to avoid redirect
2454 loops if the URI itself may generate the same error (eg: 500).
2455
2456 It is important to understand that this keyword is not meant to rewrite
2457 errors returned by the server, but errors detected and returned by HAProxy.
2458 This is why the list of supported errors is limited to a small set.
2459
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002460 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2461
Willy Tarreau2769aa02007-12-27 18:26:09 +01002462 Note that both keyword return the HTTP 302 status code, which tells the
2463 client to fetch the designated URL using the same HTTP method. This can be
2464 quite problematic in case of non-GET methods such as POST, because the URL
2465 sent to the client might not be allowed for something other than GET. To
2466 workaround this problem, please use "errorloc303" which send the HTTP 303
2467 status code, indicating to the client that the URL must be fetched with a GET
2468 request.
2469
2470 See also : "errorfile", "errorloc303"
2471
2472
2473errorloc303 <code> <url>
2474 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2475 May be used in sections : defaults | frontend | listen | backend
2476 yes | yes | yes | yes
2477 Arguments :
2478 <code> is the HTTP status code. Currently, HAProxy is capable of
2479 generating codes 400, 403, 408, 500, 502, 503, and 504.
2480
2481 <url> it is the exact contents of the "Location" header. It may contain
2482 either a relative URI to an error page hosted on the same site,
2483 or an absolute URI designating an error page on another site.
2484 Special care should be given to relative URIs to avoid redirect
2485 loops if the URI itself may generate the same error (eg: 500).
2486
2487 It is important to understand that this keyword is not meant to rewrite
2488 errors returned by the server, but errors detected and returned by HAProxy.
2489 This is why the list of supported errors is limited to a small set.
2490
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002491 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2492
Willy Tarreau2769aa02007-12-27 18:26:09 +01002493 Note that both keyword return the HTTP 303 status code, which tells the
2494 client to fetch the designated URL using the same HTTP GET method. This
2495 solves the usual problems associated with "errorloc" and the 302 code. It is
2496 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002497 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002498
2499 See also : "errorfile", "errorloc", "errorloc302"
2500
2501
Willy Tarreau4de91492010-01-22 19:10:05 +01002502force-persist { if | unless } <condition>
2503 Declare a condition to force persistence on down servers
2504 May be used in sections: defaults | frontend | listen | backend
2505 no | yes | yes | yes
2506
2507 By default, requests are not dispatched to down servers. It is possible to
2508 force this using "option persist", but it is unconditional and redispatches
2509 to a valid server if "option redispatch" is set. That leaves with very little
2510 possibilities to force some requests to reach a server which is artificially
2511 marked down for maintenance operations.
2512
2513 The "force-persist" statement allows one to declare various ACL-based
2514 conditions which, when met, will cause a request to ignore the down status of
2515 a server and still try to connect to it. That makes it possible to start a
2516 server, still replying an error to the health checks, and run a specially
2517 configured browser to test the service. Among the handy methods, one could
2518 use a specific source IP address, or a specific cookie. The cookie also has
2519 the advantage that it can easily be added/removed on the browser from a test
2520 page. Once the service is validated, it is then possible to open the service
2521 to the world by returning a valid response to health checks.
2522
2523 The forced persistence is enabled when an "if" condition is met, or unless an
2524 "unless" condition is met. The final redispatch is always disabled when this
2525 is used.
2526
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002527 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002528 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01002529
2530
Willy Tarreau2769aa02007-12-27 18:26:09 +01002531fullconn <conns>
2532 Specify at what backend load the servers will reach their maxconn
2533 May be used in sections : defaults | frontend | listen | backend
2534 yes | no | yes | yes
2535 Arguments :
2536 <conns> is the number of connections on the backend which will make the
2537 servers use the maximal number of connections.
2538
Willy Tarreau198a7442008-01-17 12:05:32 +01002539 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01002540 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01002541 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01002542 load. The server will then always accept at least <minconn> connections,
2543 never more than <maxconn>, and the limit will be on the ramp between both
2544 values when the backend has less than <conns> concurrent connections. This
2545 makes it possible to limit the load on the servers during normal loads, but
2546 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002547 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002548
Willy Tarreaufbb78422011-06-05 15:38:35 +02002549 Since it's hard to get this value right, haproxy automatically sets it to
2550 10% of the sum of the maxconns of all frontends that may branch to this
2551 backend. That way it's safe to leave it unset.
2552
Willy Tarreau2769aa02007-12-27 18:26:09 +01002553 Example :
2554 # The servers will accept between 100 and 1000 concurrent connections each
2555 # and the maximum of 1000 will be reached when the backend reaches 10000
2556 # connections.
2557 backend dynamic
2558 fullconn 10000
2559 server srv1 dyn1:80 minconn 100 maxconn 1000
2560 server srv2 dyn2:80 minconn 100 maxconn 1000
2561
2562 See also : "maxconn", "server"
2563
2564
2565grace <time>
2566 Maintain a proxy operational for some time after a soft stop
2567 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01002568 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01002569 Arguments :
2570 <time> is the time (by default in milliseconds) for which the instance
2571 will remain operational with the frontend sockets still listening
2572 when a soft-stop is received via the SIGUSR1 signal.
2573
2574 This may be used to ensure that the services disappear in a certain order.
2575 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002576 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01002577 needed by the equipment to detect the failure.
2578
2579 Note that currently, there is very little benefit in using this parameter,
2580 and it may in fact complicate the soft-reconfiguration process more than
2581 simplify it.
2582
Willy Tarreau0ba27502007-12-24 16:55:16 +01002583
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05002584hash-type <method> <function> <modifier>
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002585 Specify a method to use for mapping hashes to servers
2586 May be used in sections : defaults | frontend | listen | backend
2587 yes | no | yes | yes
2588 Arguments :
Bhaskar98634f02013-10-29 23:30:51 -04002589 <method> is the method used to select a server from the hash computed by
2590 the <function> :
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002591
Bhaskar98634f02013-10-29 23:30:51 -04002592 map-based the hash table is a static array containing all alive servers.
2593 The hashes will be very smooth, will consider weights, but
2594 will be static in that weight changes while a server is up
2595 will be ignored. This means that there will be no slow start.
2596 Also, since a server is selected by its position in the array,
2597 most mappings are changed when the server count changes. This
2598 means that when a server goes up or down, or when a server is
2599 added to a farm, most connections will be redistributed to
2600 different servers. This can be inconvenient with caches for
2601 instance.
Willy Tarreau798a39c2010-11-24 15:04:29 +01002602
Bhaskar98634f02013-10-29 23:30:51 -04002603 consistent the hash table is a tree filled with many occurrences of each
2604 server. The hash key is looked up in the tree and the closest
2605 server is chosen. This hash is dynamic, it supports changing
2606 weights while the servers are up, so it is compatible with the
2607 slow start feature. It has the advantage that when a server
2608 goes up or down, only its associations are moved. When a
2609 server is added to the farm, only a few part of the mappings
2610 are redistributed, making it an ideal method for caches.
2611 However, due to its principle, the distribution will never be
2612 very smooth and it may sometimes be necessary to adjust a
2613 server's weight or its ID to get a more balanced distribution.
2614 In order to get the same distribution on multiple load
2615 balancers, it is important that all servers have the exact
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05002616 same IDs. Note: consistent hash uses sdbm and avalanche if no
2617 hash function is specified.
Bhaskar98634f02013-10-29 23:30:51 -04002618
2619 <function> is the hash function to be used :
2620
2621 sdbm this function was created intially for sdbm (a public-domain
2622 reimplementation of ndbm) database library. It was found to do
2623 well in scrambling bits, causing better distribution of the keys
2624 and fewer splits. It also happens to be a good general hashing
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05002625 function with good distribution, unless the total server weight
2626 is a multiple of 64, in which case applying the avalanche
2627 modifier may help.
Bhaskar98634f02013-10-29 23:30:51 -04002628
2629 djb2 this function was first proposed by Dan Bernstein many years ago
2630 on comp.lang.c. Studies have shown that for certain workload this
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05002631 function provides a better distribution than sdbm. It generally
2632 works well with text-based inputs though it can perform extremely
2633 poorly with numeric-only input or when the total server weight is
2634 a multiple of 33, unless the avalanche modifier is also used.
2635
Willy Tarreaua0f42712013-11-14 14:30:35 +01002636 wt6 this function was designed for haproxy while testing other
2637 functions in the past. It is not as smooth as the other ones, but
2638 is much less sensible to the input data set or to the number of
2639 servers. It can make sense as an alternative to sdbm+avalanche or
2640 djb2+avalanche for consistent hashing or when hashing on numeric
2641 data such as a source IP address or a visitor identifier in a URL
2642 parameter.
2643
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05002644 <modifier> indicates an optional method applied after hashing the key :
2645
2646 avalanche This directive indicates that the result from the hash
2647 function above should not be used in its raw form but that
2648 a 4-byte full avalanche hash must be applied first. The
2649 purpose of this step is to mix the resulting bits from the
2650 previous hash in order to avoid any undesired effect when
2651 the input contains some limited values or when the number of
2652 servers is a multiple of one of the hash's components (64
2653 for SDBM, 33 for DJB2). Enabling avalanche tends to make the
2654 result less predictable, but it's also not as smooth as when
2655 using the original function. Some testing might be needed
2656 with some workloads. This hash is one of the many proposed
2657 by Bob Jenkins.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002658
Bhaskar98634f02013-10-29 23:30:51 -04002659 The default hash type is "map-based" and is recommended for most usages. The
2660 default function is "sdbm", the selection of a function should be based on
2661 the range of the values being hashed.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002662
2663 See also : "balance", "server"
2664
2665
Willy Tarreau0ba27502007-12-24 16:55:16 +01002666http-check disable-on-404
2667 Enable a maintenance mode upon HTTP/404 response to health-checks
2668 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01002669 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01002670 Arguments : none
2671
2672 When this option is set, a server which returns an HTTP code 404 will be
2673 excluded from further load-balancing, but will still receive persistent
2674 connections. This provides a very convenient method for Web administrators
2675 to perform a graceful shutdown of their servers. It is also important to note
2676 that a server which is detected as failed while it was in this mode will not
2677 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
2678 will immediately be reinserted into the farm. The status on the stats page
2679 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01002680 option only works in conjunction with the "httpchk" option. If this option
2681 is used with "http-check expect", then it has precedence over it so that 404
2682 responses will still be considered as soft-stop.
2683
2684 See also : "option httpchk", "http-check expect"
2685
2686
2687http-check expect [!] <match> <pattern>
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002688 Make HTTP health checks consider response contents or specific status codes
Willy Tarreaubd741542010-03-16 18:46:54 +01002689 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau1ee51a62011-08-19 20:04:17 +02002690 yes | no | yes | yes
Willy Tarreaubd741542010-03-16 18:46:54 +01002691 Arguments :
2692 <match> is a keyword indicating how to look for a specific pattern in the
2693 response. The keyword may be one of "status", "rstatus",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002694 "string", or "rstring". The keyword may be preceded by an
Willy Tarreaubd741542010-03-16 18:46:54 +01002695 exclamation mark ("!") to negate the match. Spaces are allowed
2696 between the exclamation mark and the keyword. See below for more
2697 details on the supported keywords.
2698
2699 <pattern> is the pattern to look for. It may be a string or a regular
2700 expression. If the pattern contains spaces, they must be escaped
2701 with the usual backslash ('\').
2702
2703 By default, "option httpchk" considers that response statuses 2xx and 3xx
2704 are valid, and that others are invalid. When "http-check expect" is used,
2705 it defines what is considered valid or invalid. Only one "http-check"
2706 statement is supported in a backend. If a server fails to respond or times
2707 out, the check obviously fails. The available matches are :
2708
2709 status <string> : test the exact string match for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002710 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002711 response's status code is exactly this string. If the
2712 "status" keyword is prefixed with "!", then the response
2713 will be considered invalid if the status code matches.
2714
2715 rstatus <regex> : test a regular expression for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002716 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002717 response's status code matches the expression. If the
2718 "rstatus" keyword is prefixed with "!", then the response
2719 will be considered invalid if the status code matches.
2720 This is mostly used to check for multiple codes.
2721
2722 string <string> : test the exact string match in the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002723 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002724 response's body contains this exact string. If the
2725 "string" keyword is prefixed with "!", then the response
2726 will be considered invalid if the body contains this
2727 string. This can be used to look for a mandatory word at
2728 the end of a dynamic page, or to detect a failure when a
2729 specific error appears on the check page (eg: a stack
2730 trace).
2731
2732 rstring <regex> : test a regular expression on the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002733 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002734 response's body matches this expression. If the "rstring"
2735 keyword is prefixed with "!", then the response will be
2736 considered invalid if the body matches the expression.
2737 This can be used to look for a mandatory word at the end
2738 of a dynamic page, or to detect a failure when a specific
2739 error appears on the check page (eg: a stack trace).
2740
2741 It is important to note that the responses will be limited to a certain size
2742 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
2743 Thus, too large responses may not contain the mandatory pattern when using
2744 "string" or "rstring". If a large response is absolutely required, it is
2745 possible to change the default max size by setting the global variable.
2746 However, it is worth keeping in mind that parsing very large responses can
2747 waste some CPU cycles, especially when regular expressions are used, and that
2748 it is always better to focus the checks on smaller resources.
2749
2750 Last, if "http-check expect" is combined with "http-check disable-on-404",
2751 then this last one has precedence when the server responds with 404.
2752
2753 Examples :
2754 # only accept status 200 as valid
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002755 http-check expect status 200
Willy Tarreaubd741542010-03-16 18:46:54 +01002756
2757 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002758 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01002759
2760 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002761 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01002762
2763 # check that we have a correct hexadecimal tag before /html
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002764 http-check expect rstring <!--tag:[0-9a-f]*</html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01002765
Willy Tarreaubd741542010-03-16 18:46:54 +01002766 See also : "option httpchk", "http-check disable-on-404"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002767
2768
Willy Tarreauef781042010-01-27 11:53:01 +01002769http-check send-state
2770 Enable emission of a state header with HTTP health checks
2771 May be used in sections : defaults | frontend | listen | backend
2772 yes | no | yes | yes
2773 Arguments : none
2774
2775 When this option is set, haproxy will systematically send a special header
2776 "X-Haproxy-Server-State" with a list of parameters indicating to each server
2777 how they are seen by haproxy. This can be used for instance when a server is
2778 manipulated without access to haproxy and the operator needs to know whether
2779 haproxy still sees it up or not, or if the server is the last one in a farm.
2780
2781 The header is composed of fields delimited by semi-colons, the first of which
2782 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
2783 checks on the total number before transition, just as appears in the stats
2784 interface. Next headers are in the form "<variable>=<value>", indicating in
2785 no specific order some values available in the stats interface :
2786 - a variable "name", containing the name of the backend followed by a slash
2787 ("/") then the name of the server. This can be used when a server is
2788 checked in multiple backends.
2789
2790 - a variable "node" containing the name of the haproxy node, as set in the
2791 global "node" variable, otherwise the system's hostname if unspecified.
2792
2793 - a variable "weight" indicating the weight of the server, a slash ("/")
2794 and the total weight of the farm (just counting usable servers). This
2795 helps to know if other servers are available to handle the load when this
2796 one fails.
2797
2798 - a variable "scur" indicating the current number of concurrent connections
2799 on the server, followed by a slash ("/") then the total number of
2800 connections on all servers of the same backend.
2801
2802 - a variable "qcur" indicating the current number of requests in the
2803 server's queue.
2804
2805 Example of a header received by the application server :
2806 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
2807 scur=13/22; qcur=0
2808
2809 See also : "option httpchk", "http-check disable-on-404"
2810
Willy Tarreauccbcc372012-12-27 12:37:57 +01002811http-request { allow | deny | tarpit | auth [realm <realm>] | redirect <rule> |
Willy Tarreauf4c43c12013-06-11 17:01:13 +02002812 add-header <name> <fmt> | set-header <name> <fmt> |
Willy Tarreau51347ed2013-06-11 19:34:13 +02002813 set-nice <nice> | set-log-level <level> | set-tos <tos> |
2814 set-mark <mark> }
Cyril Bontéf0c60612010-02-06 14:44:47 +01002815 [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002816 Access control for Layer 7 requests
2817
2818 May be used in sections: defaults | frontend | listen | backend
2819 no | yes | yes | yes
2820
Willy Tarreau20b0de52012-12-24 15:45:22 +01002821 The http-request statement defines a set of rules which apply to layer 7
2822 processing. The rules are evaluated in their declaration order when they are
2823 met in a frontend, listen or backend section. Any rule may optionally be
2824 followed by an ACL-based condition, in which case it will only be evaluated
2825 if the condition is true.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002826
Willy Tarreau20b0de52012-12-24 15:45:22 +01002827 The first keyword is the rule's action. Currently supported actions include :
2828 - "allow" : this stops the evaluation of the rules and lets the request
2829 pass the check. No further "http-request" rules are evaluated.
2830
2831 - "deny" : this stops the evaluation of the rules and immediately rejects
2832 the request and emits an HTTP 403 error. No further "http-request" rules
2833 are evaluated.
2834
Willy Tarreauccbcc372012-12-27 12:37:57 +01002835 - "tarpit" : this stops the evaluation of the rules and immediately blocks
2836 the request without responding for a delay specified by "timeout tarpit"
2837 or "timeout connect" if the former is not set. After that delay, if the
2838 client is still connected, an HTTP error 500 is returned so that the
2839 client does not suspect it has been tarpitted. Logs will report the flags
2840 "PT". The goal of the tarpit rule is to slow down robots during an attack
2841 when they're limited on the number of concurrent requests. It can be very
2842 efficient against very dumb robots, and will significantly reduce the
2843 load on firewalls compared to a "deny" rule. But when facing "correctly"
2844 developped robots, it can make things worse by forcing haproxy and the
2845 front firewall to support insane number of concurrent connections.
2846
Willy Tarreau20b0de52012-12-24 15:45:22 +01002847 - "auth" : this stops the evaluation of the rules and immediately responds
2848 with an HTTP 401 or 407 error code to invite the user to present a valid
2849 user name and password. No further "http-request" rules are evaluated. An
2850 optional "realm" parameter is supported, it sets the authentication realm
2851 that is returned with the response (typically the application's name).
2852
Willy Tarreau81499eb2012-12-27 12:19:02 +01002853 - "redirect" : this performs an HTTP redirection based on a redirect rule.
2854 This is exactly the same as the "redirect" statement except that it
2855 inserts a redirect rule which can be processed in the middle of other
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01002856 "http-request" rules and that these rules use the "log-format" strings.
2857 See the "redirect" keyword for the rule's syntax.
Willy Tarreau81499eb2012-12-27 12:19:02 +01002858
Willy Tarreau20b0de52012-12-24 15:45:22 +01002859 - "add-header" appends an HTTP header field whose name is specified in
2860 <name> and whose value is defined by <fmt> which follows the log-format
2861 rules (see Custom Log Format in section 8.2.4). This is particularly
2862 useful to pass connection-specific information to the server (eg: the
2863 client's SSL certificate), or to combine several headers into one. This
2864 rule is not final, so it is possible to add other similar rules. Note
2865 that header addition is performed immediately, so one rule might reuse
2866 the resulting header from a previous rule.
2867
2868 - "set-header" does the same as "add-header" except that the header name
2869 is first removed if it existed. This is useful when passing security
2870 information to the server, where the header must not be manipulated by
2871 external users.
2872
Willy Tarreauf4c43c12013-06-11 17:01:13 +02002873 - "set-nice" sets the "nice" factor of the current request being processed.
2874 It only has effect against the other requests being processed at the same
2875 time. The default value is 0, unless altered by the "nice" setting on the
2876 "bind" line. The accepted range is -1024..1024. The higher the value, the
2877 nicest the request will be. Lower values will make the request more
2878 important than other ones. This can be useful to improve the speed of
2879 some requests, or lower the priority of non-important requests. Using
2880 this setting without prior experimentation can cause some major slowdown.
2881
Willy Tarreau9a355ec2013-06-11 17:45:46 +02002882 - "set-log-level" is used to change the log level of the current request
2883 when a certain condition is met. Valid levels are the 8 syslog levels
2884 (see the "log" keyword) plus the special level "silent" which disables
2885 logging for this request. This rule is not final so the last matching
2886 rule wins. This rule can be useful to disable health checks coming from
2887 another equipment.
2888
Willy Tarreau42cf39e2013-06-11 18:51:32 +02002889 - "set-tos" is used to set the TOS or DSCP field value of packets sent to
2890 the client to the value passed in <tos> on platforms which support this.
2891 This value represents the whole 8 bits of the IP TOS field, and can be
2892 expressed both in decimal or hexadecimal format (prefixed by "0x"). Note
2893 that only the 6 higher bits are used in DSCP or TOS, and the two lower
2894 bits are always 0. This can be used to adjust some routing behaviour on
2895 border routers based on some information from the request. See RFC 2474,
2896 2597, 3260 and 4594 for more information.
2897
Willy Tarreau51347ed2013-06-11 19:34:13 +02002898 - "set-mark" is used to set the Netfilter MARK on all packets sent to the
2899 client to the value passed in <mark> on platforms which support it. This
2900 value is an unsigned 32 bit value which can be matched by netfilter and
2901 by the routing table. It can be expressed both in decimal or hexadecimal
2902 format (prefixed by "0x"). This can be useful to force certain packets to
2903 take a different route (for example a cheaper network path for bulk
2904 downloads). This works on Linux kernels 2.6.32 and above and requires
2905 admin privileges.
2906
Willy Tarreau20b0de52012-12-24 15:45:22 +01002907 There is no limit to the number of http-request statements per instance.
2908
2909 It is important to know that http-request rules are processed very early in
2910 the HTTP processing, just after "block" rules and before "reqdel" or "reqrep"
2911 rules. That way, headers added by "add-header"/"set-header" are visible by
2912 almost all further ACL rules.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002913
2914 Example:
Cyril Bonté78caf842010-03-10 22:41:43 +01002915 acl nagios src 192.168.129.3
2916 acl local_net src 192.168.0.0/16
2917 acl auth_ok http_auth(L1)
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002918
Cyril Bonté78caf842010-03-10 22:41:43 +01002919 http-request allow if nagios
2920 http-request allow if local_net auth_ok
2921 http-request auth realm Gimme if local_net auth_ok
2922 http-request deny
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002923
Cyril Bonté78caf842010-03-10 22:41:43 +01002924 Example:
2925 acl auth_ok http_auth_group(L1) G1
Cyril Bonté78caf842010-03-10 22:41:43 +01002926 http-request auth unless auth_ok
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002927
Willy Tarreau20b0de52012-12-24 15:45:22 +01002928 Example:
2929 http-request set-header X-Haproxy-Current-Date %T
2930 http-request set-header X-SSL %[ssl_fc]
2931 http-request set-header X-SSL-Session_ID %[ssl_fc_session_id]
2932 http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
2933 http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
2934 http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
2935 http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
2936 http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
2937 http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
2938
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002939 See also : "stats http-request", section 3.4 about userlists and section 7
2940 about ACL usage.
Willy Tarreauef781042010-01-27 11:53:01 +01002941
Willy Tarreauf4c43c12013-06-11 17:01:13 +02002942http-response { allow | deny | add-header <name> <fmt> | set-nice <nice> |
Willy Tarreau51347ed2013-06-11 19:34:13 +02002943 set-header <name> <fmt> | set-log-level <level> |
Lukas Tribus2dd1d1a2013-06-19 23:34:41 +02002944 set-mark <mark> | set-tos <tos> }
2945 [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02002946 Access control for Layer 7 responses
2947
2948 May be used in sections: defaults | frontend | listen | backend
2949 no | yes | yes | yes
2950
2951 The http-response statement defines a set of rules which apply to layer 7
2952 processing. The rules are evaluated in their declaration order when they are
2953 met in a frontend, listen or backend section. Any rule may optionally be
2954 followed by an ACL-based condition, in which case it will only be evaluated
2955 if the condition is true. Since these rules apply on responses, the backend
2956 rules are applied first, followed by the frontend's rules.
2957
2958 The first keyword is the rule's action. Currently supported actions include :
2959 - "allow" : this stops the evaluation of the rules and lets the response
2960 pass the check. No further "http-response" rules are evaluated for the
2961 current section.
2962
2963 - "deny" : this stops the evaluation of the rules and immediately rejects
2964 the response and emits an HTTP 502 error. No further "http-response"
2965 rules are evaluated.
2966
2967 - "add-header" appends an HTTP header field whose name is specified in
2968 <name> and whose value is defined by <fmt> which follows the log-format
2969 rules (see Custom Log Format in section 8.2.4). This may be used to send
2970 a cookie to a client for example, or to pass some internal information.
2971 This rule is not final, so it is possible to add other similar rules.
2972 Note that header addition is performed immediately, so one rule might
2973 reuse the resulting header from a previous rule.
2974
2975 - "set-header" does the same as "add-header" except that the header name
2976 is first removed if it existed. This is useful when passing security
2977 information to the server, where the header must not be manipulated by
2978 external users.
2979
Willy Tarreauf4c43c12013-06-11 17:01:13 +02002980 - "set-nice" sets the "nice" factor of the current request being processed.
2981 It only has effect against the other requests being processed at the same
2982 time. The default value is 0, unless altered by the "nice" setting on the
2983 "bind" line. The accepted range is -1024..1024. The higher the value, the
2984 nicest the request will be. Lower values will make the request more
2985 important than other ones. This can be useful to improve the speed of
2986 some requests, or lower the priority of non-important requests. Using
2987 this setting without prior experimentation can cause some major slowdown.
2988
Willy Tarreau9a355ec2013-06-11 17:45:46 +02002989 - "set-log-level" is used to change the log level of the current request
2990 when a certain condition is met. Valid levels are the 8 syslog levels
2991 (see the "log" keyword) plus the special level "silent" which disables
2992 logging for this request. This rule is not final so the last matching
2993 rule wins. This rule can be useful to disable health checks coming from
2994 another equipment.
2995
Willy Tarreau42cf39e2013-06-11 18:51:32 +02002996 - "set-tos" is used to set the TOS or DSCP field value of packets sent to
2997 the client to the value passed in <tos> on platforms which support this.
2998 This value represents the whole 8 bits of the IP TOS field, and can be
2999 expressed both in decimal or hexadecimal format (prefixed by "0x"). Note
3000 that only the 6 higher bits are used in DSCP or TOS, and the two lower
3001 bits are always 0. This can be used to adjust some routing behaviour on
3002 border routers based on some information from the request. See RFC 2474,
3003 2597, 3260 and 4594 for more information.
3004
Willy Tarreau51347ed2013-06-11 19:34:13 +02003005 - "set-mark" is used to set the Netfilter MARK on all packets sent to the
3006 client to the value passed in <mark> on platforms which support it. This
3007 value is an unsigned 32 bit value which can be matched by netfilter and
3008 by the routing table. It can be expressed both in decimal or hexadecimal
3009 format (prefixed by "0x"). This can be useful to force certain packets to
3010 take a different route (for example a cheaper network path for bulk
3011 downloads). This works on Linux kernels 2.6.32 and above and requires
3012 admin privileges.
3013
Willy Tarreaue365c0b2013-06-11 16:06:12 +02003014 There is no limit to the number of http-response statements per instance.
3015
Godbach09250262013-07-02 01:19:15 +08003016 It is important to know that http-response rules are processed very early in
Willy Tarreaue365c0b2013-06-11 16:06:12 +02003017 the HTTP processing, before "reqdel" or "reqrep" rules. That way, headers
3018 added by "add-header"/"set-header" are visible by almost all further ACL
3019 rules.
3020
3021 See also : "http-request", section 3.4 about userlists and section 7 about
3022 ACL usage.
3023
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02003024
Baptiste Assmann69e273f2013-12-11 00:52:19 +01003025tcp-check connect [params*]
3026 Opens a new connection
3027 May be used in sections: defaults | frontend | listen | backend
3028 no | no | yes | yes
3029
3030 When an application lies on more than a single TCP port or when HAProxy
3031 load-balance many services in a single backend, it makes sense to probe all
3032 the services individually before considering a server as operational.
3033
3034 When there are no TCP port configured on the server line neither server port
3035 directive, then the 'tcp-check connect port <port>' must be the first step
3036 of the sequence.
3037
3038 In a tcp-check ruleset a 'connect' is required, it is also mandatory to start
3039 the ruleset with a 'connect' rule. Purpose is to ensure admin know what they
3040 do.
3041
3042 Parameters :
3043 They are optional and can be used to describe how HAProxy should open and
3044 use the TCP connection.
3045
3046 port if not set, check port or server port is used.
3047 It tells HAProxy where to open the connection to.
3048 <port> must be a valid TCP port source integer, from 1 to 65535.
3049
3050 send-proxy send a PROXY protocol string
3051
3052 ssl opens a ciphered connection
3053
3054 Examples:
3055 # check HTTP and HTTPs services on a server.
3056 # first open port 80 thanks to server line port directive, then
3057 # tcp-check opens port 443, ciphered and run a request on it:
3058 option tcp-check
3059 tcp-check connect
3060 tcp-check send GET\ /\ HTTP/1.0\r\n
3061 tcp-check send Host:\ haproxy.1wt.eu\r\n
3062 tcp-check send \r\n
3063 tcp-check expect rstring (2..|3..)
3064 tcp-check connect port 443 ssl
3065 tcp-check send GET\ /\ HTTP/1.0\r\n
3066 tcp-check send Host:\ haproxy.1wt.eu\r\n
3067 tcp-check send \r\n
3068 tcp-check expect rstring (2..|3..)
3069 server www 10.0.0.1 check port 80
3070
3071 # check both POP and IMAP from a single server:
3072 option tcp-check
3073 tcp-check connect port 110
3074 tcp-check expect string +OK\ POP3\ ready
3075 tcp-check connect port 143
3076 tcp-check expect string *\ OK\ IMAP4\ ready
3077 server mail 10.0.0.1 check
3078
3079 See also : "option tcp-check", "tcp-check send", "tcp-check expect"
3080
3081
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02003082tcp-check expect [!] <match> <pattern>
3083 Specify data to be collected and analysed during a generic health check
3084 May be used in sections: defaults | frontend | listen | backend
3085 no | no | yes | yes
3086
3087 Arguments :
3088 <match> is a keyword indicating how to look for a specific pattern in the
3089 response. The keyword may be one of "string", "rstring" or
3090 binary.
3091 The keyword may be preceded by an exclamation mark ("!") to negate
3092 the match. Spaces are allowed between the exclamation mark and the
3093 keyword. See below for more details on the supported keywords.
3094
3095 <pattern> is the pattern to look for. It may be a string or a regular
3096 expression. If the pattern contains spaces, they must be escaped
3097 with the usual backslash ('\').
3098 If the match is set to binary, then the pattern must be passed as
3099 a serie of hexadecimal digits in an even number. Each sequence of
3100 two digits will represent a byte. The hexadecimal digits may be
3101 used upper or lower case.
3102
3103
3104 The available matches are intentionally similar to their http-check cousins :
3105
3106 string <string> : test the exact string matches in the response buffer.
3107 A health check response will be considered valid if the
3108 response's buffer contains this exact string. If the
3109 "string" keyword is prefixed with "!", then the response
3110 will be considered invalid if the body contains this
3111 string. This can be used to look for a mandatory pattern
3112 in a protocol response, or to detect a failure when a
3113 specific error appears in a protocol banner.
3114
3115 rstring <regex> : test a regular expression on the response buffer.
3116 A health check response will be considered valid if the
3117 response's buffer matches this expression. If the
3118 "rstring" keyword is prefixed with "!", then the response
3119 will be considered invalid if the body matches the
3120 expression.
3121
3122 binary <hexstring> : test the exact string in its hexadecimal form matches
3123 in the response buffer. A health check response will
3124 be considered valid if the response's buffer contains
3125 this exact hexadecimal string.
3126 Purpose is to match data on binary protocols.
3127
3128 It is important to note that the responses will be limited to a certain size
3129 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
3130 Thus, too large responses may not contain the mandatory pattern when using
3131 "string", "rstring" or binary. If a large response is absolutely required, it
3132 is possible to change the default max size by setting the global variable.
3133 However, it is worth keeping in mind that parsing very large responses can
3134 waste some CPU cycles, especially when regular expressions are used, and that
3135 it is always better to focus the checks on smaller resources. Also, in its
3136 current state, the check will not find any string nor regex past a null
3137 character in the response. Similarly it is not possible to request matching
3138 the null character.
3139
3140 Examples :
3141 # perform a POP check
3142 option tcp-check
3143 tcp-check expect string +OK\ POP3\ ready
3144
3145 # perform an IMAP check
3146 option tcp-check
3147 tcp-check expect string *\ OK\ IMAP4\ ready
3148
3149 # look for the redis master server
3150 option tcp-check
3151 tcp-check send PING\r\n
3152 tcp-check expect +PONG
3153 tcp-check send info\ replication\r\n
3154 tcp-check expect string role:master
3155 tcp-check send QUIT\r\n
3156 tcp-check expect string +OK
3157
3158
Baptiste Assmann69e273f2013-12-11 00:52:19 +01003159 See also : "option tcp-check", "tcp-check connect", "tcp-check send",
3160 "tcp-check send-binary", "http-check expect", tune.chksize
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02003161
3162
3163tcp-check send <data>
3164 Specify a string to be sent as a question during a generic health check
3165 May be used in sections: defaults | frontend | listen | backend
3166 no | no | yes | yes
3167
3168 <data> : the data to be sent as a question during a generic health check
3169 session. For now, <data> must be a string.
3170
3171 Examples :
3172 # look for the redis master server
3173 option tcp-check
3174 tcp-check send info\ replication\r\n
3175 tcp-check expect string role:master
3176
Baptiste Assmann69e273f2013-12-11 00:52:19 +01003177 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
3178 "tcp-check send-binary", tune.chksize
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02003179
3180
3181tcp-check send-binary <hexastring>
3182 Specify an hexa digits string to be sent as a binary question during a raw
3183 tcp health check
3184 May be used in sections: defaults | frontend | listen | backend
3185 no | no | yes | yes
3186
3187 <data> : the data to be sent as a question during a generic health check
3188 session. For now, <data> must be a string.
3189 <hexastring> : test the exact string in its hexadecimal form matches in the
3190 response buffer. A health check response will be considered
3191 valid if the response's buffer contains this exact
3192 hexadecimal string.
3193 Purpose is to send binary data to ask on binary protocols.
3194
3195 Examples :
3196 # redis check in binary
3197 option tcp-check
3198 tcp-check send-binary 50494e470d0a # PING\r\n
3199 tcp-check expect binary 2b504F4e47 # +PONG
3200
3201
Baptiste Assmann69e273f2013-12-11 00:52:19 +01003202 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
3203 "tcp-check send", tune.chksize
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02003204
3205
Mark Lamourinec2247f02012-01-04 13:02:01 -05003206http-send-name-header [<header>]
3207 Add the server name to a request. Use the header string given by <header>
3208
3209 May be used in sections: defaults | frontend | listen | backend
3210 yes | no | yes | yes
3211
3212 Arguments :
3213
3214 <header> The header string to use to send the server name
3215
3216 The "http-send-name-header" statement causes the name of the target
3217 server to be added to the headers of an HTTP request. The name
3218 is added with the header string proved.
3219
3220 See also : "server"
3221
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01003222id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02003223 Set a persistent ID to a proxy.
3224 May be used in sections : defaults | frontend | listen | backend
3225 no | yes | yes | yes
3226 Arguments : none
3227
3228 Set a persistent ID for the proxy. This ID must be unique and positive.
3229 An unused ID will automatically be assigned if unset. The first assigned
3230 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01003231
3232
Cyril Bonté0d4bf012010-04-25 23:21:46 +02003233ignore-persist { if | unless } <condition>
3234 Declare a condition to ignore persistence
3235 May be used in sections: defaults | frontend | listen | backend
3236 no | yes | yes | yes
3237
3238 By default, when cookie persistence is enabled, every requests containing
3239 the cookie are unconditionally persistent (assuming the target server is up
3240 and running).
3241
3242 The "ignore-persist" statement allows one to declare various ACL-based
3243 conditions which, when met, will cause a request to ignore persistence.
3244 This is sometimes useful to load balance requests for static files, which
3245 oftenly don't require persistence. This can also be used to fully disable
3246 persistence for a specific User-Agent (for example, some web crawler bots).
3247
3248 Combined with "appsession", it can also help reduce HAProxy memory usage, as
3249 the appsession table won't grow if persistence is ignored.
3250
3251 The persistence is ignored when an "if" condition is met, or unless an
3252 "unless" condition is met.
3253
3254 See also : "force-persist", "cookie", and section 7 about ACL usage.
3255
3256
Willy Tarreau2769aa02007-12-27 18:26:09 +01003257log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02003258log <address> <facility> [<level> [<minlevel>]]
William Lallemand0f99e342011-10-12 17:50:54 +02003259no log
Willy Tarreau2769aa02007-12-27 18:26:09 +01003260 Enable per-instance logging of events and traffic.
3261 May be used in sections : defaults | frontend | listen | backend
3262 yes | yes | yes | yes
William Lallemand0f99e342011-10-12 17:50:54 +02003263
3264 Prefix :
3265 no should be used when the logger list must be flushed. For example,
3266 if you don't want to inherit from the default logger list. This
3267 prefix does not allow arguments.
3268
Willy Tarreau2769aa02007-12-27 18:26:09 +01003269 Arguments :
3270 global should be used when the instance's logging parameters are the
3271 same as the global ones. This is the most common usage. "global"
3272 replaces <address>, <facility> and <level> with those of the log
3273 entries found in the "global" section. Only one "log global"
3274 statement may be used per instance, and this form takes no other
3275 parameter.
3276
3277 <address> indicates where to send the logs. It takes the same format as
3278 for the "global" section's logs, and can be one of :
3279
3280 - An IPv4 address optionally followed by a colon (':') and a UDP
3281 port. If no port is specified, 514 is used by default (the
3282 standard syslog port).
3283
David du Colombier24bb5f52011-03-17 10:40:23 +01003284 - An IPv6 address followed by a colon (':') and optionally a UDP
3285 port. If no port is specified, 514 is used by default (the
3286 standard syslog port).
3287
Willy Tarreau2769aa02007-12-27 18:26:09 +01003288 - A filesystem path to a UNIX domain socket, keeping in mind
3289 considerations for chroot (be sure the path is accessible
3290 inside the chroot) and uid/gid (be sure the path is
3291 appropriately writeable).
3292
Willy Tarreaudad36a32013-03-11 01:20:04 +01003293 Any part of the address string may reference any number of
3294 environment variables by preceding their name with a dollar
3295 sign ('$') and optionally enclosing them with braces ('{}'),
3296 similarly to what is done in Bourne shell.
3297
Willy Tarreau2769aa02007-12-27 18:26:09 +01003298 <facility> must be one of the 24 standard syslog facilities :
3299
3300 kern user mail daemon auth syslog lpr news
3301 uucp cron auth2 ftp ntp audit alert cron2
3302 local0 local1 local2 local3 local4 local5 local6 local7
3303
3304 <level> is optional and can be specified to filter outgoing messages. By
3305 default, all messages are sent. If a level is specified, only
3306 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02003307 will be sent. An optional minimum level can be specified. If it
3308 is set, logs emitted with a more severe level than this one will
3309 be capped to this level. This is used to avoid sending "emerg"
3310 messages on all terminals on some default syslog configurations.
3311 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01003312
3313 emerg alert crit err warning notice info debug
3314
William Lallemand0f99e342011-10-12 17:50:54 +02003315 It is important to keep in mind that it is the frontend which decides what to
3316 log from a connection, and that in case of content switching, the log entries
3317 from the backend will be ignored. Connections are logged at level "info".
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003318
3319 However, backend log declaration define how and where servers status changes
3320 will be logged. Level "notice" will be used to indicate a server going up,
3321 "warning" will be used for termination signals and definitive service
3322 termination, and "alert" will be used for when a server goes down.
3323
3324 Note : According to RFC3164, messages are truncated to 1024 bytes before
3325 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003326
3327 Example :
3328 log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02003329 log 127.0.0.1:514 local0 notice # only send important events
3330 log 127.0.0.1:514 local0 notice notice # same but limit output level
Willy Tarreaudad36a32013-03-11 01:20:04 +01003331 log ${LOCAL_SYSLOG}:514 local0 notice # send to local server
3332
Willy Tarreau2769aa02007-12-27 18:26:09 +01003333
William Lallemand48940402012-01-30 16:47:22 +01003334log-format <string>
3335 Allows you to custom a log line.
3336
3337 See also : Custom Log Format (8.2.4)
3338
Willy Tarreau2769aa02007-12-27 18:26:09 +01003339
3340maxconn <conns>
3341 Fix the maximum number of concurrent connections on a frontend
3342 May be used in sections : defaults | frontend | listen | backend
3343 yes | yes | yes | no
3344 Arguments :
3345 <conns> is the maximum number of concurrent connections the frontend will
3346 accept to serve. Excess connections will be queued by the system
3347 in the socket's listen queue and will be served once a connection
3348 closes.
3349
3350 If the system supports it, it can be useful on big sites to raise this limit
3351 very high so that haproxy manages connection queues, instead of leaving the
3352 clients with unanswered connection attempts. This value should not exceed the
3353 global maxconn. Also, keep in mind that a connection contains two buffers
3354 of 8kB each, as well as some other data resulting in about 17 kB of RAM being
3355 consumed per established connection. That means that a medium system equipped
3356 with 1GB of RAM can withstand around 40000-50000 concurrent connections if
3357 properly tuned.
3358
3359 Also, when <conns> is set to large values, it is possible that the servers
3360 are not sized to accept such loads, and for this reason it is generally wise
3361 to assign them some reasonable connection limits.
3362
Vincent Bernat6341be52012-06-27 17:18:30 +02003363 By default, this value is set to 2000.
3364
Willy Tarreau2769aa02007-12-27 18:26:09 +01003365 See also : "server", global section's "maxconn", "fullconn"
3366
3367
3368mode { tcp|http|health }
3369 Set the running mode or protocol of the instance
3370 May be used in sections : defaults | frontend | listen | backend
3371 yes | yes | yes | yes
3372 Arguments :
3373 tcp The instance will work in pure TCP mode. A full-duplex connection
3374 will be established between clients and servers, and no layer 7
3375 examination will be performed. This is the default mode. It
3376 should be used for SSL, SSH, SMTP, ...
3377
3378 http The instance will work in HTTP mode. The client request will be
3379 analyzed in depth before connecting to any server. Any request
3380 which is not RFC-compliant will be rejected. Layer 7 filtering,
3381 processing and switching will be possible. This is the mode which
3382 brings HAProxy most of its value.
3383
3384 health The instance will work in "health" mode. It will just reply "OK"
Willy Tarreau82569f92012-09-27 23:48:56 +02003385 to incoming connections and close the connection. Alternatively,
3386 If the "httpchk" option is set, "HTTP/1.0 200 OK" will be sent
3387 instead. Nothing will be logged in either case. This mode is used
3388 to reply to external components health checks. This mode is
3389 deprecated and should not be used anymore as it is possible to do
3390 the same and even better by combining TCP or HTTP modes with the
3391 "monitor" keyword.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003392
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003393 When doing content switching, it is mandatory that the frontend and the
3394 backend are in the same mode (generally HTTP), otherwise the configuration
3395 will be refused.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003396
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003397 Example :
Willy Tarreau2769aa02007-12-27 18:26:09 +01003398 defaults http_instances
3399 mode http
3400
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003401 See also : "monitor", "monitor-net"
Willy Tarreau2769aa02007-12-27 18:26:09 +01003402
Willy Tarreau0ba27502007-12-24 16:55:16 +01003403
Cyril Bontéf0c60612010-02-06 14:44:47 +01003404monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01003405 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003406 May be used in sections : defaults | frontend | listen | backend
3407 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01003408 Arguments :
3409 if <cond> the monitor request will fail if the condition is satisfied,
3410 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003411 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01003412 are met, for instance a low number of servers both in a
3413 backend and its backup.
3414
3415 unless <cond> the monitor request will succeed only if the condition is
3416 satisfied, and will fail otherwise. Such a condition may be
3417 based on a test on the presence of a minimum number of active
3418 servers in a list of backends.
3419
3420 This statement adds a condition which can force the response to a monitor
3421 request to report a failure. By default, when an external component queries
3422 the URI dedicated to monitoring, a 200 response is returned. When one of the
3423 conditions above is met, haproxy will return 503 instead of 200. This is
3424 very useful to report a site failure to an external component which may base
3425 routing advertisements between multiple sites on the availability reported by
3426 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003427 criterion. Note that "monitor fail" only works in HTTP mode. Both status
3428 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003429
3430 Example:
3431 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01003432 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01003433 acl site_dead nbsrv(dynamic) lt 2
3434 acl site_dead nbsrv(static) lt 2
3435 monitor-uri /site_alive
3436 monitor fail if site_dead
3437
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003438 See also : "monitor-net", "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01003439
3440
3441monitor-net <source>
3442 Declare a source network which is limited to monitor requests
3443 May be used in sections : defaults | frontend | listen | backend
3444 yes | yes | yes | no
3445 Arguments :
3446 <source> is the source IPv4 address or network which will only be able to
3447 get monitor responses to any request. It can be either an IPv4
3448 address, a host name, or an address followed by a slash ('/')
3449 followed by a mask.
3450
3451 In TCP mode, any connection coming from a source matching <source> will cause
3452 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003453 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01003454 forwarding the connection to a remote server.
3455
3456 In HTTP mode, a connection coming from a source matching <source> will be
3457 accepted, the following response will be sent without waiting for a request,
3458 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
3459 enough for any front-end HTTP probe to detect that the service is UP and
Willy Tarreau82569f92012-09-27 23:48:56 +02003460 running without forwarding the request to a backend server. Note that this
3461 response is sent in raw format, without any transformation. This is important
3462 as it means that it will not be SSL-encrypted on SSL listeners.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003463
Willy Tarreau82569f92012-09-27 23:48:56 +02003464 Monitor requests are processed very early, just after tcp-request connection
3465 ACLs which are the only ones able to block them. These connections are short
3466 lived and never wait for any data from the client. They cannot be logged, and
3467 it is the intended purpose. They are only used to report HAProxy's health to
3468 an upper component, nothing more. Please note that "monitor fail" rules do
3469 not apply to connections intercepted by "monitor-net".
Willy Tarreau2769aa02007-12-27 18:26:09 +01003470
Willy Tarreau95cd2832010-03-04 23:36:33 +01003471 Last, please note that only one "monitor-net" statement can be specified in
3472 a frontend. If more than one is found, only the last one will be considered.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003473
Willy Tarreau2769aa02007-12-27 18:26:09 +01003474 Example :
3475 # addresses .252 and .253 are just probing us.
3476 frontend www
3477 monitor-net 192.168.0.252/31
3478
3479 See also : "monitor fail", "monitor-uri"
3480
3481
3482monitor-uri <uri>
3483 Intercept a URI used by external components' monitor requests
3484 May be used in sections : defaults | frontend | listen | backend
3485 yes | yes | yes | no
3486 Arguments :
3487 <uri> is the exact URI which we want to intercept to return HAProxy's
3488 health status instead of forwarding the request.
3489
3490 When an HTTP request referencing <uri> will be received on a frontend,
3491 HAProxy will not forward it nor log it, but instead will return either
3492 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
3493 conditions defined with "monitor fail". This is normally enough for any
3494 front-end HTTP probe to detect that the service is UP and running without
3495 forwarding the request to a backend server. Note that the HTTP method, the
3496 version and all headers are ignored, but the request must at least be valid
3497 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
3498
3499 Monitor requests are processed very early. It is not possible to block nor
3500 divert them using ACLs. They cannot be logged either, and it is the intended
3501 purpose. They are only used to report HAProxy's health to an upper component,
3502 nothing more. However, it is possible to add any number of conditions using
3503 "monitor fail" and ACLs so that the result can be adjusted to whatever check
3504 can be imagined (most often the number of available servers in a backend).
3505
3506 Example :
3507 # Use /haproxy_test to report haproxy's status
3508 frontend www
3509 mode http
3510 monitor-uri /haproxy_test
3511
3512 See also : "monitor fail", "monitor-net"
3513
Willy Tarreau0ba27502007-12-24 16:55:16 +01003514
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003515option abortonclose
3516no option abortonclose
3517 Enable or disable early dropping of aborted requests pending in queues.
3518 May be used in sections : defaults | frontend | listen | backend
3519 yes | no | yes | yes
3520 Arguments : none
3521
3522 In presence of very high loads, the servers will take some time to respond.
3523 The per-instance connection queue will inflate, and the response time will
3524 increase respective to the size of the queue times the average per-session
3525 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01003526 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003527 the queue, and slowing down other users, and the servers as well, because the
3528 request will eventually be served, then aborted at the first error
3529 encountered while delivering the response.
3530
3531 As there is no way to distinguish between a full STOP and a simple output
3532 close on the client side, HTTP agents should be conservative and consider
3533 that the client might only have closed its output channel while waiting for
3534 the response. However, this introduces risks of congestion when lots of users
3535 do the same, and is completely useless nowadays because probably no client at
3536 all will close the session while waiting for the response. Some HTTP agents
Willy Tarreaud72758d2010-01-12 10:42:19 +01003537 support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003538 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01003539 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003540 of being the single component to break rare but valid traffic is extremely
3541 low, which adds to the temptation to be able to abort a session early while
3542 still not served and not pollute the servers.
3543
3544 In HAProxy, the user can choose the desired behaviour using the option
3545 "abortonclose". By default (without the option) the behaviour is HTTP
3546 compliant and aborted requests will be served. But when the option is
3547 specified, a session with an incoming channel closed will be aborted while
3548 it is still possible, either pending in the queue for a connection slot, or
3549 during the connection establishment if the server has not yet acknowledged
3550 the connection request. This considerably reduces the queue size and the load
3551 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01003552 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003553
3554 If this option has been enabled in a "defaults" section, it can be disabled
3555 in a specific instance by prepending the "no" keyword before it.
3556
3557 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
3558
3559
Willy Tarreau4076a152009-04-02 15:18:36 +02003560option accept-invalid-http-request
3561no option accept-invalid-http-request
3562 Enable or disable relaxing of HTTP request parsing
3563 May be used in sections : defaults | frontend | listen | backend
3564 yes | yes | yes | no
3565 Arguments : none
3566
3567 By default, HAProxy complies with RFC2616 in terms of message parsing. This
3568 means that invalid characters in header names are not permitted and cause an
3569 error to be returned to the client. This is the desired behaviour as such
3570 forbidden characters are essentially used to build attacks exploiting server
3571 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
3572 server will emit invalid header names for whatever reason (configuration,
3573 implementation) and the issue will not be immediately fixed. In such a case,
3574 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau422246e2012-01-07 23:54:13 +01003575 even if that does not make sense, by specifying this option. Similarly, the
3576 list of characters allowed to appear in a URI is well defined by RFC3986, and
3577 chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
3578 ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
3579 not allowed at all. Haproxy always blocks a number of them (0..32, 127). The
3580 remaining ones are blocked by default unless this option is enabled.
Willy Tarreau4076a152009-04-02 15:18:36 +02003581
3582 This option should never be enabled by default as it hides application bugs
3583 and open security breaches. It should only be deployed after a problem has
3584 been confirmed.
3585
3586 When this option is enabled, erroneous header names will still be accepted in
3587 requests, but the complete request will be captured in order to permit later
Willy Tarreau422246e2012-01-07 23:54:13 +01003588 analysis using the "show errors" request on the UNIX stats socket. Similarly,
3589 requests containing invalid chars in the URI part will be logged. Doing this
Willy Tarreau4076a152009-04-02 15:18:36 +02003590 also helps confirming that the issue has been solved.
3591
3592 If this option has been enabled in a "defaults" section, it can be disabled
3593 in a specific instance by prepending the "no" keyword before it.
3594
3595 See also : "option accept-invalid-http-response" and "show errors" on the
3596 stats socket.
3597
3598
3599option accept-invalid-http-response
3600no option accept-invalid-http-response
3601 Enable or disable relaxing of HTTP response parsing
3602 May be used in sections : defaults | frontend | listen | backend
3603 yes | no | yes | yes
3604 Arguments : none
3605
3606 By default, HAProxy complies with RFC2616 in terms of message parsing. This
3607 means that invalid characters in header names are not permitted and cause an
3608 error to be returned to the client. This is the desired behaviour as such
3609 forbidden characters are essentially used to build attacks exploiting server
3610 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
3611 server will emit invalid header names for whatever reason (configuration,
3612 implementation) and the issue will not be immediately fixed. In such a case,
3613 it is possible to relax HAProxy's header name parser to accept any character
3614 even if that does not make sense, by specifying this option.
3615
3616 This option should never be enabled by default as it hides application bugs
3617 and open security breaches. It should only be deployed after a problem has
3618 been confirmed.
3619
3620 When this option is enabled, erroneous header names will still be accepted in
3621 responses, but the complete response will be captured in order to permit
3622 later analysis using the "show errors" request on the UNIX stats socket.
3623 Doing this also helps confirming that the issue has been solved.
3624
3625 If this option has been enabled in a "defaults" section, it can be disabled
3626 in a specific instance by prepending the "no" keyword before it.
3627
3628 See also : "option accept-invalid-http-request" and "show errors" on the
3629 stats socket.
3630
3631
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003632option allbackups
3633no option allbackups
3634 Use either all backup servers at a time or only the first one
3635 May be used in sections : defaults | frontend | listen | backend
3636 yes | no | yes | yes
3637 Arguments : none
3638
3639 By default, the first operational backup server gets all traffic when normal
3640 servers are all down. Sometimes, it may be preferred to use multiple backups
3641 at once, because one will not be enough. When "option allbackups" is enabled,
3642 the load balancing will be performed among all backup servers when all normal
3643 ones are unavailable. The same load balancing algorithm will be used and the
3644 servers' weights will be respected. Thus, there will not be any priority
3645 order between the backup servers anymore.
3646
3647 This option is mostly used with static server farms dedicated to return a
3648 "sorry" page when an application is completely offline.
3649
3650 If this option has been enabled in a "defaults" section, it can be disabled
3651 in a specific instance by prepending the "no" keyword before it.
3652
3653
3654option checkcache
3655no option checkcache
Godbach7056a352013-12-11 20:01:07 +08003656 Analyze all server responses and block responses with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003657 May be used in sections : defaults | frontend | listen | backend
3658 yes | no | yes | yes
3659 Arguments : none
3660
3661 Some high-level frameworks set application cookies everywhere and do not
3662 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003663 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003664 high risk of session crossing or stealing between users traversing the same
3665 caches. In some situations, it is better to block the response than to let
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02003666 some sensitive session information go in the wild.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003667
3668 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003669 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01003670 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003671 response to check if there's a risk of caching a cookie on a client-side
3672 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01003673 to the client are :
3674 - all those without "Set-Cookie" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003675 - all those with a return code other than 200, 203, 206, 300, 301, 410,
Willy Tarreau198a7442008-01-17 12:05:32 +01003676 provided that the server has not set a "Cache-control: public" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003677 - all those that come from a POST request, provided that the server has not
3678 set a 'Cache-Control: public' header ;
3679 - those with a 'Pragma: no-cache' header
3680 - those with a 'Cache-control: private' header
3681 - those with a 'Cache-control: no-store' header
3682 - those with a 'Cache-control: max-age=0' header
3683 - those with a 'Cache-control: s-maxage=0' header
3684 - those with a 'Cache-control: no-cache' header
3685 - those with a 'Cache-control: no-cache="set-cookie"' header
3686 - those with a 'Cache-control: no-cache="set-cookie,' header
3687 (allowing other fields after set-cookie)
3688
3689 If a response doesn't respect these requirements, then it will be blocked
Willy Tarreau198a7442008-01-17 12:05:32 +01003690 just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003691 The session state shows "PH--" meaning that the proxy blocked the response
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003692 during headers processing. Additionally, an alert will be sent in the logs so
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003693 that admins are informed that there's something to be fixed.
3694
3695 Due to the high impact on the application, the application should be tested
3696 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003697 good practice to always activate it during tests, even if it is not used in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003698 production, as it will report potentially dangerous application behaviours.
3699
3700 If this option has been enabled in a "defaults" section, it can be disabled
3701 in a specific instance by prepending the "no" keyword before it.
3702
3703
3704option clitcpka
3705no option clitcpka
3706 Enable or disable the sending of TCP keepalive packets on the client side
3707 May be used in sections : defaults | frontend | listen | backend
3708 yes | yes | yes | no
3709 Arguments : none
3710
3711 When there is a firewall or any session-aware component between a client and
3712 a server, and when the protocol involves very long sessions with long idle
3713 periods (eg: remote desktops), there is a risk that one of the intermediate
3714 components decides to expire a session which has remained idle for too long.
3715
3716 Enabling socket-level TCP keep-alives makes the system regularly send packets
3717 to the other end of the connection, leaving it active. The delay between
3718 keep-alive probes is controlled by the system only and depends both on the
3719 operating system and its tuning parameters.
3720
3721 It is important to understand that keep-alive packets are neither emitted nor
3722 received at the application level. It is only the network stacks which sees
3723 them. For this reason, even if one side of the proxy already uses keep-alives
3724 to maintain its connection alive, those keep-alive packets will not be
3725 forwarded to the other side of the proxy.
3726
3727 Please note that this has nothing to do with HTTP keep-alive.
3728
3729 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
3730 client side of a connection, which should help when session expirations are
3731 noticed between HAProxy and a client.
3732
3733 If this option has been enabled in a "defaults" section, it can be disabled
3734 in a specific instance by prepending the "no" keyword before it.
3735
3736 See also : "option srvtcpka", "option tcpka"
3737
3738
Willy Tarreau0ba27502007-12-24 16:55:16 +01003739option contstats
3740 Enable continuous traffic statistics updates
3741 May be used in sections : defaults | frontend | listen | backend
3742 yes | yes | yes | no
3743 Arguments : none
3744
3745 By default, counters used for statistics calculation are incremented
3746 only when a session finishes. It works quite well when serving small
3747 objects, but with big ones (for example large images or archives) or
3748 with A/V streaming, a graph generated from haproxy counters looks like
3749 a hedgehog. With this option enabled counters get incremented continuously,
3750 during a whole session. Recounting touches a hotpath directly so
3751 it is not enabled by default, as it has small performance impact (~0.5%).
3752
3753
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003754option dontlog-normal
3755no option dontlog-normal
3756 Enable or disable logging of normal, successful connections
3757 May be used in sections : defaults | frontend | listen | backend
3758 yes | yes | yes | no
3759 Arguments : none
3760
3761 There are large sites dealing with several thousand connections per second
3762 and for which logging is a major pain. Some of them are even forced to turn
3763 logs off and cannot debug production issues. Setting this option ensures that
3764 normal connections, those which experience no error, no timeout, no retry nor
3765 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
3766 mode, the response status code is checked and return codes 5xx will still be
3767 logged.
3768
3769 It is strongly discouraged to use this option as most of the time, the key to
3770 complex issues is in the normal logs which will not be logged here. If you
3771 need to separate logs, see the "log-separate-errors" option instead.
3772
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003773 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003774 logging.
3775
3776
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003777option dontlognull
3778no option dontlognull
3779 Enable or disable logging of null connections
3780 May be used in sections : defaults | frontend | listen | backend
3781 yes | yes | yes | no
3782 Arguments : none
3783
3784 In certain environments, there are components which will regularly connect to
3785 various systems to ensure that they are still alive. It can be the case from
3786 another load balancer as well as from monitoring systems. By default, even a
3787 simple port probe or scan will produce a log. If those connections pollute
3788 the logs too much, it is possible to enable option "dontlognull" to indicate
3789 that a connection on which no data has been transferred will not be logged,
3790 which typically corresponds to those probes.
3791
3792 It is generally recommended not to use this option in uncontrolled
3793 environments (eg: internet), otherwise scans and other malicious activities
3794 would not be logged.
3795
3796 If this option has been enabled in a "defaults" section, it can be disabled
3797 in a specific instance by prepending the "no" keyword before it.
3798
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003799 See also : "log", "monitor-net", "monitor-uri" and section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003800
3801
3802option forceclose
3803no option forceclose
3804 Enable or disable active connection closing after response is transferred.
3805 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaua31e5df2009-12-30 01:10:35 +01003806 yes | yes | yes | yes
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003807 Arguments : none
3808
3809 Some HTTP servers do not necessarily close the connections when they receive
3810 the "Connection: close" set by "option httpclose", and if the client does not
3811 close either, then the connection remains open till the timeout expires. This
3812 causes high number of simultaneous connections on the servers and shows high
3813 global session times in the logs.
3814
3815 When this happens, it is possible to use "option forceclose". It will
Willy Tarreau82eeaf22009-12-29 12:09:05 +01003816 actively close the outgoing server channel as soon as the server has finished
Willy Tarreau02bce8b2014-01-30 00:15:28 +01003817 to respond and release some resources earlier than with 'option httpclose'.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003818
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003819 This option may also be combined with "option http-pretend-keepalive", which
3820 will disable sending of the "Connection: close" header, but will still cause
3821 the connection to be closed once the whole response is received.
3822
Willy Tarreau02bce8b2014-01-30 00:15:28 +01003823 This option disables and replaces any previous 'option httpclose', 'option
Willy Tarreau70dffda2014-01-30 03:07:23 +01003824 http-server-close', 'option http-keep-alive', or "option http-tunnel".
Willy Tarreau02bce8b2014-01-30 00:15:28 +01003825
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003826 If this option has been enabled in a "defaults" section, it can be disabled
3827 in a specific instance by prepending the "no" keyword before it.
3828
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003829 See also : "option httpclose" and "option http-pretend-keepalive"
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003830
3831
Willy Tarreau87cf5142011-08-19 22:57:24 +02003832option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003833 Enable insertion of the X-Forwarded-For header to requests sent to servers
3834 May be used in sections : defaults | frontend | listen | backend
3835 yes | yes | yes | yes
3836 Arguments :
3837 <network> is an optional argument used to disable this option for sources
3838 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02003839 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01003840 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003841
3842 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
3843 their client address. This is sometimes annoying when the client's IP address
3844 is expected in server logs. To solve this problem, the well-known HTTP header
3845 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
3846 This header contains a value representing the client's IP address. Since this
3847 header is always appended at the end of the existing header list, the server
3848 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02003849 the server's manual to find how to enable use of this standard header. Note
3850 that only the last occurrence of the header must be used, since it is really
3851 possible that the client has already brought one.
3852
Willy Tarreaud72758d2010-01-12 10:42:19 +01003853 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02003854 the default "X-Forwarded-For". This can be useful where you might already
Willy Tarreaud72758d2010-01-12 10:42:19 +01003855 have a "X-Forwarded-For" header from a different application (eg: stunnel),
3856 and you need preserve it. Also if your backend server doesn't use the
Ross Westaf72a1d2008-08-03 10:51:45 +02003857 "X-Forwarded-For" header and requires different one (eg: Zeus Web Servers
3858 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01003859
3860 Sometimes, a same HAProxy instance may be shared between a direct client
3861 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
3862 used to decrypt HTTPS traffic). It is possible to disable the addition of the
3863 header for a known source address or network by adding the "except" keyword
3864 followed by the network address. In this case, any source IP matching the
3865 network will not cause an addition of this header. Most common uses are with
3866 private networks or 127.0.0.1.
3867
Willy Tarreau87cf5142011-08-19 22:57:24 +02003868 Alternatively, the keyword "if-none" states that the header will only be
3869 added if it is not present. This should only be used in perfectly trusted
3870 environment, as this might cause a security issue if headers reaching haproxy
3871 are under the control of the end-user.
3872
Willy Tarreauc27debf2008-01-06 08:57:02 +01003873 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02003874 least one of them uses it, the header will be added. Note that the backend's
3875 setting of the header subargument takes precedence over the frontend's if
Willy Tarreau87cf5142011-08-19 22:57:24 +02003876 both are defined. In the case of the "if-none" argument, if at least one of
3877 the frontend or the backend does not specify it, it wants the addition to be
3878 mandatory, so it wins.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003879
Ross Westaf72a1d2008-08-03 10:51:45 +02003880 Examples :
Willy Tarreauc27debf2008-01-06 08:57:02 +01003881 # Public HTTP address also used by stunnel on the same machine
3882 frontend www
3883 mode http
3884 option forwardfor except 127.0.0.1 # stunnel already adds the header
3885
Ross Westaf72a1d2008-08-03 10:51:45 +02003886 # Those servers want the IP Address in X-Client
3887 backend www
3888 mode http
3889 option forwardfor header X-Client
3890
Willy Tarreau87cf5142011-08-19 22:57:24 +02003891 See also : "option httpclose", "option http-server-close",
Willy Tarreau70dffda2014-01-30 03:07:23 +01003892 "option forceclose", "option http-keep-alive"
Willy Tarreauc27debf2008-01-06 08:57:02 +01003893
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003894
Willy Tarreau16bfb022010-01-16 19:48:41 +01003895option http-keep-alive
3896no option http-keep-alive
3897 Enable or disable HTTP keep-alive from client to server
3898 May be used in sections : defaults | frontend | listen | backend
3899 yes | yes | yes | yes
3900 Arguments : none
3901
Willy Tarreau70dffda2014-01-30 03:07:23 +01003902 By default HAProxy operates in keep-alive mode with regards to persistent
3903 connections: for each connection it processes each request and response, and
3904 leaves the connection idle on both sides between the end of a response and the
3905 start of a new request. This mode may be changed by several options such as
3906 "option http-server-close", "option forceclose", "option httpclose" or
3907 "option http-tunnel". This option allows to set back the keep-alive mode,
3908 which can be useful when another mode was used in a defaults section.
3909
3910 Setting "option http-keep-alive" enables HTTP keep-alive mode on the client-
3911 and server- sides. This provides the lowest latency on the client side (slow
Willy Tarreau16bfb022010-01-16 19:48:41 +01003912 network) and the fastest session reuse on the server side at the expense
3913 of maintaining idle connections to the servers. In general, it is possible
3914 with this option to achieve approximately twice the request rate that the
3915 "http-server-close" option achieves on small objects. There are mainly two
3916 situations where this option may be useful :
3917
3918 - when the server is non-HTTP compliant and authenticates the connection
3919 instead of requests (eg: NTLM authentication)
3920
3921 - when the cost of establishing the connection to the server is significant
3922 compared to the cost of retrieving the associated object from the server.
3923
3924 This last case can happen when the server is a fast static server of cache.
3925 In this case, the server will need to be properly tuned to support high enough
3926 connection counts because connections will last until the client sends another
3927 request.
3928
3929 If the client request has to go to another backend or another server due to
3930 content switching or the load balancing algorithm, the idle connection will
Willy Tarreau9420b122013-12-15 18:58:25 +01003931 immediately be closed and a new one re-opened. Option "prefer-last-server" is
3932 available to try optimize server selection so that if the server currently
3933 attached to an idle connection is usable, it will be used.
Willy Tarreau16bfb022010-01-16 19:48:41 +01003934
3935 In general it is preferred to use "option http-server-close" with application
3936 servers, and some static servers might benefit from "option http-keep-alive".
3937
3938 At the moment, logs will not indicate whether requests came from the same
3939 session or not. The accept date reported in the logs corresponds to the end
3940 of the previous request, and the request time corresponds to the time spent
3941 waiting for a new request. The keep-alive request time is still bound to the
3942 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
3943 not set.
3944
Willy Tarreau02bce8b2014-01-30 00:15:28 +01003945 This option disables and replaces any previous 'option httpclose', 'option
Willy Tarreau70dffda2014-01-30 03:07:23 +01003946 http-server-close', 'option forceclose' or "option http-tunnel". When backend
3947 and frontend options differ, all of these 4 options have precedence over
3948 'option http-keep-alive'.
Willy Tarreau16bfb022010-01-16 19:48:41 +01003949
3950 See also : "option forceclose", "option http-server-close",
Willy Tarreau9420b122013-12-15 18:58:25 +01003951 "option prefer-last-server", "option http-pretend-keepalive",
3952 "option httpclose", and "1.1. The HTTP transaction model".
Willy Tarreau16bfb022010-01-16 19:48:41 +01003953
3954
Willy Tarreau96e31212011-05-30 18:10:30 +02003955option http-no-delay
3956no option http-no-delay
3957 Instruct the system to favor low interactive delays over performance in HTTP
3958 May be used in sections : defaults | frontend | listen | backend
3959 yes | yes | yes | yes
3960 Arguments : none
3961
3962 In HTTP, each payload is unidirectional and has no notion of interactivity.
3963 Any agent is expected to queue data somewhat for a reasonably low delay.
3964 There are some very rare server-to-server applications that abuse the HTTP
3965 protocol and expect the payload phase to be highly interactive, with many
3966 interleaved data chunks in both directions within a single request. This is
3967 absolutely not supported by the HTTP specification and will not work across
3968 most proxies or servers. When such applications attempt to do this through
3969 haproxy, it works but they will experience high delays due to the network
3970 optimizations which favor performance by instructing the system to wait for
3971 enough data to be available in order to only send full packets. Typical
3972 delays are around 200 ms per round trip. Note that this only happens with
3973 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
3974 affected.
3975
3976 When "option http-no-delay" is present in either the frontend or the backend
3977 used by a connection, all such optimizations will be disabled in order to
3978 make the exchanges as fast as possible. Of course this offers no guarantee on
3979 the functionality, as it may break at any other place. But if it works via
3980 HAProxy, it will work as fast as possible. This option should never be used
3981 by default, and should never be used at all unless such a buggy application
3982 is discovered. The impact of using this option is an increase of bandwidth
3983 usage and CPU usage, which may significantly lower performance in high
3984 latency environments.
3985
3986
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003987option http-pretend-keepalive
3988no option http-pretend-keepalive
3989 Define whether haproxy will announce keepalive to the server or not
3990 May be used in sections : defaults | frontend | listen | backend
3991 yes | yes | yes | yes
3992 Arguments : none
3993
3994 When running with "option http-server-close" or "option forceclose", haproxy
3995 adds a "Connection: close" header to the request forwarded to the server.
3996 Unfortunately, when some servers see this header, they automatically refrain
3997 from using the chunked encoding for responses of unknown length, while this
3998 is totally unrelated. The immediate effect is that this prevents haproxy from
3999 maintaining the client connection alive. A second effect is that a client or
4000 a cache could receive an incomplete response without being aware of it, and
4001 consider the response complete.
4002
4003 By setting "option http-pretend-keepalive", haproxy will make the server
4004 believe it will keep the connection alive. The server will then not fall back
4005 to the abnormal undesired above. When haproxy gets the whole response, it
4006 will close the connection with the server just as it would do with the
4007 "forceclose" option. That way the client gets a normal response and the
4008 connection is correctly closed on the server side.
4009
4010 It is recommended not to enable this option by default, because most servers
4011 will more efficiently close the connection themselves after the last packet,
4012 and release its buffers slightly earlier. Also, the added packet on the
4013 network could slightly reduce the overall peak performance. However it is
4014 worth noting that when this option is enabled, haproxy will have slightly
4015 less work to do. So if haproxy is the bottleneck on the whole architecture,
4016 enabling this option might save a few CPU cycles.
4017
4018 This option may be set both in a frontend and in a backend. It is enabled if
4019 at least one of the frontend or backend holding a connection has it enabled.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004020 This option may be combined with "option httpclose", which will cause
Willy Tarreau22a95342010-09-29 14:31:41 +02004021 keepalive to be announced to the server and close to be announced to the
4022 client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02004023
4024 If this option has been enabled in a "defaults" section, it can be disabled
4025 in a specific instance by prepending the "no" keyword before it.
4026
Willy Tarreau16bfb022010-01-16 19:48:41 +01004027 See also : "option forceclose", "option http-server-close", and
4028 "option http-keep-alive"
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02004029
Willy Tarreauc27debf2008-01-06 08:57:02 +01004030
Willy Tarreaub608feb2010-01-02 22:47:18 +01004031option http-server-close
4032no option http-server-close
4033 Enable or disable HTTP connection closing on the server side
4034 May be used in sections : defaults | frontend | listen | backend
4035 yes | yes | yes | yes
4036 Arguments : none
4037
Willy Tarreau70dffda2014-01-30 03:07:23 +01004038 By default HAProxy operates in keep-alive mode with regards to persistent
4039 connections: for each connection it processes each request and response, and
4040 leaves the connection idle on both sides between the end of a response and
4041 the start of a new request. This mode may be changed by several options such
4042 as "option http-server-close", "option forceclose", "option httpclose" or
4043 "option http-tunnel". Setting "option http-server-close" enables HTTP
4044 connection-close mode on the server side while keeping the ability to support
4045 HTTP keep-alive and pipelining on the client side. This provides the lowest
4046 latency on the client side (slow network) and the fastest session reuse on
4047 the server side to save server resources, similarly to "option forceclose".
4048 It also permits non-keepalive capable servers to be served in keep-alive mode
4049 to the clients if they conform to the requirements of RFC2616. Please note
4050 that some servers do not always conform to those requirements when they see
4051 "Connection: close" in the request. The effect will be that keep-alive will
4052 never be used. A workaround consists in enabling "option
4053 http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01004054
4055 At the moment, logs will not indicate whether requests came from the same
4056 session or not. The accept date reported in the logs corresponds to the end
4057 of the previous request, and the request time corresponds to the time spent
4058 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01004059 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
4060 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01004061
4062 This option may be set both in a frontend and in a backend. It is enabled if
4063 at least one of the frontend or backend holding a connection has it enabled.
Willy Tarreau70dffda2014-01-30 03:07:23 +01004064 It disables and replaces any previous 'option httpclose', 'option forceclose',
4065 'option http-tunnel' or 'option http-keep-alive'. Please check section 4
4066 ("Proxies") to see how this option combines with others when frontend and
4067 backend options differ.
Willy Tarreaub608feb2010-01-02 22:47:18 +01004068
4069 If this option has been enabled in a "defaults" section, it can be disabled
4070 in a specific instance by prepending the "no" keyword before it.
4071
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02004072 See also : "option forceclose", "option http-pretend-keepalive",
Willy Tarreau16bfb022010-01-16 19:48:41 +01004073 "option httpclose", "option http-keep-alive", and
4074 "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01004075
4076
Willy Tarreau02bce8b2014-01-30 00:15:28 +01004077option http-tunnel
4078no option http-tunnel
4079 Disable or enable HTTP connection processing after first transaction
4080 May be used in sections : defaults | frontend | listen | backend
4081 yes | yes | yes | yes
4082 Arguments : none
4083
Willy Tarreau70dffda2014-01-30 03:07:23 +01004084 By default HAProxy operates in keep-alive mode with regards to persistent
4085 connections: for each connection it processes each request and response, and
4086 leaves the connection idle on both sides between the end of a response and
4087 the start of a new request. This mode may be changed by several options such
4088 as "option http-server-close", "option forceclose", "option httpclose" or
4089 "option http-tunnel".
4090
4091 Option "http-tunnel" disables any HTTP processing past the first request and
4092 the first respones. This is the mode which was used by default in versions
4093 1.0 to 1.5-dev21. It is the mode with the lowest processing overhead, which
4094 is normally not needed anymore unless in very specific cases such as when
4095 using an in-house protocol that looks like HTTP but is not compatible, or
4096 just to log one request per client in order to reduce log size. Note that
4097 everything which works at the HTTP level, including header parsing/addition,
4098 cookie processing or content switching will only work for the first request
4099 and will be ignored after the first response.
Willy Tarreau02bce8b2014-01-30 00:15:28 +01004100
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 forceclose", "option http-server-close",
4105 "option httpclose", "option http-keep-alive", and
4106 "1.1. The HTTP transaction model".
4107
4108
Willy Tarreau88d349d2010-01-25 12:15:43 +01004109option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01004110no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01004111 Make use of non-standard Proxy-Connection header instead of Connection
4112 May be used in sections : defaults | frontend | listen | backend
4113 yes | yes | yes | no
4114 Arguments : none
4115
4116 While RFC2616 explicitly states that HTTP/1.1 agents must use the
4117 Connection header to indicate their wish of persistent or non-persistent
4118 connections, both browsers and proxies ignore this header for proxied
4119 connections and make use of the undocumented, non-standard Proxy-Connection
4120 header instead. The issue begins when trying to put a load balancer between
4121 browsers and such proxies, because there will be a difference between what
4122 haproxy understands and what the client and the proxy agree on.
4123
4124 By setting this option in a frontend, haproxy can automatically switch to use
4125 that non-standard header if it sees proxied requests. A proxied request is
4126 defined here as one where the URI begins with neither a '/' nor a '*'. The
4127 choice of header only affects requests passing through proxies making use of
4128 one of the "httpclose", "forceclose" and "http-server-close" options. Note
4129 that this option can only be specified in a frontend and will affect the
4130 request along its whole life.
4131
Willy Tarreau844a7e72010-01-31 21:46:18 +01004132 Also, when this option is set, a request which requires authentication will
4133 automatically switch to use proxy authentication headers if it is itself a
4134 proxied request. That makes it possible to check or enforce authentication in
4135 front of an existing proxy.
4136
Willy Tarreau88d349d2010-01-25 12:15:43 +01004137 This option should normally never be used, except in front of a proxy.
4138
4139 See also : "option httpclose", "option forceclose" and "option
4140 http-server-close".
4141
4142
Willy Tarreaud63335a2010-02-26 12:56:52 +01004143option httpchk
4144option httpchk <uri>
4145option httpchk <method> <uri>
4146option httpchk <method> <uri> <version>
4147 Enable HTTP protocol to check on the servers health
4148 May be used in sections : defaults | frontend | listen | backend
4149 yes | no | yes | yes
4150 Arguments :
4151 <method> is the optional HTTP method used with the requests. When not set,
4152 the "OPTIONS" method is used, as it generally requires low server
4153 processing and is easy to filter out from the logs. Any method
4154 may be used, though it is not recommended to invent non-standard
4155 ones.
4156
4157 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
4158 which is accessible by default on almost any server, but may be
4159 changed to any other URI. Query strings are permitted.
4160
4161 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
4162 but some servers might behave incorrectly in HTTP 1.0, so turning
4163 it to HTTP/1.1 may sometimes help. Note that the Host field is
4164 mandatory in HTTP/1.1, and as a trick, it is possible to pass it
4165 after "\r\n" following the version string.
4166
4167 By default, server health checks only consist in trying to establish a TCP
4168 connection. When "option httpchk" is specified, a complete HTTP request is
4169 sent once the TCP connection is established, and responses 2xx and 3xx are
4170 considered valid, while all other ones indicate a server failure, including
4171 the lack of any response.
4172
4173 The port and interval are specified in the server configuration.
4174
4175 This option does not necessarily require an HTTP backend, it also works with
4176 plain TCP backends. This is particularly useful to check simple scripts bound
4177 to some dedicated ports using the inetd daemon.
4178
4179 Examples :
4180 # Relay HTTPS traffic to Apache instance and check service availability
4181 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
4182 backend https_relay
4183 mode tcp
4184 option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www
4185 server apache1 192.168.1.1:443 check port 80
4186
Simon Hormanafc47ee2013-11-25 10:46:35 +09004187 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
4188 "option pgsql-check", "http-check" and the "check", "port" and
4189 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01004190
4191
Willy Tarreauc27debf2008-01-06 08:57:02 +01004192option httpclose
4193no option httpclose
4194 Enable or disable passive HTTP connection closing
4195 May be used in sections : defaults | frontend | listen | backend
4196 yes | yes | yes | yes
4197 Arguments : none
4198
Willy Tarreau70dffda2014-01-30 03:07:23 +01004199 By default HAProxy operates in keep-alive mode with regards to persistent
4200 connections: for each connection it processes each request and response, and
4201 leaves the connection idle on both sides between the end of a response and
4202 the start of a new request. This mode may be changed by several options such
4203 as "option http-serve-close", "option forceclose", "option httpclose" or
4204 "option http-tunnel".
4205
4206 If "option httpclose" is set, HAProxy will work in HTTP tunnel mode and check
4207 if a "Connection: close" header is already set in each direction, and will
4208 add one if missing. Each end should react to this by actively closing the TCP
4209 connection after each transfer, thus resulting in a switch to the HTTP close
4210 mode. Any "Connection" header different from "close" will also be removed.
4211 Note that this option is deprecated since what it does is very cheap but not
4212 reliable. Using "option http-server-close" or "option forceclose" is strongly
4213 recommended instead.
Willy Tarreauc27debf2008-01-06 08:57:02 +01004214
4215 It seldom happens that some servers incorrectly ignore this header and do not
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004216 close the connection even though they reply "Connection: close". For this
Willy Tarreau0dfdf192010-01-05 11:33:11 +01004217 reason, they are not compatible with older HTTP 1.0 browsers. If this happens
4218 it is possible to use the "option forceclose" which actively closes the
4219 request connection once the server responds. Option "forceclose" also
4220 releases the server connection earlier because it does not have to wait for
4221 the client to acknowledge it.
Willy Tarreauc27debf2008-01-06 08:57:02 +01004222
4223 This option may be set both in a frontend and in a backend. It is enabled if
4224 at least one of the frontend or backend holding a connection has it enabled.
Willy Tarreau02bce8b2014-01-30 00:15:28 +01004225 It disables and replaces any previous 'option http-server-close',
Willy Tarreau70dffda2014-01-30 03:07:23 +01004226 'option forceclose', 'option http-keep-alive' or "option http-tunnel". Please
4227 check section 4 ("Proxies") to see how this option combines with others when
4228 frontend and backend options differ.
Willy Tarreauc27debf2008-01-06 08:57:02 +01004229
4230 If this option has been enabled in a "defaults" section, it can be disabled
4231 in a specific instance by prepending the "no" keyword before it.
4232
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02004233 See also : "option forceclose", "option http-server-close" and
4234 "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01004235
4236
Emeric Brun3a058f32009-06-30 18:26:00 +02004237option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01004238 Enable logging of HTTP request, session state and timers
4239 May be used in sections : defaults | frontend | listen | backend
4240 yes | yes | yes | yes
Emeric Brun3a058f32009-06-30 18:26:00 +02004241 Arguments :
4242 clf if the "clf" argument is added, then the output format will be
4243 the CLF format instead of HAProxy's default HTTP format. You can
4244 use this when you need to feed HAProxy's logs through a specific
4245 log analyser which only support the CLF format and which is not
4246 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01004247
4248 By default, the log output format is very poor, as it only contains the
4249 source and destination addresses, and the instance name. By specifying
4250 "option httplog", each log line turns into a much richer format including,
4251 but not limited to, the HTTP request, the connection timers, the session
4252 status, the connections numbers, the captured headers and cookies, the
4253 frontend, backend and server name, and of course the source address and
4254 ports.
4255
4256 This option may be set either in the frontend or the backend.
4257
Emeric Brun3a058f32009-06-30 18:26:00 +02004258 If this option has been enabled in a "defaults" section, it can be disabled
4259 in a specific instance by prepending the "no" keyword before it. Specifying
4260 only "option httplog" will automatically clear the 'clf' mode if it was set
4261 by default.
4262
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004263 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01004264
Willy Tarreau55165fe2009-05-10 12:02:55 +02004265
4266option http_proxy
4267no option http_proxy
4268 Enable or disable plain HTTP proxy mode
4269 May be used in sections : defaults | frontend | listen | backend
4270 yes | yes | yes | yes
4271 Arguments : none
4272
4273 It sometimes happens that people need a pure HTTP proxy which understands
4274 basic proxy requests without caching nor any fancy feature. In this case,
4275 it may be worth setting up an HAProxy instance with the "option http_proxy"
4276 set. In this mode, no server is declared, and the connection is forwarded to
4277 the IP address and port found in the URL after the "http://" scheme.
4278
4279 No host address resolution is performed, so this only works when pure IP
4280 addresses are passed. Since this option's usage perimeter is rather limited,
4281 it will probably be used only by experts who know they need exactly it. Last,
4282 if the clients are susceptible of sending keep-alive requests, it will be
Cyril Bonté2409e682010-12-14 22:47:51 +01004283 needed to add "option httpclose" to ensure that all requests will correctly
Willy Tarreau55165fe2009-05-10 12:02:55 +02004284 be analyzed.
4285
4286 If this option has been enabled in a "defaults" section, it can be disabled
4287 in a specific instance by prepending the "no" keyword before it.
4288
4289 Example :
4290 # this backend understands HTTP proxy requests and forwards them directly.
4291 backend direct_forward
4292 option httpclose
4293 option http_proxy
4294
4295 See also : "option httpclose"
4296
Willy Tarreau211ad242009-10-03 21:45:07 +02004297
Jamie Gloudon801a0a32012-08-25 00:18:33 -04004298option independent-streams
4299no option independent-streams
4300 Enable or disable independent timeout processing for both directions
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02004301 May be used in sections : defaults | frontend | listen | backend
4302 yes | yes | yes | yes
4303 Arguments : none
4304
4305 By default, when data is sent over a socket, both the write timeout and the
4306 read timeout for that socket are refreshed, because we consider that there is
4307 activity on that socket, and we have no other means of guessing if we should
4308 receive data or not.
4309
4310 While this default behaviour is desirable for almost all applications, there
4311 exists a situation where it is desirable to disable it, and only refresh the
4312 read timeout if there are incoming data. This happens on sessions with large
4313 timeouts and low amounts of exchanged data such as telnet session. If the
4314 server suddenly disappears, the output data accumulates in the system's
4315 socket buffers, both timeouts are correctly refreshed, and there is no way
4316 to know the server does not receive them, so we don't timeout. However, when
4317 the underlying protocol always echoes sent data, it would be enough by itself
4318 to detect the issue using the read timeout. Note that this problem does not
4319 happen with more verbose protocols because data won't accumulate long in the
4320 socket buffers.
4321
4322 When this option is set on the frontend, it will disable read timeout updates
4323 on data sent to the client. There probably is little use of this case. When
4324 the option is set on the backend, it will disable read timeout updates on
4325 data sent to the server. Doing so will typically break large HTTP posts from
4326 slow lines, so use it with caution.
4327
Jamie Gloudon801a0a32012-08-25 00:18:33 -04004328 Note: older versions used to call this setting "option independant-streams"
4329 with a spelling mistake. This spelling is still supported but
4330 deprecated.
4331
Willy Tarreauce887fd2012-05-12 12:50:00 +02004332 See also : "timeout client", "timeout server" and "timeout tunnel"
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02004333
4334
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02004335option ldap-check
4336 Use LDAPv3 health checks for server testing
4337 May be used in sections : defaults | frontend | listen | backend
4338 yes | no | yes | yes
4339 Arguments : none
4340
4341 It is possible to test that the server correctly talks LDAPv3 instead of just
4342 testing that it accepts the TCP connection. When this option is set, an
4343 LDAPv3 anonymous simple bind message is sent to the server, and the response
4344 is analyzed to find an LDAPv3 bind response message.
4345
4346 The server is considered valid only when the LDAP response contains success
4347 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
4348
4349 Logging of bind requests is server dependent see your documentation how to
4350 configure it.
4351
4352 Example :
4353 option ldap-check
4354
4355 See also : "option httpchk"
4356
4357
Willy Tarreau211ad242009-10-03 21:45:07 +02004358option log-health-checks
4359no option log-health-checks
4360 Enable or disable logging of health checks
4361 May be used in sections : defaults | frontend | listen | backend
4362 yes | no | yes | yes
4363 Arguments : none
4364
4365 Enable health checks logging so it possible to check for example what
4366 was happening before a server crash. Failed health check are logged if
4367 server is UP and succeeded health checks if server is DOWN, so the amount
4368 of additional information is limited.
4369
4370 If health check logging is enabled no health check status is printed
4371 when servers is set up UP/DOWN/ENABLED/DISABLED.
4372
4373 See also: "log" and section 8 about logging.
4374
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02004375
4376option log-separate-errors
4377no option log-separate-errors
4378 Change log level for non-completely successful connections
4379 May be used in sections : defaults | frontend | listen | backend
4380 yes | yes | yes | no
4381 Arguments : none
4382
4383 Sometimes looking for errors in logs is not easy. This option makes haproxy
4384 raise the level of logs containing potentially interesting information such
4385 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
4386 level changes from "info" to "err". This makes it possible to log them
4387 separately to a different file with most syslog daemons. Be careful not to
4388 remove them from the original file, otherwise you would lose ordering which
4389 provides very important information.
4390
4391 Using this option, large sites dealing with several thousand connections per
4392 second may log normal traffic to a rotating buffer and only archive smaller
4393 error logs.
4394
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004395 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02004396 logging.
4397
Willy Tarreauc27debf2008-01-06 08:57:02 +01004398
4399option logasap
4400no option logasap
4401 Enable or disable early logging of HTTP requests
4402 May be used in sections : defaults | frontend | listen | backend
4403 yes | yes | yes | no
4404 Arguments : none
4405
4406 By default, HTTP requests are logged upon termination so that the total
4407 transfer time and the number of bytes appear in the logs. When large objects
4408 are being transferred, it may take a while before the request appears in the
4409 logs. Using "option logasap", the request gets logged as soon as the server
4410 sends the complete headers. The only missing information in the logs will be
4411 the total number of bytes which will indicate everything except the amount
4412 of data transferred, and the total time which will not take the transfer
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004413 time into account. In such a situation, it's a good practice to capture the
Willy Tarreauc27debf2008-01-06 08:57:02 +01004414 "Content-Length" response header so that the logs at least indicate how many
4415 bytes are expected to be transferred.
4416
Willy Tarreaucc6c8912009-02-22 10:53:55 +01004417 Examples :
4418 listen http_proxy 0.0.0.0:80
4419 mode http
4420 option httplog
4421 option logasap
4422 log 192.168.2.200 local3
4423
4424 >>> Feb 6 12:14:14 localhost \
4425 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
4426 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
4427 "GET /image.iso HTTP/1.0"
4428
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004429 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01004430 logging.
4431
4432
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02004433option mysql-check [ user <username> ]
4434 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01004435 May be used in sections : defaults | frontend | listen | backend
4436 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02004437 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02004438 <username> This is the username which will be used when connecting to MySQL
4439 server.
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02004440
4441 If you specify a username, the check consists of sending two MySQL packet,
4442 one Client Authentication packet, and one QUIT packet, to correctly close
4443 MySQL session. We then parse the MySQL Handshake Initialisation packet and/or
4444 Error packet. It is a basic but useful test which does not produce error nor
4445 aborted connect on the server. However, it requires adding an authorization
4446 in the MySQL table, like this :
4447
4448 USE mysql;
4449 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
4450 FLUSH PRIVILEGES;
4451
4452 If you don't specify a username (it is deprecated and not recommended), the
4453 check only consists in parsing the Mysql Handshake Initialisation packet or
4454 Error packet, we don't send anything in this mode. It was reported that it
4455 can generate lockout if check is too frequent and/or if there is not enough
4456 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
4457 value as if a connection is established successfully within fewer than MySQL
4458 "max_connect_errors" attempts after a previous connection was interrupted,
4459 the error count for the host is cleared to zero. If HAProxy's server get
4460 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
4461
4462 Remember that this does not check database presence nor database consistency.
4463 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01004464
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02004465 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01004466
4467 Most often, an incoming MySQL server needs to see the client's IP address for
4468 various purposes, including IP privilege matching and connection logging.
4469 When possible, it is often wise to masquerade the client's IP address when
4470 connecting to the server using the "usesrc" argument of the "source" keyword,
4471 which requires the cttproxy feature to be compiled in, and the MySQL server
4472 to route the client via the machine hosting haproxy.
4473
4474 See also: "option httpchk"
4475
4476
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004477option nolinger
4478no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004479 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004480 May be used in sections: defaults | frontend | listen | backend
4481 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004482 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004483
4484 When clients or servers abort connections in a dirty way (eg: they are
4485 physically disconnected), the session timeouts triggers and the session is
4486 closed. But it will remain in FIN_WAIT1 state for some time in the system,
4487 using some resources and possibly limiting the ability to establish newer
4488 connections.
4489
4490 When this happens, it is possible to activate "option nolinger" which forces
4491 the system to immediately remove any socket's pending data on close. Thus,
4492 the session is instantly purged from the system's tables. This usually has
4493 side effects such as increased number of TCP resets due to old retransmits
4494 getting immediately rejected. Some firewalls may sometimes complain about
4495 this too.
4496
4497 For this reason, it is not recommended to use this option when not absolutely
4498 needed. You know that you need it when you have thousands of FIN_WAIT1
4499 sessions on your system (TIME_WAIT ones do not count).
4500
4501 This option may be used both on frontends and backends, depending on the side
4502 where it is required. Use it on the frontend for clients, and on the backend
4503 for servers.
4504
4505 If this option has been enabled in a "defaults" section, it can be disabled
4506 in a specific instance by prepending the "no" keyword before it.
4507
4508
Willy Tarreau55165fe2009-05-10 12:02:55 +02004509option originalto [ except <network> ] [ header <name> ]
4510 Enable insertion of the X-Original-To header to requests sent to servers
4511 May be used in sections : defaults | frontend | listen | backend
4512 yes | yes | yes | yes
4513 Arguments :
4514 <network> is an optional argument used to disable this option for sources
4515 matching <network>
4516 <name> an optional argument to specify a different "X-Original-To"
4517 header name.
4518
4519 Since HAProxy can work in transparent mode, every request from a client can
4520 be redirected to the proxy and HAProxy itself can proxy every request to a
4521 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
4522 be lost. This is annoying when you want access rules based on destination ip
4523 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
4524 added by HAProxy to all requests sent to the server. This header contains a
4525 value representing the original destination IP address. Since this must be
4526 configured to always use the last occurrence of this header only. Note that
4527 only the last occurrence of the header must be used, since it is really
4528 possible that the client has already brought one.
4529
4530 The keyword "header" may be used to supply a different header name to replace
4531 the default "X-Original-To". This can be useful where you might already
4532 have a "X-Original-To" header from a different application, and you need
4533 preserve it. Also if your backend server doesn't use the "X-Original-To"
4534 header and requires different one.
4535
4536 Sometimes, a same HAProxy instance may be shared between a direct client
4537 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
4538 used to decrypt HTTPS traffic). It is possible to disable the addition of the
4539 header for a known source address or network by adding the "except" keyword
4540 followed by the network address. In this case, any source IP matching the
4541 network will not cause an addition of this header. Most common uses are with
4542 private networks or 127.0.0.1.
4543
4544 This option may be specified either in the frontend or in the backend. If at
4545 least one of them uses it, the header will be added. Note that the backend's
4546 setting of the header subargument takes precedence over the frontend's if
4547 both are defined.
4548
Willy Tarreau55165fe2009-05-10 12:02:55 +02004549 Examples :
4550 # Original Destination address
4551 frontend www
4552 mode http
4553 option originalto except 127.0.0.1
4554
4555 # Those servers want the IP Address in X-Client-Dst
4556 backend www
4557 mode http
4558 option originalto header X-Client-Dst
4559
Willy Tarreau87cf5142011-08-19 22:57:24 +02004560 See also : "option httpclose", "option http-server-close",
4561 "option forceclose"
Willy Tarreau55165fe2009-05-10 12:02:55 +02004562
4563
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004564option persist
4565no option persist
4566 Enable or disable forced persistence on down servers
4567 May be used in sections: defaults | frontend | listen | backend
4568 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004569 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004570
4571 When an HTTP request reaches a backend with a cookie which references a dead
4572 server, by default it is redispatched to another server. It is possible to
4573 force the request to be sent to the dead server first using "option persist"
4574 if absolutely needed. A common use case is when servers are under extreme
4575 load and spend their time flapping. In this case, the users would still be
4576 directed to the server they opened the session on, in the hope they would be
4577 correctly served. It is recommended to use "option redispatch" in conjunction
4578 with this option so that in the event it would not be possible to connect to
4579 the server at all (server definitely dead), the client would finally be
4580 redirected to another valid server.
4581
4582 If this option has been enabled in a "defaults" section, it can be disabled
4583 in a specific instance by prepending the "no" keyword before it.
4584
Willy Tarreau4de91492010-01-22 19:10:05 +01004585 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004586
4587
Willy Tarreau0c122822013-12-15 18:49:01 +01004588option pgsql-check [ user <username> ]
4589 Use PostgreSQL health checks for server testing
4590 May be used in sections : defaults | frontend | listen | backend
4591 yes | no | yes | yes
4592 Arguments :
4593 <username> This is the username which will be used when connecting to
4594 PostgreSQL server.
4595
4596 The check sends a PostgreSQL StartupMessage and waits for either
4597 Authentication request or ErrorResponse message. It is a basic but useful
4598 test which does not produce error nor aborted connect on the server.
4599 This check is identical with the "mysql-check".
4600
4601 See also: "option httpchk"
4602
4603
Willy Tarreau9420b122013-12-15 18:58:25 +01004604option prefer-last-server
4605no option prefer-last-server
4606 Allow multiple load balanced requests to remain on the same server
4607 May be used in sections: defaults | frontend | listen | backend
4608 yes | no | yes | yes
4609 Arguments : none
4610
4611 When the load balancing algorithm in use is not deterministic, and a previous
4612 request was sent to a server to which haproxy still holds a connection, it is
4613 sometimes desirable that subsequent requests on a same session go to the same
4614 server as much as possible. Note that this is different from persistence, as
4615 we only indicate a preference which haproxy tries to apply without any form
4616 of warranty. The real use is for keep-alive connections sent to servers. When
4617 this option is used, haproxy will try to reuse the same connection that is
4618 attached to the server instead of rebalancing to another server, causing a
4619 close of the connection. This can make sense for static file servers. It does
Willy Tarreau068621e2013-12-23 15:11:25 +01004620 not make much sense to use this in combination with hashing algorithms. Note,
4621 haproxy already automatically tries to stick to a server which sends a 401 or
4622 to a proxy which sends a 407 (authentication required). This is mandatory for
4623 use with the broken NTLM authentication challenge, and significantly helps in
4624 troubleshooting some faulty applications. Option prefer-last-server might be
4625 desirable in these environments as well, to avoid redistributing the traffic
4626 after every other response.
Willy Tarreau9420b122013-12-15 18:58:25 +01004627
4628 If this option has been enabled in a "defaults" section, it can be disabled
4629 in a specific instance by prepending the "no" keyword before it.
4630
4631 See also: "option http-keep-alive"
4632
4633
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004634option redispatch
4635no option redispatch
4636 Enable or disable session redistribution in case of connection failure
4637 May be used in sections: defaults | frontend | listen | backend
4638 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004639 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004640
4641 In HTTP mode, if a server designated by a cookie is down, clients may
4642 definitely stick to it because they cannot flush the cookie, so they will not
4643 be able to access the service anymore.
4644
4645 Specifying "option redispatch" will allow the proxy to break their
4646 persistence and redistribute them to a working server.
4647
4648 It also allows to retry last connection to another server in case of multiple
4649 connection failures. Of course, it requires having "retries" set to a nonzero
4650 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01004651
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004652 This form is the preferred form, which replaces both the "redispatch" and
4653 "redisp" keywords.
4654
4655 If this option has been enabled in a "defaults" section, it can be disabled
4656 in a specific instance by prepending the "no" keyword before it.
4657
Willy Tarreau4de91492010-01-22 19:10:05 +01004658 See also : "redispatch", "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004659
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004660
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02004661option redis-check
4662 Use redis health checks for server testing
4663 May be used in sections : defaults | frontend | listen | backend
4664 yes | no | yes | yes
4665 Arguments : none
4666
4667 It is possible to test that the server correctly talks REDIS protocol instead
4668 of just testing that it accepts the TCP connection. When this option is set,
4669 a PING redis command is sent to the server, and the response is analyzed to
4670 find the "+PONG" response message.
4671
4672 Example :
4673 option redis-check
4674
4675 See also : "option httpchk"
4676
4677
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004678option smtpchk
4679option smtpchk <hello> <domain>
4680 Use SMTP health checks for server testing
4681 May be used in sections : defaults | frontend | listen | backend
4682 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01004683 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004684 <hello> is an optional argument. It is the "hello" command to use. It can
4685 be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other
4686 values will be turned into the default command ("HELO").
4687
4688 <domain> is the domain name to present to the server. It may only be
4689 specified (and is mandatory) if the hello command has been
4690 specified. By default, "localhost" is used.
4691
4692 When "option smtpchk" is set, the health checks will consist in TCP
4693 connections followed by an SMTP command. By default, this command is
4694 "HELO localhost". The server's return code is analyzed and only return codes
4695 starting with a "2" will be considered as valid. All other responses,
4696 including a lack of response will constitute an error and will indicate a
4697 dead server.
4698
4699 This test is meant to be used with SMTP servers or relays. Depending on the
4700 request, it is possible that some servers do not log each connection attempt,
4701 so you may want to experiment to improve the behaviour. Using telnet on port
4702 25 is often easier than adjusting the configuration.
4703
4704 Most often, an incoming SMTP server needs to see the client's IP address for
4705 various purposes, including spam filtering, anti-spoofing and logging. When
4706 possible, it is often wise to masquerade the client's IP address when
4707 connecting to the server using the "usesrc" argument of the "source" keyword,
4708 which requires the cttproxy feature to be compiled in.
4709
4710 Example :
4711 option smtpchk HELO mydomain.org
4712
4713 See also : "option httpchk", "source"
4714
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004715
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02004716option socket-stats
4717no option socket-stats
4718
4719 Enable or disable collecting & providing separate statistics for each socket.
4720 May be used in sections : defaults | frontend | listen | backend
4721 yes | yes | yes | no
4722
4723 Arguments : none
4724
4725
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004726option splice-auto
4727no option splice-auto
4728 Enable or disable automatic kernel acceleration on sockets in both directions
4729 May be used in sections : defaults | frontend | listen | backend
4730 yes | yes | yes | yes
4731 Arguments : none
4732
4733 When this option is enabled either on a frontend or on a backend, haproxy
4734 will automatically evaluate the opportunity to use kernel tcp splicing to
4735 forward data between the client and the server, in either direction. Haproxy
4736 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004737 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004738 are not much aggressive in order to limit excessive use of splicing. This
4739 option requires splicing to be enabled at compile time, and may be globally
4740 disabled with the global option "nosplice". Since splice uses pipes, using it
4741 requires that there are enough spare pipes.
4742
4743 Important note: kernel-based TCP splicing is a Linux-specific feature which
4744 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
4745 transfer data between sockets without copying these data to user-space, thus
4746 providing noticeable performance gains and CPU cycles savings. Since many
4747 early implementations are buggy, corrupt data and/or are inefficient, this
4748 feature is not enabled by default, and it should be used with extreme care.
4749 While it is not possible to detect the correctness of an implementation,
4750 2.6.29 is the first version offering a properly working implementation. In
4751 case of doubt, splicing may be globally disabled using the global "nosplice"
4752 keyword.
4753
4754 Example :
4755 option splice-auto
4756
4757 If this option has been enabled in a "defaults" section, it can be disabled
4758 in a specific instance by prepending the "no" keyword before it.
4759
4760 See also : "option splice-request", "option splice-response", and global
4761 options "nosplice" and "maxpipes"
4762
4763
4764option splice-request
4765no option splice-request
4766 Enable or disable automatic kernel acceleration on sockets for requests
4767 May be used in sections : defaults | frontend | listen | backend
4768 yes | yes | yes | yes
4769 Arguments : none
4770
4771 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004772 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004773 the client to the server. It might still use the recv/send scheme if there
4774 are no spare pipes left. This option requires splicing to be enabled at
4775 compile time, and may be globally disabled with the global option "nosplice".
4776 Since splice uses pipes, using it requires that there are enough spare pipes.
4777
4778 Important note: see "option splice-auto" for usage limitations.
4779
4780 Example :
4781 option splice-request
4782
4783 If this option has been enabled in a "defaults" section, it can be disabled
4784 in a specific instance by prepending the "no" keyword before it.
4785
4786 See also : "option splice-auto", "option splice-response", and global options
4787 "nosplice" and "maxpipes"
4788
4789
4790option splice-response
4791no option splice-response
4792 Enable or disable automatic kernel acceleration on sockets for responses
4793 May be used in sections : defaults | frontend | listen | backend
4794 yes | yes | yes | yes
4795 Arguments : none
4796
4797 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004798 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004799 the server to the client. It might still use the recv/send scheme if there
4800 are no spare pipes left. This option requires splicing to be enabled at
4801 compile time, and may be globally disabled with the global option "nosplice".
4802 Since splice uses pipes, using it requires that there are enough spare pipes.
4803
4804 Important note: see "option splice-auto" for usage limitations.
4805
4806 Example :
4807 option splice-response
4808
4809 If this option has been enabled in a "defaults" section, it can be disabled
4810 in a specific instance by prepending the "no" keyword before it.
4811
4812 See also : "option splice-auto", "option splice-request", and global options
4813 "nosplice" and "maxpipes"
4814
4815
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004816option srvtcpka
4817no option srvtcpka
4818 Enable or disable the sending of TCP keepalive packets on the server side
4819 May be used in sections : defaults | frontend | listen | backend
4820 yes | no | yes | yes
4821 Arguments : none
4822
4823 When there is a firewall or any session-aware component between a client and
4824 a server, and when the protocol involves very long sessions with long idle
4825 periods (eg: remote desktops), there is a risk that one of the intermediate
4826 components decides to expire a session which has remained idle for too long.
4827
4828 Enabling socket-level TCP keep-alives makes the system regularly send packets
4829 to the other end of the connection, leaving it active. The delay between
4830 keep-alive probes is controlled by the system only and depends both on the
4831 operating system and its tuning parameters.
4832
4833 It is important to understand that keep-alive packets are neither emitted nor
4834 received at the application level. It is only the network stacks which sees
4835 them. For this reason, even if one side of the proxy already uses keep-alives
4836 to maintain its connection alive, those keep-alive packets will not be
4837 forwarded to the other side of the proxy.
4838
4839 Please note that this has nothing to do with HTTP keep-alive.
4840
4841 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
4842 server side of a connection, which should help when session expirations are
4843 noticed between HAProxy and a server.
4844
4845 If this option has been enabled in a "defaults" section, it can be disabled
4846 in a specific instance by prepending the "no" keyword before it.
4847
4848 See also : "option clitcpka", "option tcpka"
4849
4850
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004851option ssl-hello-chk
4852 Use SSLv3 client hello health checks for server testing
4853 May be used in sections : defaults | frontend | listen | backend
4854 yes | no | yes | yes
4855 Arguments : none
4856
4857 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
4858 possible to test that the server correctly talks SSL instead of just testing
4859 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
4860 SSLv3 client hello messages are sent once the connection is established to
4861 the server, and the response is analyzed to find an SSL server hello message.
4862 The server is considered valid only when the response contains this server
4863 hello message.
4864
4865 All servers tested till there correctly reply to SSLv3 client hello messages,
4866 and most servers tested do not even log the requests containing only hello
4867 messages, which is appreciable.
4868
Willy Tarreau763a95b2012-10-04 23:15:39 +02004869 Note that this check works even when SSL support was not built into haproxy
4870 because it forges the SSL message. When SSL support is available, it is best
4871 to use native SSL health checks instead of this one.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004872
Willy Tarreau763a95b2012-10-04 23:15:39 +02004873 See also: "option httpchk", "check-ssl"
4874
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004875
Willy Tarreaued179852013-12-16 01:07:00 +01004876option tcp-check
4877 Perform health checks using tcp-check send/expect sequences
4878 May be used in sections: defaults | frontend | listen | backend
4879 yes | no | yes | yes
4880
4881 This health check method is intended to be combined with "tcp-check" command
4882 lists in order to support send/expect types of health check sequences.
4883
4884 TCP checks currently support 4 modes of operations :
4885 - no "tcp-check" directive : the health check only consists in a connection
4886 attempt, which remains the default mode.
4887
4888 - "tcp-check send" or "tcp-check send-binary" only is mentionned : this is
4889 used to send a string along with a connection opening. With some
4890 protocols, it helps sending a "QUIT" message for example that prevents
4891 the server from logging a connection error for each health check. The
4892 check result will still be based on the ability to open the connection
4893 only.
4894
4895 - "tcp-check expect" only is mentionned : this is used to test a banner.
4896 The connection is opened and haproxy waits for the server to present some
4897 contents which must validate some rules. The check result will be based
4898 on the matching between the contents and the rules. This is suited for
4899 POP, IMAP, SMTP, FTP, SSH, TELNET.
4900
4901 - both "tcp-check send" and "tcp-check expect" are mentionned : this is
4902 used to test a hello-type protocol. Haproxy sends a message, the server
4903 responds and its response is analysed. the check result will be based on
4904 the maching between the response contents and the rules. This is often
4905 suited for protocols which require a binding or a request/response model.
4906 LDAP, MySQL, Redis and SSL are example of such protocols, though they
4907 already all have their dedicated checks with a deeper understanding of
4908 the respective protocols.
4909 In this mode, many questions may be sent and many answers may be
4910 analysed.
4911
4912 Examples :
4913 # perform a POP check (analyse only server's banner)
4914 option tcp-check
4915 tcp-check expect string +OK\ POP3\ ready
4916
4917 # perform an IMAP check (analyse only server's banner)
4918 option tcp-check
4919 tcp-check expect string *\ OK\ IMAP4\ ready
4920
4921 # look for the redis master server after ensuring it speaks well
4922 # redis protocol, then it exits properly.
4923 # (send a command then analyse the response 3 tims)
4924 option tcp-check
4925 tcp-check send PING\r\n
4926 tcp-check expect +PONG
4927 tcp-check send info\ replication\r\n
4928 tcp-check expect string role:master
4929 tcp-check send QUIT\r\n
4930 tcp-check expect string +OK
4931
4932 forge a HTTP request, then analyse the response
4933 (send many headers before analyzing)
4934 option tcp-check
4935 tcp-check send HEAD\ /\ HTTP/1.1\r\n
4936 tcp-check send Host:\ www.mydomain.com\r\n
4937 tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n
4938 tcp-check send \r\n
4939 tcp-check expect rstring HTTP/1\..\ (2..|3..)
4940
4941
4942 See also : "tcp-check expect", "tcp-check send"
4943
4944
Willy Tarreau9ea05a72009-06-14 12:07:01 +02004945option tcp-smart-accept
4946no option tcp-smart-accept
4947 Enable or disable the saving of one ACK packet during the accept sequence
4948 May be used in sections : defaults | frontend | listen | backend
4949 yes | yes | yes | no
4950 Arguments : none
4951
4952 When an HTTP connection request comes in, the system acknowledges it on
4953 behalf of HAProxy, then the client immediately sends its request, and the
4954 system acknowledges it too while it is notifying HAProxy about the new
4955 connection. HAProxy then reads the request and responds. This means that we
4956 have one TCP ACK sent by the system for nothing, because the request could
4957 very well be acknowledged by HAProxy when it sends its response.
4958
4959 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
4960 sending this useless ACK on platforms which support it (currently at least
4961 Linux). It must not cause any problem, because the system will send it anyway
4962 after 40 ms if the response takes more time than expected to come.
4963
4964 During complex network debugging sessions, it may be desirable to disable
4965 this optimization because delayed ACKs can make troubleshooting more complex
4966 when trying to identify where packets are delayed. It is then possible to
4967 fall back to normal behaviour by specifying "no option tcp-smart-accept".
4968
4969 It is also possible to force it for non-HTTP proxies by simply specifying
4970 "option tcp-smart-accept". For instance, it can make sense with some services
4971 such as SMTP where the server speaks first.
4972
4973 It is recommended to avoid forcing this option in a defaults section. In case
4974 of doubt, consider setting it back to automatic values by prepending the
4975 "default" keyword before it, or disabling it using the "no" keyword.
4976
Willy Tarreaud88edf22009-06-14 15:48:17 +02004977 See also : "option tcp-smart-connect"
4978
4979
4980option tcp-smart-connect
4981no option tcp-smart-connect
4982 Enable or disable the saving of one ACK packet during the connect sequence
4983 May be used in sections : defaults | frontend | listen | backend
4984 yes | no | yes | yes
4985 Arguments : none
4986
4987 On certain systems (at least Linux), HAProxy can ask the kernel not to
4988 immediately send an empty ACK upon a connection request, but to directly
4989 send the buffer request instead. This saves one packet on the network and
4990 thus boosts performance. It can also be useful for some servers, because they
4991 immediately get the request along with the incoming connection.
4992
4993 This feature is enabled when "option tcp-smart-connect" is set in a backend.
4994 It is not enabled by default because it makes network troubleshooting more
4995 complex.
4996
4997 It only makes sense to enable it with protocols where the client speaks first
4998 such as HTTP. In other situations, if there is no data to send in place of
4999 the ACK, a normal ACK is sent.
5000
5001 If this option has been enabled in a "defaults" section, it can be disabled
5002 in a specific instance by prepending the "no" keyword before it.
5003
5004 See also : "option tcp-smart-accept"
5005
Willy Tarreau9ea05a72009-06-14 12:07:01 +02005006
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005007option tcpka
5008 Enable or disable the sending of TCP keepalive packets on both sides
5009 May be used in sections : defaults | frontend | listen | backend
5010 yes | yes | yes | yes
5011 Arguments : none
5012
5013 When there is a firewall or any session-aware component between a client and
5014 a server, and when the protocol involves very long sessions with long idle
5015 periods (eg: remote desktops), there is a risk that one of the intermediate
5016 components decides to expire a session which has remained idle for too long.
5017
5018 Enabling socket-level TCP keep-alives makes the system regularly send packets
5019 to the other end of the connection, leaving it active. The delay between
5020 keep-alive probes is controlled by the system only and depends both on the
5021 operating system and its tuning parameters.
5022
5023 It is important to understand that keep-alive packets are neither emitted nor
5024 received at the application level. It is only the network stacks which sees
5025 them. For this reason, even if one side of the proxy already uses keep-alives
5026 to maintain its connection alive, those keep-alive packets will not be
5027 forwarded to the other side of the proxy.
5028
5029 Please note that this has nothing to do with HTTP keep-alive.
5030
5031 Using option "tcpka" enables the emission of TCP keep-alive probes on both
5032 the client and server sides of a connection. Note that this is meaningful
5033 only in "defaults" or "listen" sections. If this option is used in a
5034 frontend, only the client side will get keep-alives, and if this option is
5035 used in a backend, only the server side will get keep-alives. For this
5036 reason, it is strongly recommended to explicitly use "option clitcpka" and
5037 "option srvtcpka" when the configuration is split between frontends and
5038 backends.
5039
5040 See also : "option clitcpka", "option srvtcpka"
5041
Willy Tarreau844e3c52008-01-11 16:28:18 +01005042
5043option tcplog
5044 Enable advanced logging of TCP connections with session state and timers
5045 May be used in sections : defaults | frontend | listen | backend
5046 yes | yes | yes | yes
5047 Arguments : none
5048
5049 By default, the log output format is very poor, as it only contains the
5050 source and destination addresses, and the instance name. By specifying
5051 "option tcplog", each log line turns into a much richer format including, but
5052 not limited to, the connection timers, the session status, the connections
5053 numbers, the frontend, backend and server name, and of course the source
5054 address and ports. This option is useful for pure TCP proxies in order to
5055 find which of the client or server disconnects or times out. For normal HTTP
5056 proxies, it's better to use "option httplog" which is even more complete.
5057
5058 This option may be set either in the frontend or the backend.
5059
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005060 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01005061
5062
Willy Tarreau844e3c52008-01-11 16:28:18 +01005063option transparent
5064no option transparent
5065 Enable client-side transparent proxying
5066 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01005067 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01005068 Arguments : none
5069
5070 This option was introduced in order to provide layer 7 persistence to layer 3
5071 load balancers. The idea is to use the OS's ability to redirect an incoming
5072 connection for a remote address to a local process (here HAProxy), and let
5073 this process know what address was initially requested. When this option is
5074 used, sessions without cookies will be forwarded to the original destination
5075 IP address of the incoming request (which should match that of another
5076 equipment), while requests with cookies will still be forwarded to the
5077 appropriate server.
5078
5079 Note that contrary to a common belief, this option does NOT make HAProxy
5080 present the client's IP to the server when establishing the connection.
5081
Willy Tarreaua1146052011-03-01 09:51:54 +01005082 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005083 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01005084
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005085
Emeric Brun647caf12009-06-30 17:57:00 +02005086persist rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02005087persist rdp-cookie(<name>)
Emeric Brun647caf12009-06-30 17:57:00 +02005088 Enable RDP cookie-based persistence
5089 May be used in sections : defaults | frontend | listen | backend
5090 yes | no | yes | yes
5091 Arguments :
5092 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02005093 default cookie name "msts" will be used. There currently is no
5094 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02005095
5096 This statement enables persistence based on an RDP cookie. The RDP cookie
5097 contains all information required to find the server in the list of known
5098 servers. So when this option is set in the backend, the request is analysed
5099 and if an RDP cookie is found, it is decoded. If it matches a known server
5100 which is still UP (or if "option persist" is set), then the connection is
5101 forwarded to this server.
5102
5103 Note that this only makes sense in a TCP backend, but for this to work, the
5104 frontend must have waited long enough to ensure that an RDP cookie is present
5105 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005106 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02005107 a single "listen" section.
5108
Willy Tarreau61e28f22010-05-16 22:31:05 +02005109 Also, it is important to understand that the terminal server will emit this
5110 RDP cookie only if it is configured for "token redirection mode", which means
5111 that the "IP address redirection" option is disabled.
5112
Emeric Brun647caf12009-06-30 17:57:00 +02005113 Example :
5114 listen tse-farm
5115 bind :3389
5116 # wait up to 5s for an RDP cookie in the request
5117 tcp-request inspect-delay 5s
5118 tcp-request content accept if RDP_COOKIE
5119 # apply RDP cookie persistence
5120 persist rdp-cookie
5121 # if server is unknown, let's balance on the same cookie.
Cyril Bontédc4d9032012-04-08 21:57:39 +02005122 # alternatively, "balance leastconn" may be useful too.
Emeric Brun647caf12009-06-30 17:57:00 +02005123 balance rdp-cookie
5124 server srv1 1.1.1.1:3389
5125 server srv2 1.1.1.2:3389
5126
Simon Hormanab814e02011-06-24 14:50:20 +09005127 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
5128 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02005129
5130
Willy Tarreau3a7d2072009-03-05 23:48:25 +01005131rate-limit sessions <rate>
5132 Set a limit on the number of new sessions accepted per second on a frontend
5133 May be used in sections : defaults | frontend | listen | backend
5134 yes | yes | yes | no
5135 Arguments :
5136 <rate> The <rate> parameter is an integer designating the maximum number
5137 of new sessions per second to accept on the frontend.
5138
5139 When the frontend reaches the specified number of new sessions per second, it
5140 stops accepting new connections until the rate drops below the limit again.
5141 During this time, the pending sessions will be kept in the socket's backlog
5142 (in system buffers) and haproxy will not even be aware that sessions are
5143 pending. When applying very low limit on a highly loaded service, it may make
5144 sense to increase the socket's backlog using the "backlog" keyword.
5145
5146 This feature is particularly efficient at blocking connection-based attacks
5147 or service abuse on fragile servers. Since the session rate is measured every
5148 millisecond, it is extremely accurate. Also, the limit applies immediately,
5149 no delay is needed at all to detect the threshold.
5150
5151 Example : limit the connection rate on SMTP to 10 per second max
5152 listen smtp
5153 mode tcp
5154 bind :25
5155 rate-limit sessions 10
5156 server 127.0.0.1:1025
5157
Willy Tarreaua17c2d92011-07-25 08:16:20 +02005158 Note : when the maximum rate is reached, the frontend's status is not changed
5159 but its sockets appear as "WAITING" in the statistics if the
5160 "socket-stats" option is enabled.
Willy Tarreau3a7d2072009-03-05 23:48:25 +01005161
5162 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
5163
5164
Willy Tarreau2e1dca82012-09-12 08:43:15 +02005165redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
5166redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
5167redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02005168 Return an HTTP redirection if/unless a condition is matched
5169 May be used in sections : defaults | frontend | listen | backend
5170 no | yes | yes | yes
5171
5172 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01005173 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02005174
Willy Tarreau0140f252008-11-19 21:07:09 +01005175 Arguments :
Willy Tarreau2e1dca82012-09-12 08:43:15 +02005176 <loc> With "redirect location", the exact value in <loc> is placed into
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01005177 the HTTP "Location" header. When used in an "http-request" rule,
5178 <loc> value follows the log-format rules and can include some
5179 dynamic values (see Custom Log Format in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02005180
5181 <pfx> With "redirect prefix", the "Location" header is built from the
5182 concatenation of <pfx> and the complete URI path, including the
5183 query string, unless the "drop-query" option is specified (see
5184 below). As a special case, if <pfx> equals exactly "/", then
5185 nothing is inserted before the original URI. It allows one to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01005186 redirect to the same URL (for instance, to insert a cookie). When
5187 used in an "http-request" rule, <pfx> value follows the log-format
5188 rules and can include some dynamic values (see Custom Log Format
5189 in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02005190
5191 <sch> With "redirect scheme", then the "Location" header is built by
5192 concatenating <sch> with "://" then the first occurrence of the
5193 "Host" header, and then the URI path, including the query string
5194 unless the "drop-query" option is specified (see below). If no
5195 path is found or if the path is "*", then "/" is used instead. If
5196 no "Host" header is found, then an empty host component will be
5197 returned, which most recent browsers interprete as redirecting to
5198 the same host. This directive is mostly used to redirect HTTP to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01005199 HTTPS. When used in an "http-request" rule, <sch> value follows
5200 the log-format rules and can include some dynamic values (see
5201 Custom Log Format in section 8.2.4).
Willy Tarreau0140f252008-11-19 21:07:09 +01005202
5203 <code> The code is optional. It indicates which type of HTTP redirection
Willy Tarreaub67fdc42013-03-29 19:28:11 +01005204 is desired. Only codes 301, 302, 303, 307 and 308 are supported,
5205 with 302 used by default if no code is specified. 301 means
5206 "Moved permanently", and a browser may cache the Location. 302
5207 means "Moved permanently" and means that the browser should not
5208 cache the redirection. 303 is equivalent to 302 except that the
5209 browser will fetch the location with a GET method. 307 is just
5210 like 302 but makes it clear that the same method must be reused.
5211 Likewise, 308 replaces 301 if the same method must be used.
Willy Tarreau0140f252008-11-19 21:07:09 +01005212
5213 <option> There are several options which can be specified to adjust the
5214 expected behaviour of a redirection :
5215
5216 - "drop-query"
5217 When this keyword is used in a prefix-based redirection, then the
5218 location will be set without any possible query-string, which is useful
5219 for directing users to a non-secure page for instance. It has no effect
5220 with a location-type redirect.
5221
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01005222 - "append-slash"
5223 This keyword may be used in conjunction with "drop-query" to redirect
5224 users who use a URL not ending with a '/' to the same one with the '/'.
5225 It can be useful to ensure that search engines will only see one URL.
5226 For this, a return code 301 is preferred.
5227
Willy Tarreau0140f252008-11-19 21:07:09 +01005228 - "set-cookie NAME[=value]"
5229 A "Set-Cookie" header will be added with NAME (and optionally "=value")
5230 to the response. This is sometimes used to indicate that a user has
5231 been seen, for instance to protect against some types of DoS. No other
5232 cookie option is added, so the cookie will be a session cookie. Note
5233 that for a browser, a sole cookie name without an equal sign is
5234 different from a cookie with an equal sign.
5235
5236 - "clear-cookie NAME[=]"
5237 A "Set-Cookie" header will be added with NAME (and optionally "="), but
5238 with the "Max-Age" attribute set to zero. This will tell the browser to
5239 delete this cookie. It is useful for instance on logout pages. It is
5240 important to note that clearing the cookie "NAME" will not remove a
5241 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
5242 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02005243
5244 Example: move the login URL only to HTTPS.
5245 acl clear dst_port 80
5246 acl secure dst_port 8080
5247 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01005248 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01005249 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01005250 acl cookie_set hdr_sub(cookie) SEEN=1
5251
5252 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01005253 redirect prefix https://mysite.com if login_page !secure
5254 redirect prefix http://mysite.com drop-query if login_page !uid_given
5255 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01005256 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02005257
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01005258 Example: send redirects for request for articles without a '/'.
5259 acl missing_slash path_reg ^/article/[^/]*$
5260 redirect code 301 prefix / drop-query append-slash if missing_slash
5261
Willy Tarreau2e1dca82012-09-12 08:43:15 +02005262 Example: redirect all HTTP traffic to HTTPS when SSL is handled by haproxy.
David BERARDe7153042012-11-03 00:11:31 +01005263 redirect scheme https if !{ ssl_fc }
Willy Tarreau2e1dca82012-09-12 08:43:15 +02005264
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01005265 Example: append 'www.' prefix in front of all hosts not having it
5266 http-request redirect code 301 location www.%[hdr(host)]%[req.uri] \
5267 unless { hdr_beg(host) -i www }
5268
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005269 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02005270
5271
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005272redisp (deprecated)
5273redispatch (deprecated)
5274 Enable or disable session redistribution in case of connection failure
5275 May be used in sections: defaults | frontend | listen | backend
5276 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005277 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005278
5279 In HTTP mode, if a server designated by a cookie is down, clients may
5280 definitely stick to it because they cannot flush the cookie, so they will not
5281 be able to access the service anymore.
5282
5283 Specifying "redispatch" will allow the proxy to break their persistence and
5284 redistribute them to a working server.
5285
5286 It also allows to retry last connection to another server in case of multiple
5287 connection failures. Of course, it requires having "retries" set to a nonzero
5288 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01005289
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005290 This form is deprecated, do not use it in any new configuration, use the new
5291 "option redispatch" instead.
5292
5293 See also : "option redispatch"
5294
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005295
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01005296reqadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01005297 Add a header at the end of the HTTP request
5298 May be used in sections : defaults | frontend | listen | backend
5299 no | yes | yes | yes
5300 Arguments :
5301 <string> is the complete line to be added. Any space or known delimiter
5302 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005303 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01005304
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01005305 <cond> is an optional matching condition built from ACLs. It makes it
5306 possible to ignore this rule when other conditions are not met.
5307
Willy Tarreau303c0352008-01-17 19:01:39 +01005308 A new line consisting in <string> followed by a line feed will be added after
5309 the last header of an HTTP request.
5310
5311 Header transformations only apply to traffic which passes through HAProxy,
5312 and not to traffic generated by HAProxy, such as health-checks or error
5313 responses.
5314
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01005315 Example : add "X-Proto: SSL" to requests coming via port 81
5316 acl is-ssl dst_port 81
5317 reqadd X-Proto:\ SSL if is-ssl
5318
5319 See also: "rspadd", section 6 about HTTP header manipulation, and section 7
5320 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005321
5322
Willy Tarreau5321c422010-01-28 20:35:13 +01005323reqallow <search> [{if | unless} <cond>]
5324reqiallow <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01005325 Definitely allow an HTTP request if a line matches a regular expression
5326 May be used in sections : defaults | frontend | listen | backend
5327 no | yes | yes | yes
5328 Arguments :
5329 <search> is the regular expression applied to HTTP headers and to the
5330 request line. This is an extended regular expression. Parenthesis
5331 grouping is supported and no preliminary backslash is required.
5332 Any space or known delimiter must be escaped using a backslash
5333 ('\'). The pattern applies to a full line at a time. The
5334 "reqallow" keyword strictly matches case while "reqiallow"
5335 ignores case.
5336
Willy Tarreau5321c422010-01-28 20:35:13 +01005337 <cond> is an optional matching condition built from ACLs. It makes it
5338 possible to ignore this rule when other conditions are not met.
5339
Willy Tarreau303c0352008-01-17 19:01:39 +01005340 A request containing any line which matches extended regular expression
5341 <search> will mark the request as allowed, even if any later test would
5342 result in a deny. The test applies both to the request line and to request
5343 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01005344 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01005345
5346 It is easier, faster and more powerful to use ACLs to write access policies.
5347 Reqdeny, reqallow and reqpass should be avoided in new designs.
5348
5349 Example :
5350 # allow www.* but refuse *.local
5351 reqiallow ^Host:\ www\.
5352 reqideny ^Host:\ .*\.local
5353
Willy Tarreau5321c422010-01-28 20:35:13 +01005354 See also: "reqdeny", "block", section 6 about HTTP header manipulation, and
5355 section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005356
5357
Willy Tarreau5321c422010-01-28 20:35:13 +01005358reqdel <search> [{if | unless} <cond>]
5359reqidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01005360 Delete all headers matching a regular expression in an HTTP request
5361 May be used in sections : defaults | frontend | listen | backend
5362 no | yes | yes | yes
5363 Arguments :
5364 <search> is the regular expression applied to HTTP headers and to the
5365 request line. This is an extended regular expression. Parenthesis
5366 grouping is supported and no preliminary backslash is required.
5367 Any space or known delimiter must be escaped using a backslash
5368 ('\'). The pattern applies to a full line at a time. The "reqdel"
5369 keyword strictly matches case while "reqidel" ignores case.
5370
Willy Tarreau5321c422010-01-28 20:35:13 +01005371 <cond> is an optional matching condition built from ACLs. It makes it
5372 possible to ignore this rule when other conditions are not met.
5373
Willy Tarreau303c0352008-01-17 19:01:39 +01005374 Any header line matching extended regular expression <search> in the request
5375 will be completely deleted. Most common use of this is to remove unwanted
5376 and/or dangerous headers or cookies from a request before passing it to the
5377 next servers.
5378
5379 Header transformations only apply to traffic which passes through HAProxy,
5380 and not to traffic generated by HAProxy, such as health-checks or error
5381 responses. Keep in mind that header names are not case-sensitive.
5382
5383 Example :
5384 # remove X-Forwarded-For header and SERVER cookie
5385 reqidel ^X-Forwarded-For:.*
5386 reqidel ^Cookie:.*SERVER=
5387
Willy Tarreau5321c422010-01-28 20:35:13 +01005388 See also: "reqadd", "reqrep", "rspdel", section 6 about HTTP header
5389 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005390
5391
Willy Tarreau5321c422010-01-28 20:35:13 +01005392reqdeny <search> [{if | unless} <cond>]
5393reqideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01005394 Deny an HTTP request if a line matches a regular expression
5395 May be used in sections : defaults | frontend | listen | backend
5396 no | yes | yes | yes
5397 Arguments :
5398 <search> is the regular expression applied to HTTP headers and to the
5399 request line. This is an extended regular expression. Parenthesis
5400 grouping is supported and no preliminary backslash is required.
5401 Any space or known delimiter must be escaped using a backslash
5402 ('\'). The pattern applies to a full line at a time. The
5403 "reqdeny" keyword strictly matches case while "reqideny" ignores
5404 case.
5405
Willy Tarreau5321c422010-01-28 20:35:13 +01005406 <cond> is an optional matching condition built from ACLs. It makes it
5407 possible to ignore this rule when other conditions are not met.
5408
Willy Tarreau303c0352008-01-17 19:01:39 +01005409 A request containing any line which matches extended regular expression
5410 <search> will mark the request as denied, even if any later test would
5411 result in an allow. The test applies both to the request line and to request
5412 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01005413 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01005414
Willy Tarreauced27012008-01-17 20:35:34 +01005415 A denied request will generate an "HTTP 403 forbidden" response once the
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01005416 complete request has been parsed. This is consistent with what is practiced
Willy Tarreaud72758d2010-01-12 10:42:19 +01005417 using ACLs.
Willy Tarreauced27012008-01-17 20:35:34 +01005418
Willy Tarreau303c0352008-01-17 19:01:39 +01005419 It is easier, faster and more powerful to use ACLs to write access policies.
5420 Reqdeny, reqallow and reqpass should be avoided in new designs.
5421
5422 Example :
5423 # refuse *.local, then allow www.*
5424 reqideny ^Host:\ .*\.local
5425 reqiallow ^Host:\ www\.
5426
Willy Tarreau5321c422010-01-28 20:35:13 +01005427 See also: "reqallow", "rspdeny", "block", section 6 about HTTP header
5428 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005429
5430
Willy Tarreau5321c422010-01-28 20:35:13 +01005431reqpass <search> [{if | unless} <cond>]
5432reqipass <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01005433 Ignore any HTTP request line matching a regular expression in next rules
5434 May be used in sections : defaults | frontend | listen | backend
5435 no | yes | yes | yes
5436 Arguments :
5437 <search> is the regular expression applied to HTTP headers and to the
5438 request line. This is an extended regular expression. Parenthesis
5439 grouping is supported and no preliminary backslash is required.
5440 Any space or known delimiter must be escaped using a backslash
5441 ('\'). The pattern applies to a full line at a time. The
5442 "reqpass" keyword strictly matches case while "reqipass" ignores
5443 case.
5444
Willy Tarreau5321c422010-01-28 20:35:13 +01005445 <cond> is an optional matching condition built from ACLs. It makes it
5446 possible to ignore this rule when other conditions are not met.
5447
Willy Tarreau303c0352008-01-17 19:01:39 +01005448 A request containing any line which matches extended regular expression
5449 <search> will skip next rules, without assigning any deny or allow verdict.
5450 The test applies both to the request line and to request headers. Keep in
5451 mind that URLs in request line are case-sensitive while header names are not.
5452
5453 It is easier, faster and more powerful to use ACLs to write access policies.
5454 Reqdeny, reqallow and reqpass should be avoided in new designs.
5455
5456 Example :
5457 # refuse *.local, then allow www.*, but ignore "www.private.local"
5458 reqipass ^Host:\ www.private\.local
5459 reqideny ^Host:\ .*\.local
5460 reqiallow ^Host:\ www\.
5461
Willy Tarreau5321c422010-01-28 20:35:13 +01005462 See also: "reqallow", "reqdeny", "block", section 6 about HTTP header
5463 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005464
5465
Willy Tarreau5321c422010-01-28 20:35:13 +01005466reqrep <search> <string> [{if | unless} <cond>]
5467reqirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01005468 Replace a regular expression with a string in an HTTP request line
5469 May be used in sections : defaults | frontend | listen | backend
5470 no | yes | yes | yes
5471 Arguments :
5472 <search> is the regular expression applied to HTTP headers and to the
5473 request line. This is an extended regular expression. Parenthesis
5474 grouping is supported and no preliminary backslash is required.
5475 Any space or known delimiter must be escaped using a backslash
5476 ('\'). The pattern applies to a full line at a time. The "reqrep"
5477 keyword strictly matches case while "reqirep" ignores case.
5478
5479 <string> is the complete line to be added. Any space or known delimiter
5480 must be escaped using a backslash ('\'). References to matched
5481 pattern groups are possible using the common \N form, with N
5482 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005483 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01005484
Willy Tarreau5321c422010-01-28 20:35:13 +01005485 <cond> is an optional matching condition built from ACLs. It makes it
5486 possible to ignore this rule when other conditions are not met.
5487
Willy Tarreau303c0352008-01-17 19:01:39 +01005488 Any line matching extended regular expression <search> in the request (both
5489 the request line and header lines) will be completely replaced with <string>.
5490 Most common use of this is to rewrite URLs or domain names in "Host" headers.
5491
5492 Header transformations only apply to traffic which passes through HAProxy,
5493 and not to traffic generated by HAProxy, such as health-checks or error
5494 responses. Note that for increased readability, it is suggested to add enough
5495 spaces between the request and the response. Keep in mind that URLs in
5496 request line are case-sensitive while header names are not.
5497
5498 Example :
5499 # replace "/static/" with "/" at the beginning of any request path.
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04005500 reqrep ^([^\ :]*)\ /static/(.*) \1\ /\2
Willy Tarreau303c0352008-01-17 19:01:39 +01005501 # replace "www.mydomain.com" with "www" in the host name.
5502 reqirep ^Host:\ www.mydomain.com Host:\ www
5503
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +04005504 See also: "reqadd", "reqdel", "rsprep", "tune.bufsize", section 6 about
5505 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005506
5507
Willy Tarreau5321c422010-01-28 20:35:13 +01005508reqtarpit <search> [{if | unless} <cond>]
5509reqitarpit <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01005510 Tarpit an HTTP request containing a line matching a regular expression
5511 May be used in sections : defaults | frontend | listen | backend
5512 no | yes | yes | yes
5513 Arguments :
5514 <search> is the regular expression applied to HTTP headers and to the
5515 request line. This is an extended regular expression. Parenthesis
5516 grouping is supported and no preliminary backslash is required.
5517 Any space or known delimiter must be escaped using a backslash
5518 ('\'). The pattern applies to a full line at a time. The
5519 "reqtarpit" keyword strictly matches case while "reqitarpit"
5520 ignores case.
5521
Willy Tarreau5321c422010-01-28 20:35:13 +01005522 <cond> is an optional matching condition built from ACLs. It makes it
5523 possible to ignore this rule when other conditions are not met.
5524
Willy Tarreau303c0352008-01-17 19:01:39 +01005525 A request containing any line which matches extended regular expression
5526 <search> will be tarpitted, which means that it will connect to nowhere, will
Willy Tarreauced27012008-01-17 20:35:34 +01005527 be kept open for a pre-defined time, then will return an HTTP error 500 so
5528 that the attacker does not suspect it has been tarpitted. The status 500 will
5529 be reported in the logs, but the completion flags will indicate "PT". The
Willy Tarreau303c0352008-01-17 19:01:39 +01005530 delay is defined by "timeout tarpit", or "timeout connect" if the former is
5531 not set.
5532
5533 The goal of the tarpit is to slow down robots attacking servers with
5534 identifiable requests. Many robots limit their outgoing number of connections
5535 and stay connected waiting for a reply which can take several minutes to
5536 come. Depending on the environment and attack, it may be particularly
5537 efficient at reducing the load on the network and firewalls.
5538
Willy Tarreau5321c422010-01-28 20:35:13 +01005539 Examples :
Willy Tarreau303c0352008-01-17 19:01:39 +01005540 # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but
5541 # block all others.
5542 reqipass ^User-Agent:\.*(Mozilla|MSIE)
5543 reqitarpit ^User-Agent:
5544
Willy Tarreau5321c422010-01-28 20:35:13 +01005545 # block bad guys
5546 acl badguys src 10.1.0.3 172.16.13.20/28
5547 reqitarpit . if badguys
5548
5549 See also: "reqallow", "reqdeny", "reqpass", section 6 about HTTP header
5550 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005551
5552
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02005553retries <value>
5554 Set the number of retries to perform on a server after a connection failure
5555 May be used in sections: defaults | frontend | listen | backend
5556 yes | no | yes | yes
5557 Arguments :
5558 <value> is the number of times a connection attempt should be retried on
5559 a server when a connection either is refused or times out. The
5560 default value is 3.
5561
5562 It is important to understand that this value applies to the number of
5563 connection attempts, not full requests. When a connection has effectively
5564 been established to a server, there will be no more retry.
5565
5566 In order to avoid immediate reconnections to a server which is restarting,
5567 a turn-around timer of 1 second is applied before a retry occurs.
5568
5569 When "option redispatch" is set, the last retry may be performed on another
5570 server even if a cookie references a different server.
5571
5572 See also : "option redispatch"
5573
5574
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005575rspadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01005576 Add a header at the end of the HTTP response
5577 May be used in sections : defaults | frontend | listen | backend
5578 no | yes | yes | yes
5579 Arguments :
5580 <string> is the complete line to be added. Any space or known delimiter
5581 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005582 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01005583
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005584 <cond> is an optional matching condition built from ACLs. It makes it
5585 possible to ignore this rule when other conditions are not met.
5586
Willy Tarreau303c0352008-01-17 19:01:39 +01005587 A new line consisting in <string> followed by a line feed will be added after
5588 the last header of an HTTP response.
5589
5590 Header transformations only apply to traffic which passes through HAProxy,
5591 and not to traffic generated by HAProxy, such as health-checks or error
5592 responses.
5593
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005594 See also: "reqadd", section 6 about HTTP header manipulation, and section 7
5595 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005596
5597
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005598rspdel <search> [{if | unless} <cond>]
5599rspidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01005600 Delete all headers matching a regular expression in an HTTP response
5601 May be used in sections : defaults | frontend | listen | backend
5602 no | yes | yes | yes
5603 Arguments :
5604 <search> is the regular expression applied to HTTP headers and to the
5605 response line. This is an extended regular expression, so
5606 parenthesis grouping is supported and no preliminary backslash
5607 is required. Any space or known delimiter must be escaped using
5608 a backslash ('\'). The pattern applies to a full line at a time.
5609 The "rspdel" keyword strictly matches case while "rspidel"
5610 ignores case.
5611
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005612 <cond> is an optional matching condition built from ACLs. It makes it
5613 possible to ignore this rule when other conditions are not met.
5614
Willy Tarreau303c0352008-01-17 19:01:39 +01005615 Any header line matching extended regular expression <search> in the response
5616 will be completely deleted. Most common use of this is to remove unwanted
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02005617 and/or sensitive headers or cookies from a response before passing it to the
Willy Tarreau303c0352008-01-17 19:01:39 +01005618 client.
5619
5620 Header transformations only apply to traffic which passes through HAProxy,
5621 and not to traffic generated by HAProxy, such as health-checks or error
5622 responses. Keep in mind that header names are not case-sensitive.
5623
5624 Example :
5625 # remove the Server header from responses
Willy Tarreau5e80e022013-05-25 08:31:25 +02005626 rspidel ^Server:.*
Willy Tarreau303c0352008-01-17 19:01:39 +01005627
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005628 See also: "rspadd", "rsprep", "reqdel", section 6 about HTTP header
5629 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005630
5631
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005632rspdeny <search> [{if | unless} <cond>]
5633rspideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01005634 Block an HTTP response if a line matches a regular expression
5635 May be used in sections : defaults | frontend | listen | backend
5636 no | yes | yes | yes
5637 Arguments :
5638 <search> is the regular expression applied to HTTP headers and to the
5639 response line. This is an extended regular expression, so
5640 parenthesis grouping is supported and no preliminary backslash
5641 is required. Any space or known delimiter must be escaped using
5642 a backslash ('\'). The pattern applies to a full line at a time.
5643 The "rspdeny" keyword strictly matches case while "rspideny"
5644 ignores case.
5645
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005646 <cond> is an optional matching condition built from ACLs. It makes it
5647 possible to ignore this rule when other conditions are not met.
5648
Willy Tarreau303c0352008-01-17 19:01:39 +01005649 A response containing any line which matches extended regular expression
5650 <search> will mark the request as denied. The test applies both to the
5651 response line and to response headers. Keep in mind that header names are not
5652 case-sensitive.
5653
5654 Main use of this keyword is to prevent sensitive information leak and to
Willy Tarreauced27012008-01-17 20:35:34 +01005655 block the response before it reaches the client. If a response is denied, it
5656 will be replaced with an HTTP 502 error so that the client never retrieves
5657 any sensitive data.
Willy Tarreau303c0352008-01-17 19:01:39 +01005658
5659 It is easier, faster and more powerful to use ACLs to write access policies.
5660 Rspdeny should be avoided in new designs.
5661
5662 Example :
5663 # Ensure that no content type matching ms-word will leak
5664 rspideny ^Content-type:\.*/ms-word
5665
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005666 See also: "reqdeny", "acl", "block", section 6 about HTTP header manipulation
5667 and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005668
5669
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005670rsprep <search> <string> [{if | unless} <cond>]
5671rspirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01005672 Replace a regular expression with a string in an HTTP response line
5673 May be used in sections : defaults | frontend | listen | backend
5674 no | yes | yes | yes
5675 Arguments :
5676 <search> is the regular expression applied to HTTP headers and to the
5677 response line. This is an extended regular expression, so
5678 parenthesis grouping is supported and no preliminary backslash
5679 is required. Any space or known delimiter must be escaped using
5680 a backslash ('\'). The pattern applies to a full line at a time.
5681 The "rsprep" keyword strictly matches case while "rspirep"
5682 ignores case.
5683
5684 <string> is the complete line to be added. Any space or known delimiter
5685 must be escaped using a backslash ('\'). References to matched
5686 pattern groups are possible using the common \N form, with N
5687 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005688 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01005689
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005690 <cond> is an optional matching condition built from ACLs. It makes it
5691 possible to ignore this rule when other conditions are not met.
5692
Willy Tarreau303c0352008-01-17 19:01:39 +01005693 Any line matching extended regular expression <search> in the response (both
5694 the response line and header lines) will be completely replaced with
5695 <string>. Most common use of this is to rewrite Location headers.
5696
5697 Header transformations only apply to traffic which passes through HAProxy,
5698 and not to traffic generated by HAProxy, such as health-checks or error
5699 responses. Note that for increased readability, it is suggested to add enough
5700 spaces between the request and the response. Keep in mind that header names
5701 are not case-sensitive.
5702
5703 Example :
5704 # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com"
5705 rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com
5706
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005707 See also: "rspadd", "rspdel", "reqrep", section 6 about HTTP header
5708 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005709
5710
David du Colombier486df472011-03-17 10:40:26 +01005711server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005712 Declare a server in a backend
5713 May be used in sections : defaults | frontend | listen | backend
5714 no | no | yes | yes
5715 Arguments :
5716 <name> is the internal name assigned to this server. This name will
Cyril Bonté941a0c62012-10-15 19:44:24 +02005717 appear in logs and alerts. If "http-send-name-header" is
Mark Lamourinec2247f02012-01-04 13:02:01 -05005718 set, it will be added to the request header sent to the server.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005719
David du Colombier486df472011-03-17 10:40:26 +01005720 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
5721 resolvable hostname is supported, but this name will be resolved
5722 during start-up. Address "0.0.0.0" or "*" has a special meaning.
5723 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +02005724 address as the one from the client connection. This is useful in
5725 transparent proxy architectures where the client's connection is
5726 intercepted and haproxy must forward to the original destination
5727 address. This is more or less what the "transparent" keyword does
5728 except that with a server it's possible to limit concurrency and
Willy Tarreau24709282013-03-10 21:32:12 +01005729 to report statistics. Optionally, an address family prefix may be
5730 used before the address to force the family regardless of the
5731 address format, which can be useful to specify a path to a unix
5732 socket with no slash ('/'). Currently supported prefixes are :
5733 - 'ipv4@' -> address is always IPv4
5734 - 'ipv6@' -> address is always IPv6
5735 - 'unix@' -> address is a path to a local unix socket
Willy Tarreaudad36a32013-03-11 01:20:04 +01005736 Any part of the address string may reference any number of
5737 environment variables by preceding their name with a dollar
5738 sign ('$') and optionally enclosing them with braces ('{}'),
5739 similarly to what is done in Bourne shell.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005740
Willy Tarreaub6205fd2012-09-24 12:27:33 +02005741 <port> is an optional port specification. If set, all connections will
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005742 be sent to this port. If unset, the same port the client
5743 connected to will be used. The port may also be prefixed by a "+"
5744 or a "-". In this case, the server's port will be determined by
5745 adding this value to the client's port.
5746
5747 <param*> is a list of parameters for this server. The "server" keywords
5748 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005749 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005750
5751 Examples :
5752 server first 10.1.1.1:1080 cookie first check inter 1000
5753 server second 10.1.1.2:1080 cookie second check inter 1000
Willy Tarreau24709282013-03-10 21:32:12 +01005754 server transp ipv4@
Willy Tarreaudad36a32013-03-11 01:20:04 +01005755 server backup ${SRV_BACKUP}:1080 backup
5756 server www1_dc1 ${LAN_DC1}.101:80
5757 server www1_dc2 ${LAN_DC2}.101:80
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005758
Mark Lamourinec2247f02012-01-04 13:02:01 -05005759 See also: "default-server", "http-send-name-header" and section 5 about
5760 server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005761
5762
5763source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02005764source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01005765source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005766 Set the source address for outgoing connections
5767 May be used in sections : defaults | frontend | listen | backend
5768 yes | no | yes | yes
5769 Arguments :
5770 <addr> is the IPv4 address HAProxy will bind to before connecting to a
5771 server. This address is also used as a source for health checks.
Willy Tarreau24709282013-03-10 21:32:12 +01005772
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005773 The default value of 0.0.0.0 means that the system will select
Willy Tarreau24709282013-03-10 21:32:12 +01005774 the most appropriate address to reach its destination. Optionally
5775 an address family prefix may be used before the address to force
5776 the family regardless of the address format, which can be useful
5777 to specify a path to a unix socket with no slash ('/'). Currently
5778 supported prefixes are :
5779 - 'ipv4@' -> address is always IPv4
5780 - 'ipv6@' -> address is always IPv6
5781 - 'unix@' -> address is a path to a local unix socket
Willy Tarreaudad36a32013-03-11 01:20:04 +01005782 Any part of the address string may reference any number of
5783 environment variables by preceding their name with a dollar
5784 sign ('$') and optionally enclosing them with braces ('{}'),
5785 similarly to what is done in Bourne shell.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005786
5787 <port> is an optional port. It is normally not needed but may be useful
5788 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02005789 the system will select a free port. Note that port ranges are not
5790 supported in the backend. If you want to force port ranges, you
5791 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005792
5793 <addr2> is the IP address to present to the server when connections are
5794 forwarded in full transparent proxy mode. This is currently only
5795 supported on some patched Linux kernels. When this address is
5796 specified, clients connecting to the server will be presented
5797 with this address, while health checks will still use the address
5798 <addr>.
5799
5800 <port2> is the optional port to present to the server when connections
5801 are forwarded in full transparent proxy mode (see <addr2> above).
5802 The default value of zero means the system will select a free
5803 port.
5804
Willy Tarreaubce70882009-09-07 11:51:47 +02005805 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
5806 This is the name of a comma-separated header list which can
5807 contain multiple IP addresses. By default, the last occurrence is
5808 used. This is designed to work with the X-Forwarded-For header
Baptiste Assmannea3e73b2013-02-02 23:47:49 +01005809 and to automatically bind to the client's IP address as seen
Willy Tarreaubce70882009-09-07 11:51:47 +02005810 by previous proxy, typically Stunnel. In order to use another
5811 occurrence from the last one, please see the <occ> parameter
5812 below. When the header (or occurrence) is not found, no binding
5813 is performed so that the proxy's default IP address is used. Also
5814 keep in mind that the header name is case insensitive, as for any
5815 HTTP header.
5816
5817 <occ> is the occurrence number of a value to be used in a multi-value
5818 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04005819 in order to specify which occurrence to use for the source IP
Willy Tarreaubce70882009-09-07 11:51:47 +02005820 address. Positive values indicate a position from the first
5821 occurrence, 1 being the first one. Negative values indicate
5822 positions relative to the last one, -1 being the last one. This
5823 is helpful for situations where an X-Forwarded-For header is set
5824 at the entry point of an infrastructure and must be used several
5825 proxy layers away. When this value is not specified, -1 is
5826 assumed. Passing a zero here disables the feature.
5827
Willy Tarreaud53f96b2009-02-04 18:46:54 +01005828 <name> is an optional interface name to which to bind to for outgoing
5829 traffic. On systems supporting this features (currently, only
5830 Linux), this allows one to bind all traffic to the server to
5831 this interface even if it is not the one the system would select
5832 based on routing tables. This should be used with extreme care.
5833 Note that using this option requires root privileges.
5834
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005835 The "source" keyword is useful in complex environments where a specific
5836 address only is allowed to connect to the servers. It may be needed when a
5837 private address must be used through a public gateway for instance, and it is
5838 known that the system cannot determine the adequate source address by itself.
5839
5840 An extension which is available on certain patched Linux kernels may be used
5841 through the "usesrc" optional keyword. It makes it possible to connect to the
5842 servers with an IP address which does not belong to the system itself. This
5843 is called "full transparent proxy mode". For this to work, the destination
5844 servers have to route their traffic back to this address through the machine
5845 running HAProxy, and IP forwarding must generally be enabled on this machine.
5846
5847 In this "full transparent proxy" mode, it is possible to force a specific IP
5848 address to be presented to the servers. This is not much used in fact. A more
5849 common use is to tell HAProxy to present the client's IP address. For this,
5850 there are two methods :
5851
5852 - present the client's IP and port addresses. This is the most transparent
5853 mode, but it can cause problems when IP connection tracking is enabled on
5854 the machine, because a same connection may be seen twice with different
5855 states. However, this solution presents the huge advantage of not
5856 limiting the system to the 64k outgoing address+port couples, because all
5857 of the client ranges may be used.
5858
5859 - present only the client's IP address and select a spare port. This
5860 solution is still quite elegant but slightly less transparent (downstream
5861 firewalls logs will not match upstream's). It also presents the downside
5862 of limiting the number of concurrent connections to the usual 64k ports.
5863 However, since the upstream and downstream ports are different, local IP
5864 connection tracking on the machine will not be upset by the reuse of the
5865 same session.
5866
5867 Note that depending on the transparent proxy technology used, it may be
5868 required to force the source address. In fact, cttproxy version 2 requires an
5869 IP address in <addr> above, and does not support setting of "0.0.0.0" as the
5870 IP address because it creates NAT entries which much match the exact outgoing
5871 address. Tproxy version 4 and some other kernel patches which work in pure
5872 forwarding mode generally will not have this limitation.
5873
5874 This option sets the default source for all servers in the backend. It may
5875 also be specified in a "defaults" section. Finer source address specification
5876 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005877 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005878
5879 Examples :
5880 backend private
5881 # Connect to the servers using our 192.168.1.200 source address
5882 source 192.168.1.200
5883
5884 backend transparent_ssl1
5885 # Connect to the SSL farm from the client's source address
5886 source 192.168.1.200 usesrc clientip
5887
5888 backend transparent_ssl2
5889 # Connect to the SSL farm from the client's source address and port
5890 # not recommended if IP conntrack is present on the local machine.
5891 source 192.168.1.200 usesrc client
5892
5893 backend transparent_ssl3
5894 # Connect to the SSL farm from the client's source address. It
5895 # is more conntrack-friendly.
5896 source 192.168.1.200 usesrc clientip
5897
5898 backend transparent_smtp
5899 # Connect to the SMTP farm from the client's source address/port
5900 # with Tproxy version 4.
5901 source 0.0.0.0 usesrc clientip
5902
Willy Tarreaubce70882009-09-07 11:51:47 +02005903 backend transparent_http
5904 # Connect to the servers using the client's IP as seen by previous
5905 # proxy.
5906 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
5907
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005908 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005909 the Linux kernel on www.balabit.com, the "bind" keyword.
5910
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005911
Willy Tarreau844e3c52008-01-11 16:28:18 +01005912srvtimeout <timeout> (deprecated)
5913 Set the maximum inactivity time on the server side.
5914 May be used in sections : defaults | frontend | listen | backend
5915 yes | no | yes | yes
5916 Arguments :
5917 <timeout> is the timeout value specified in milliseconds by default, but
5918 can be in any other unit if the number is suffixed by the unit,
5919 as explained at the top of this document.
5920
5921 The inactivity timeout applies when the server is expected to acknowledge or
5922 send data. In HTTP mode, this timeout is particularly important to consider
5923 during the first phase of the server's response, when it has to send the
5924 headers, as it directly represents the server's processing time for the
5925 request. To find out what value to put there, it's often good to start with
5926 what would be considered as unacceptable response times, then check the logs
5927 to observe the response time distribution, and adjust the value accordingly.
5928
5929 The value is specified in milliseconds by default, but can be in any other
5930 unit if the number is suffixed by the unit, as specified at the top of this
5931 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
5932 recommended that the client timeout remains equal to the server timeout in
5933 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01005934 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01005935 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreaud72758d2010-01-12 10:42:19 +01005936 seconds (eg: 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01005937
5938 This parameter is specific to backends, but can be specified once for all in
5939 "defaults" sections. This is in fact one of the easiest solutions not to
5940 forget about it. An unspecified timeout results in an infinite timeout, which
5941 is not recommended. Such a usage is accepted and works but reports a warning
5942 during startup because it may results in accumulation of expired sessions in
5943 the system if the system's timeouts are not configured either.
5944
5945 This parameter is provided for compatibility but is currently deprecated.
5946 Please use "timeout server" instead.
5947
Willy Tarreauce887fd2012-05-12 12:50:00 +02005948 See also : "timeout server", "timeout tunnel", "timeout client" and
5949 "clitimeout".
Willy Tarreau844e3c52008-01-11 16:28:18 +01005950
5951
Cyril Bonté66c327d2010-10-12 00:14:37 +02005952stats admin { if | unless } <cond>
5953 Enable statistics admin level if/unless a condition is matched
5954 May be used in sections : defaults | frontend | listen | backend
5955 no | no | yes | yes
5956
5957 This statement enables the statistics admin level if/unless a condition is
5958 matched.
5959
5960 The admin level allows to enable/disable servers from the web interface. By
5961 default, statistics page is read-only for security reasons.
5962
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005963 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5964 unless you know what you do : memory is not shared between the
5965 processes, which can result in random behaviours.
5966
Cyril Bonté23b39d92011-02-10 22:54:44 +01005967 Currently, the POST request is limited to the buffer size minus the reserved
5968 buffer space, which means that if the list of servers is too long, the
5969 request won't be processed. It is recommended to alter few servers at a
5970 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02005971
5972 Example :
5973 # statistics admin level only for localhost
5974 backend stats_localhost
5975 stats enable
5976 stats admin if LOCALHOST
5977
5978 Example :
5979 # statistics admin level always enabled because of the authentication
5980 backend stats_auth
5981 stats enable
5982 stats auth admin:AdMiN123
5983 stats admin if TRUE
5984
5985 Example :
5986 # statistics admin level depends on the authenticated user
5987 userlist stats-auth
5988 group admin users admin
5989 user admin insecure-password AdMiN123
5990 group readonly users haproxy
5991 user haproxy insecure-password haproxy
5992
5993 backend stats_auth
5994 stats enable
5995 acl AUTH http_auth(stats-auth)
5996 acl AUTH_ADMIN http_auth_group(stats-auth) admin
5997 stats http-request auth unless AUTH
5998 stats admin if AUTH_ADMIN
5999
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01006000 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
6001 "bind-process", section 3.4 about userlists and section 7 about
6002 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02006003
6004
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006005stats auth <user>:<passwd>
6006 Enable statistics with authentication and grant access to an account
6007 May be used in sections : defaults | frontend | listen | backend
6008 yes | no | yes | yes
6009 Arguments :
6010 <user> is a user name to grant access to
6011
6012 <passwd> is the cleartext password associated to this user
6013
6014 This statement enables statistics with default settings, and restricts access
6015 to declared users only. It may be repeated as many times as necessary to
6016 allow as many users as desired. When a user tries to access the statistics
6017 without a valid account, a "401 Forbidden" response will be returned so that
6018 the browser asks the user to provide a valid user and password. The real
6019 which will be returned to the browser is configurable using "stats realm".
6020
6021 Since the authentication method is HTTP Basic Authentication, the passwords
6022 circulate in cleartext on the network. Thus, it was decided that the
6023 configuration file would also use cleartext passwords to remind the users
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02006024 that those ones should not be sensitive and not shared with any other account.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006025
6026 It is also possible to reduce the scope of the proxies which appear in the
6027 report using "stats scope".
6028
6029 Though this statement alone is enough to enable statistics reporting, it is
6030 recommended to set all other settings in order to avoid relying on default
6031 unobvious parameters.
6032
6033 Example :
6034 # public access (limited to this backend only)
6035 backend public_www
6036 server srv1 192.168.0.1:80
6037 stats enable
6038 stats hide-version
6039 stats scope .
6040 stats uri /admin?stats
6041 stats realm Haproxy\ Statistics
6042 stats auth admin1:AdMiN123
6043 stats auth admin2:AdMiN321
6044
6045 # internal monitoring access (unlimited)
6046 backend private_monitoring
6047 stats enable
6048 stats uri /admin?stats
6049 stats refresh 5s
6050
6051 See also : "stats enable", "stats realm", "stats scope", "stats uri"
6052
6053
6054stats enable
6055 Enable statistics reporting with default settings
6056 May be used in sections : defaults | frontend | listen | backend
6057 yes | no | yes | yes
6058 Arguments : none
6059
6060 This statement enables statistics reporting with default settings defined
6061 at build time. Unless stated otherwise, these settings are used :
6062 - stats uri : /haproxy?stats
6063 - stats realm : "HAProxy Statistics"
6064 - stats auth : no authentication
6065 - stats scope : no restriction
6066
6067 Though this statement alone is enough to enable statistics reporting, it is
6068 recommended to set all other settings in order to avoid relying on default
6069 unobvious parameters.
6070
6071 Example :
6072 # public access (limited to this backend only)
6073 backend public_www
6074 server srv1 192.168.0.1:80
6075 stats enable
6076 stats hide-version
6077 stats scope .
6078 stats uri /admin?stats
6079 stats realm Haproxy\ Statistics
6080 stats auth admin1:AdMiN123
6081 stats auth admin2:AdMiN321
6082
6083 # internal monitoring access (unlimited)
6084 backend private_monitoring
6085 stats enable
6086 stats uri /admin?stats
6087 stats refresh 5s
6088
6089 See also : "stats auth", "stats realm", "stats uri"
6090
6091
Willy Tarreaud63335a2010-02-26 12:56:52 +01006092stats hide-version
6093 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02006094 May be used in sections : defaults | frontend | listen | backend
6095 yes | no | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01006096 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02006097
Willy Tarreaud63335a2010-02-26 12:56:52 +01006098 By default, the stats page reports some useful status information along with
6099 the statistics. Among them is HAProxy's version. However, it is generally
6100 considered dangerous to report precise version to anyone, as it can help them
6101 target known weaknesses with specific attacks. The "stats hide-version"
6102 statement removes the version from the statistics report. This is recommended
6103 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02006104
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02006105 Though this statement alone is enough to enable statistics reporting, it is
6106 recommended to set all other settings in order to avoid relying on default
6107 unobvious parameters.
6108
Willy Tarreaud63335a2010-02-26 12:56:52 +01006109 Example :
6110 # public access (limited to this backend only)
6111 backend public_www
6112 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02006113 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01006114 stats hide-version
6115 stats scope .
6116 stats uri /admin?stats
6117 stats realm Haproxy\ Statistics
6118 stats auth admin1:AdMiN123
6119 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02006120
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02006121 # internal monitoring access (unlimited)
6122 backend private_monitoring
6123 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01006124 stats uri /admin?stats
6125 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01006126
Willy Tarreaud63335a2010-02-26 12:56:52 +01006127 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02006128
Willy Tarreau983e01e2010-01-11 18:42:06 +01006129
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02006130stats http-request { allow | deny | auth [realm <realm>] }
6131 [ { if | unless } <condition> ]
6132 Access control for statistics
6133
6134 May be used in sections: defaults | frontend | listen | backend
6135 no | no | yes | yes
6136
6137 As "http-request", these set of options allow to fine control access to
6138 statistics. Each option may be followed by if/unless and acl.
6139 First option with matched condition (or option without condition) is final.
6140 For "deny" a 403 error will be returned, for "allow" normal processing is
6141 performed, for "auth" a 401/407 error code is returned so the client
6142 should be asked to enter a username and password.
6143
6144 There is no fixed limit to the number of http-request statements per
6145 instance.
6146
6147 See also : "http-request", section 3.4 about userlists and section 7
6148 about ACL usage.
6149
6150
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006151stats realm <realm>
6152 Enable statistics and set authentication realm
6153 May be used in sections : defaults | frontend | listen | backend
6154 yes | no | yes | yes
6155 Arguments :
6156 <realm> is the name of the HTTP Basic Authentication realm reported to
6157 the browser. The browser uses it to display it in the pop-up
6158 inviting the user to enter a valid username and password.
6159
6160 The realm is read as a single word, so any spaces in it should be escaped
6161 using a backslash ('\').
6162
6163 This statement is useful only in conjunction with "stats auth" since it is
6164 only related to authentication.
6165
6166 Though this statement alone is enough to enable statistics reporting, it is
6167 recommended to set all other settings in order to avoid relying on default
6168 unobvious parameters.
6169
6170 Example :
6171 # public access (limited to this backend only)
6172 backend public_www
6173 server srv1 192.168.0.1:80
6174 stats enable
6175 stats hide-version
6176 stats scope .
6177 stats uri /admin?stats
6178 stats realm Haproxy\ Statistics
6179 stats auth admin1:AdMiN123
6180 stats auth admin2:AdMiN321
6181
6182 # internal monitoring access (unlimited)
6183 backend private_monitoring
6184 stats enable
6185 stats uri /admin?stats
6186 stats refresh 5s
6187
6188 See also : "stats auth", "stats enable", "stats uri"
6189
6190
6191stats refresh <delay>
6192 Enable statistics with automatic refresh
6193 May be used in sections : defaults | frontend | listen | backend
6194 yes | no | yes | yes
6195 Arguments :
6196 <delay> is the suggested refresh delay, specified in seconds, which will
6197 be returned to the browser consulting the report page. While the
6198 browser is free to apply any delay, it will generally respect it
6199 and refresh the page this every seconds. The refresh interval may
6200 be specified in any other non-default time unit, by suffixing the
6201 unit after the value, as explained at the top of this document.
6202
6203 This statement is useful on monitoring displays with a permanent page
6204 reporting the load balancer's activity. When set, the HTML report page will
6205 include a link "refresh"/"stop refresh" so that the user can select whether
6206 he wants automatic refresh of the page or not.
6207
6208 Though this statement alone is enough to enable statistics reporting, it is
6209 recommended to set all other settings in order to avoid relying on default
6210 unobvious parameters.
6211
6212 Example :
6213 # public access (limited to this backend only)
6214 backend public_www
6215 server srv1 192.168.0.1:80
6216 stats enable
6217 stats hide-version
6218 stats scope .
6219 stats uri /admin?stats
6220 stats realm Haproxy\ Statistics
6221 stats auth admin1:AdMiN123
6222 stats auth admin2:AdMiN321
6223
6224 # internal monitoring access (unlimited)
6225 backend private_monitoring
6226 stats enable
6227 stats uri /admin?stats
6228 stats refresh 5s
6229
6230 See also : "stats auth", "stats enable", "stats realm", "stats uri"
6231
6232
6233stats scope { <name> | "." }
6234 Enable statistics and limit access scope
6235 May be used in sections : defaults | frontend | listen | backend
6236 yes | no | yes | yes
6237 Arguments :
6238 <name> is the name of a listen, frontend or backend section to be
6239 reported. The special name "." (a single dot) designates the
6240 section in which the statement appears.
6241
6242 When this statement is specified, only the sections enumerated with this
6243 statement will appear in the report. All other ones will be hidden. This
6244 statement may appear as many times as needed if multiple sections need to be
6245 reported. Please note that the name checking is performed as simple string
6246 comparisons, and that it is never checked that a give section name really
6247 exists.
6248
6249 Though this statement alone is enough to enable statistics reporting, it is
6250 recommended to set all other settings in order to avoid relying on default
6251 unobvious parameters.
6252
6253 Example :
6254 # public access (limited to this backend only)
6255 backend public_www
6256 server srv1 192.168.0.1:80
6257 stats enable
6258 stats hide-version
6259 stats scope .
6260 stats uri /admin?stats
6261 stats realm Haproxy\ Statistics
6262 stats auth admin1:AdMiN123
6263 stats auth admin2:AdMiN321
6264
6265 # internal monitoring access (unlimited)
6266 backend private_monitoring
6267 stats enable
6268 stats uri /admin?stats
6269 stats refresh 5s
6270
6271 See also : "stats auth", "stats enable", "stats realm", "stats uri"
6272
Willy Tarreaud63335a2010-02-26 12:56:52 +01006273
Willy Tarreauc9705a12010-07-27 20:05:50 +02006274stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01006275 Enable reporting of a description on the statistics page.
6276 May be used in sections : defaults | frontend | listen | backend
6277 yes | no | yes | yes
6278
Willy Tarreauc9705a12010-07-27 20:05:50 +02006279 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01006280 description from global section is automatically used instead.
6281
6282 This statement is useful for users that offer shared services to their
6283 customers, where node or description should be different for each customer.
6284
6285 Though this statement alone is enough to enable statistics reporting, it is
6286 recommended to set all other settings in order to avoid relying on default
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04006287 unobvious parameters. By default description is not shown.
Willy Tarreaud63335a2010-02-26 12:56:52 +01006288
6289 Example :
6290 # internal monitoring access (unlimited)
6291 backend private_monitoring
6292 stats enable
6293 stats show-desc Master node for Europe, Asia, Africa
6294 stats uri /admin?stats
6295 stats refresh 5s
6296
6297 See also: "show-node", "stats enable", "stats uri" and "description" in
6298 global section.
6299
6300
6301stats show-legends
6302 Enable reporting additional informations on the statistics page :
6303 - cap: capabilities (proxy)
6304 - mode: one of tcp, http or health (proxy)
6305 - id: SNMP ID (proxy, socket, server)
6306 - IP (socket, server)
6307 - cookie (backend, server)
6308
6309 Though this statement alone is enough to enable statistics reporting, it is
6310 recommended to set all other settings in order to avoid relying on default
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04006311 unobvious parameters. Default behaviour is not to show this information.
Willy Tarreaud63335a2010-02-26 12:56:52 +01006312
6313 See also: "stats enable", "stats uri".
6314
6315
6316stats show-node [ <name> ]
6317 Enable reporting of a host name on the statistics page.
6318 May be used in sections : defaults | frontend | listen | backend
6319 yes | no | yes | yes
6320 Arguments:
6321 <name> is an optional name to be reported. If unspecified, the
6322 node name from global section is automatically used instead.
6323
6324 This statement is useful for users that offer shared services to their
6325 customers, where node or description might be different on a stats page
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04006326 provided for each customer. Default behaviour is not to show host name.
Willy Tarreaud63335a2010-02-26 12:56:52 +01006327
6328 Though this statement alone is enough to enable statistics reporting, it is
6329 recommended to set all other settings in order to avoid relying on default
6330 unobvious parameters.
6331
6332 Example:
6333 # internal monitoring access (unlimited)
6334 backend private_monitoring
6335 stats enable
6336 stats show-node Europe-1
6337 stats uri /admin?stats
6338 stats refresh 5s
6339
6340 See also: "show-desc", "stats enable", "stats uri", and "node" in global
6341 section.
6342
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006343
6344stats uri <prefix>
6345 Enable statistics and define the URI prefix to access them
6346 May be used in sections : defaults | frontend | listen | backend
6347 yes | no | yes | yes
6348 Arguments :
6349 <prefix> is the prefix of any URI which will be redirected to stats. This
6350 prefix may contain a question mark ('?') to indicate part of a
6351 query string.
6352
6353 The statistics URI is intercepted on the relayed traffic, so it appears as a
6354 page within the normal application. It is strongly advised to ensure that the
6355 selected URI will never appear in the application, otherwise it will never be
6356 possible to reach it in the application.
6357
6358 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006359 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006360 It is generally a good idea to include a question mark in the URI so that
6361 intermediate proxies refrain from caching the results. Also, since any string
6362 beginning with the prefix will be accepted as a stats request, the question
6363 mark helps ensuring that no valid URI will begin with the same words.
6364
6365 It is sometimes very convenient to use "/" as the URI prefix, and put that
6366 statement in a "listen" instance of its own. That makes it easy to dedicate
6367 an address or a port to statistics only.
6368
6369 Though this statement alone is enough to enable statistics reporting, it is
6370 recommended to set all other settings in order to avoid relying on default
6371 unobvious parameters.
6372
6373 Example :
6374 # public access (limited to this backend only)
6375 backend public_www
6376 server srv1 192.168.0.1:80
6377 stats enable
6378 stats hide-version
6379 stats scope .
6380 stats uri /admin?stats
6381 stats realm Haproxy\ Statistics
6382 stats auth admin1:AdMiN123
6383 stats auth admin2:AdMiN321
6384
6385 # internal monitoring access (unlimited)
6386 backend private_monitoring
6387 stats enable
6388 stats uri /admin?stats
6389 stats refresh 5s
6390
6391 See also : "stats auth", "stats enable", "stats realm"
6392
6393
Willy Tarreaud63335a2010-02-26 12:56:52 +01006394stick match <pattern> [table <table>] [{if | unless} <cond>]
6395 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +01006396 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +01006397 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006398
6399 Arguments :
Willy Tarreau74ca5042013-06-11 23:12:07 +02006400 <pattern> is a pattern extraction rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006401 describes what elements of the incoming request or connection
6402 will be analysed in the hope to find a matching entry in a
6403 stickiness table. This rule is mandatory.
6404
6405 <table> is an optional stickiness table name. If unspecified, the same
6406 backend's table is used. A stickiness table is declared using
6407 the "stick-table" statement.
6408
6409 <cond> is an optional matching condition. It makes it possible to match
6410 on a certain criterion only when other conditions are met (or
6411 not met). For instance, it could be used to match on a source IP
6412 address except when a request passes through a known proxy, in
6413 which case we'd match on a header containing that IP address.
6414
6415 Some protocols or applications require complex stickiness rules and cannot
6416 always simply rely on cookies nor hashing. The "stick match" statement
6417 describes a rule to extract the stickiness criterion from an incoming request
6418 or connection. See section 7 for a complete list of possible patterns and
6419 transformation rules.
6420
6421 The table has to be declared using the "stick-table" statement. It must be of
6422 a type compatible with the pattern. By default it is the one which is present
6423 in the same backend. It is possible to share a table with other backends by
6424 referencing it using the "table" keyword. If another table is referenced,
6425 the server's ID inside the backends are used. By default, all server IDs
6426 start at 1 in each backend, so the server ordering is enough. But in case of
6427 doubt, it is highly recommended to force server IDs using their "id" setting.
6428
6429 It is possible to restrict the conditions where a "stick match" statement
6430 will apply, using "if" or "unless" followed by a condition. See section 7 for
6431 ACL based conditions.
6432
6433 There is no limit on the number of "stick match" statements. The first that
6434 applies and matches will cause the request to be directed to the same server
6435 as was used for the request which created the entry. That way, multiple
6436 matches can be used as fallbacks.
6437
6438 The stick rules are checked after the persistence cookies, so they will not
6439 affect stickiness if a cookie has already been used to select a server. That
6440 way, it becomes very easy to insert cookies and match on IP addresses in
6441 order to maintain stickiness between HTTP and HTTPS.
6442
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01006443 Note : Consider not using this feature in multi-process mode (nbproc > 1)
6444 unless you know what you do : memory is not shared between the
6445 processes, which can result in random behaviours.
6446
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006447 Example :
6448 # forward SMTP users to the same server they just used for POP in the
6449 # last 30 minutes
6450 backend pop
6451 mode tcp
6452 balance roundrobin
6453 stick store-request src
6454 stick-table type ip size 200k expire 30m
6455 server s1 192.168.1.1:110
6456 server s2 192.168.1.1:110
6457
6458 backend smtp
6459 mode tcp
6460 balance roundrobin
6461 stick match src table pop
6462 server s1 192.168.1.1:25
6463 server s2 192.168.1.1:25
6464
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01006465 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
6466 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006467
6468
6469stick on <pattern> [table <table>] [{if | unless} <condition>]
6470 Define a request pattern to associate a user to a server
6471 May be used in sections : defaults | frontend | listen | backend
6472 no | no | yes | yes
6473
6474 Note : This form is exactly equivalent to "stick match" followed by
6475 "stick store-request", all with the same arguments. Please refer
6476 to both keywords for details. It is only provided as a convenience
6477 for writing more maintainable configurations.
6478
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01006479 Note : Consider not using this feature in multi-process mode (nbproc > 1)
6480 unless you know what you do : memory is not shared between the
6481 processes, which can result in random behaviours.
6482
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006483 Examples :
6484 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +01006485 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006486
6487 # ...is strictly equivalent to this one :
6488 stick match src table pop if !localhost
6489 stick store-request src table pop if !localhost
6490
6491
6492 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
6493 # well as HTTP without cookie. Share the same table between both accesses.
6494 backend http
6495 mode http
6496 balance roundrobin
6497 stick on src table https
6498 cookie SRV insert indirect nocache
6499 server s1 192.168.1.1:80 cookie s1
6500 server s2 192.168.1.1:80 cookie s2
6501
6502 backend https
6503 mode tcp
6504 balance roundrobin
6505 stick-table type ip size 200k expire 30m
6506 stick on src
6507 server s1 192.168.1.1:443
6508 server s2 192.168.1.1:443
6509
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01006510 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006511
6512
6513stick store-request <pattern> [table <table>] [{if | unless} <condition>]
6514 Define a request pattern used to create an entry in a stickiness table
6515 May be used in sections : defaults | frontend | listen | backend
6516 no | no | yes | yes
6517
6518 Arguments :
Willy Tarreau74ca5042013-06-11 23:12:07 +02006519 <pattern> is a pattern extraction rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006520 describes what elements of the incoming request or connection
6521 will be analysed, extracted and stored in the table once a
6522 server is selected.
6523
6524 <table> is an optional stickiness table name. If unspecified, the same
6525 backend's table is used. A stickiness table is declared using
6526 the "stick-table" statement.
6527
6528 <cond> is an optional storage condition. It makes it possible to store
6529 certain criteria only when some conditions are met (or not met).
6530 For instance, it could be used to store the source IP address
6531 except when the request passes through a known proxy, in which
6532 case we'd store a converted form of a header containing that IP
6533 address.
6534
6535 Some protocols or applications require complex stickiness rules and cannot
6536 always simply rely on cookies nor hashing. The "stick store-request" statement
6537 describes a rule to decide what to extract from the request and when to do
6538 it, in order to store it into a stickiness table for further requests to
6539 match it using the "stick match" statement. Obviously the extracted part must
6540 make sense and have a chance to be matched in a further request. Storing a
6541 client's IP address for instance often makes sense. Storing an ID found in a
6542 URL parameter also makes sense. Storing a source port will almost never make
6543 any sense because it will be randomly matched. See section 7 for a complete
6544 list of possible patterns and transformation rules.
6545
6546 The table has to be declared using the "stick-table" statement. It must be of
6547 a type compatible with the pattern. By default it is the one which is present
6548 in the same backend. It is possible to share a table with other backends by
6549 referencing it using the "table" keyword. If another table is referenced,
6550 the server's ID inside the backends are used. By default, all server IDs
6551 start at 1 in each backend, so the server ordering is enough. But in case of
6552 doubt, it is highly recommended to force server IDs using their "id" setting.
6553
6554 It is possible to restrict the conditions where a "stick store-request"
6555 statement will apply, using "if" or "unless" followed by a condition. This
6556 condition will be evaluated while parsing the request, so any criteria can be
6557 used. See section 7 for ACL based conditions.
6558
6559 There is no limit on the number of "stick store-request" statements, but
6560 there is a limit of 8 simultaneous stores per request or response. This
6561 makes it possible to store up to 8 criteria, all extracted from either the
6562 request or the response, regardless of the number of rules. Only the 8 first
6563 ones which match will be kept. Using this, it is possible to feed multiple
6564 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +01006565 another protocol or access method. Using multiple store-request rules with
6566 the same table is possible and may be used to find the best criterion to rely
6567 on, by arranging the rules by decreasing preference order. Only the first
6568 extracted criterion for a given table will be stored. All subsequent store-
6569 request rules referencing the same table will be skipped and their ACLs will
6570 not be evaluated.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006571
6572 The "store-request" rules are evaluated once the server connection has been
6573 established, so that the table will contain the real server that processed
6574 the request.
6575
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01006576 Note : Consider not using this feature in multi-process mode (nbproc > 1)
6577 unless you know what you do : memory is not shared between the
6578 processes, which can result in random behaviours.
6579
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006580 Example :
6581 # forward SMTP users to the same server they just used for POP in the
6582 # last 30 minutes
6583 backend pop
6584 mode tcp
6585 balance roundrobin
6586 stick store-request src
6587 stick-table type ip size 200k expire 30m
6588 server s1 192.168.1.1:110
6589 server s2 192.168.1.1:110
6590
6591 backend smtp
6592 mode tcp
6593 balance roundrobin
6594 stick match src table pop
6595 server s1 192.168.1.1:25
6596 server s2 192.168.1.1:25
6597
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01006598 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
6599 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006600
6601
Emeric Brun7c6b82e2010-09-24 16:34:28 +02006602stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +02006603 size <size> [expire <expire>] [nopurge] [peers <peersect>]
6604 [store <data_type>]*
Godbach64cef792013-12-04 16:08:22 +08006605 Configure the stickiness table for the current section
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006606 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +02006607 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006608
6609 Arguments :
6610 ip a table declared with "type ip" will only store IPv4 addresses.
6611 This form is very compact (about 50 bytes per entry) and allows
6612 very fast entry lookup and stores with almost no overhead. This
6613 is mainly used to store client source IP addresses.
6614
David du Colombier9a6d3c92011-03-17 10:40:24 +01006615 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
6616 This form is very compact (about 60 bytes per entry) and allows
6617 very fast entry lookup and stores with almost no overhead. This
6618 is mainly used to store client source IP addresses.
6619
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006620 integer a table declared with "type integer" will store 32bit integers
6621 which can represent a client identifier found in a request for
6622 instance.
6623
6624 string a table declared with "type string" will store substrings of up
6625 to <len> characters. If the string provided by the pattern
6626 extractor is larger than <len>, it will be truncated before
6627 being stored. During matching, at most <len> characters will be
6628 compared between the string in the table and the extracted
6629 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +02006630 to 32 characters.
6631
6632 binary a table declared with "type binary" will store binary blocks
6633 of <len> bytes. If the block provided by the pattern
6634 extractor is larger than <len>, it will be truncated before
6635 being stored. If the block provided by the pattern extractor
6636 is shorter than <len>, it will be padded by 0. When not
6637 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006638
6639 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +02006640 "string" type table (See type "string" above). Or the number
6641 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006642 changing this parameter as memory usage will proportionally
6643 increase.
6644
6645 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +01006646 value directly impacts memory usage. Count approximately
6647 50 bytes per entry, plus the size of a string if any. The size
6648 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006649
6650 [nopurge] indicates that we refuse to purge older entries when the table
6651 is full. When not specified and the table is full when haproxy
6652 wants to store an entry in it, it will flush a few of the oldest
6653 entries in order to release some space for the new ones. This is
6654 most often the desired behaviour. In some specific cases, it
6655 be desirable to refuse new entries instead of purging the older
6656 ones. That may be the case when the amount of data to store is
6657 far above the hardware limits and we prefer not to offer access
6658 to new clients than to reject the ones already connected. When
6659 using this parameter, be sure to properly set the "expire"
6660 parameter (see below).
6661
Emeric Brunf099e792010-09-27 12:05:28 +02006662 <peersect> is the name of the peers section to use for replication. Entries
6663 which associate keys to server IDs are kept synchronized with
6664 the remote peers declared in this section. All entries are also
6665 automatically learned from the local peer (old process) during a
6666 soft restart.
6667
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01006668 NOTE : peers can't be used in multi-process mode.
6669
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006670 <expire> defines the maximum duration of an entry in the table since it
6671 was last created, refreshed or matched. The expiration delay is
6672 defined using the standard time format, similarly as the various
6673 timeouts. The maximum duration is slightly above 24 days. See
6674 section 2.2 for more information. If this delay is not specified,
Cyril Bontédc4d9032012-04-08 21:57:39 +02006675 the session won't automatically expire, but older entries will
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006676 be removed once full. Be sure not to use the "nopurge" parameter
6677 if not expiration delay is specified.
6678
Willy Tarreau08d5f982010-06-06 13:34:54 +02006679 <data_type> is used to store additional information in the stick-table. This
6680 may be used by ACLs in order to control various criteria related
6681 to the activity of the client matching the stick-table. For each
6682 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +02006683 that the additional data can fit. Several data types may be
6684 stored with an entry. Multiple data types may be specified after
6685 the "store" keyword, as a comma-separated list. Alternatively,
6686 it is possible to repeat the "store" keyword followed by one or
6687 several data types. Except for the "server_id" type which is
6688 automatically detected and enabled, all data types must be
6689 explicitly declared to be stored. If an ACL references a data
6690 type which is not stored, the ACL will simply not match. Some
6691 data types require an argument which must be passed just after
6692 the type between parenthesis. See below for the supported data
6693 types and their arguments.
6694
6695 The data types that can be stored with an entry are the following :
6696 - server_id : this is an integer which holds the numeric ID of the server a
6697 request was assigned to. It is used by the "stick match", "stick store",
6698 and "stick on" rules. It is automatically enabled when referenced.
6699
6700 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
6701 integer which may be used for anything. Most of the time it will be used
6702 to put a special tag on some entries, for instance to note that a
6703 specific behaviour was detected and must be known for future matches.
6704
Willy Tarreauba2ffd12013-05-29 15:54:14 +02006705 - gpc0_rate(<period>) : increment rate of the first General Purpose Counter
6706 over a period. It is a positive 32-bit integer integer which may be used
6707 for anything. Just like <gpc0>, it counts events, but instead of keeping
6708 a cumulative count, it maintains the rate at which the counter is
6709 incremented. Most of the time it will be used to measure the frequency of
6710 occurrence of certain events (eg: requests to a specific URL).
6711
Willy Tarreauc9705a12010-07-27 20:05:50 +02006712 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
6713 the absolute number of connections received from clients which matched
6714 this entry. It does not mean the connections were accepted, just that
6715 they were received.
6716
6717 - conn_cur : Current Connections. It is a positive 32-bit integer which
6718 stores the concurrent connection counts for the entry. It is incremented
6719 once an incoming connection matches the entry, and decremented once the
6720 connection leaves. That way it is possible to know at any time the exact
6721 number of concurrent connections for an entry.
6722
6723 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
6724 integer parameter <period> which indicates in milliseconds the length
6725 of the period over which the average is measured. It reports the average
6726 incoming connection rate over that period, in connections per period. The
6727 result is an integer which can be matched using ACLs.
6728
6729 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
6730 the absolute number of sessions received from clients which matched this
6731 entry. A session is a connection that was accepted by the layer 4 rules.
6732
6733 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
6734 integer parameter <period> which indicates in milliseconds the length
6735 of the period over which the average is measured. It reports the average
6736 incoming session rate over that period, in sessions per period. The
6737 result is an integer which can be matched using ACLs.
6738
6739 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
6740 counts the absolute number of HTTP requests received from clients which
6741 matched this entry. It does not matter whether they are valid requests or
6742 not. Note that this is different from sessions when keep-alive is used on
6743 the client side.
6744
6745 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
6746 integer parameter <period> which indicates in milliseconds the length
6747 of the period over which the average is measured. It reports the average
6748 HTTP request rate over that period, in requests per period. The result is
6749 an integer which can be matched using ACLs. It does not matter whether
6750 they are valid requests or not. Note that this is different from sessions
6751 when keep-alive is used on the client side.
6752
6753 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
6754 counts the absolute number of HTTP requests errors induced by clients
6755 which matched this entry. Errors are counted on invalid and truncated
6756 requests, as well as on denied or tarpitted requests, and on failed
6757 authentications. If the server responds with 4xx, then the request is
6758 also counted as an error since it's an error triggered by the client
6759 (eg: vulnerability scan).
6760
6761 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
6762 integer parameter <period> which indicates in milliseconds the length
6763 of the period over which the average is measured. It reports the average
6764 HTTP request error rate over that period, in requests per period (see
6765 http_err_cnt above for what is accounted as an error). The result is an
6766 integer which can be matched using ACLs.
6767
6768 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
6769 integer which counts the cumulated amount of bytes received from clients
6770 which matched this entry. Headers are included in the count. This may be
6771 used to limit abuse of upload features on photo or video servers.
6772
6773 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
6774 integer parameter <period> which indicates in milliseconds the length
6775 of the period over which the average is measured. It reports the average
6776 incoming bytes rate over that period, in bytes per period. It may be used
6777 to detect users which upload too much and too fast. Warning: with large
6778 uploads, it is possible that the amount of uploaded data will be counted
6779 once upon termination, thus causing spikes in the average transfer speed
6780 instead of having a smooth one. This may partially be smoothed with
6781 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
6782 recommended for better fairness.
6783
6784 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
6785 integer which counts the cumulated amount of bytes sent to clients which
6786 matched this entry. Headers are included in the count. This may be used
6787 to limit abuse of bots sucking the whole site.
6788
6789 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
6790 an integer parameter <period> which indicates in milliseconds the length
6791 of the period over which the average is measured. It reports the average
6792 outgoing bytes rate over that period, in bytes per period. It may be used
6793 to detect users which download too much and too fast. Warning: with large
6794 transfers, it is possible that the amount of transferred data will be
6795 counted once upon termination, thus causing spikes in the average
6796 transfer speed instead of having a smooth one. This may partially be
6797 smoothed with "option contstats" though this is not perfect yet. Use of
6798 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +02006799
Willy Tarreauc00cdc22010-06-06 16:48:26 +02006800 There is only one stick-table per proxy. At the moment of writing this doc,
6801 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006802 to be required, simply create a dummy backend with a stick-table in it and
6803 reference it.
6804
6805 It is important to understand that stickiness based on learning information
6806 has some limitations, including the fact that all learned associations are
6807 lost upon restart. In general it can be good as a complement but not always
6808 as an exclusive stickiness.
6809
Willy Tarreauc9705a12010-07-27 20:05:50 +02006810 Last, memory requirements may be important when storing many data types.
6811 Indeed, storing all indicators above at once in each entry requires 116 bytes
6812 per entry, or 116 MB for a 1-million entries table. This is definitely not
6813 something that can be ignored.
6814
6815 Example:
6816 # Keep track of counters of up to 1 million IP addresses over 5 minutes
6817 # and store a general purpose counter and the average connection rate
6818 # computed over a sliding window of 30 seconds.
6819 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
6820
6821 See also : "stick match", "stick on", "stick store-request", section 2.2
David du Colombiera13d1b92011-03-17 10:40:22 +01006822 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006823
6824
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006825stick store-response <pattern> [table <table>] [{if | unless} <condition>]
6826 Define a request pattern used to create an entry in a stickiness table
6827 May be used in sections : defaults | frontend | listen | backend
6828 no | no | yes | yes
6829
6830 Arguments :
Willy Tarreau74ca5042013-06-11 23:12:07 +02006831 <pattern> is a pattern extraction rule as described in section 7.3. It
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006832 describes what elements of the response or connection will
6833 be analysed, extracted and stored in the table once a
6834 server is selected.
6835
6836 <table> is an optional stickiness table name. If unspecified, the same
6837 backend's table is used. A stickiness table is declared using
6838 the "stick-table" statement.
6839
6840 <cond> is an optional storage condition. It makes it possible to store
6841 certain criteria only when some conditions are met (or not met).
6842 For instance, it could be used to store the SSL session ID only
6843 when the response is a SSL server hello.
6844
6845 Some protocols or applications require complex stickiness rules and cannot
6846 always simply rely on cookies nor hashing. The "stick store-response"
6847 statement describes a rule to decide what to extract from the response and
6848 when to do it, in order to store it into a stickiness table for further
6849 requests to match it using the "stick match" statement. Obviously the
6850 extracted part must make sense and have a chance to be matched in a further
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006851 request. Storing an ID found in a header of a response makes sense.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006852 See section 7 for a complete list of possible patterns and transformation
6853 rules.
6854
6855 The table has to be declared using the "stick-table" statement. It must be of
6856 a type compatible with the pattern. By default it is the one which is present
6857 in the same backend. It is possible to share a table with other backends by
6858 referencing it using the "table" keyword. If another table is referenced,
6859 the server's ID inside the backends are used. By default, all server IDs
6860 start at 1 in each backend, so the server ordering is enough. But in case of
6861 doubt, it is highly recommended to force server IDs using their "id" setting.
6862
6863 It is possible to restrict the conditions where a "stick store-response"
6864 statement will apply, using "if" or "unless" followed by a condition. This
6865 condition will be evaluated while parsing the response, so any criteria can
6866 be used. See section 7 for ACL based conditions.
6867
6868 There is no limit on the number of "stick store-response" statements, but
6869 there is a limit of 8 simultaneous stores per request or response. This
6870 makes it possible to store up to 8 criteria, all extracted from either the
6871 request or the response, regardless of the number of rules. Only the 8 first
6872 ones which match will be kept. Using this, it is possible to feed multiple
6873 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +01006874 another protocol or access method. Using multiple store-response rules with
6875 the same table is possible and may be used to find the best criterion to rely
6876 on, by arranging the rules by decreasing preference order. Only the first
6877 extracted criterion for a given table will be stored. All subsequent store-
6878 response rules referencing the same table will be skipped and their ACLs will
6879 not be evaluated. However, even if a store-request rule references a table, a
6880 store-response rule may also use the same table. This means that each table
6881 may learn exactly one element from the request and one element from the
6882 response at once.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006883
6884 The table will contain the real server that processed the request.
6885
6886 Example :
6887 # Learn SSL session ID from both request and response and create affinity.
6888 backend https
6889 mode tcp
6890 balance roundrobin
Cyril Bontédc4d9032012-04-08 21:57:39 +02006891 # maximum SSL session ID length is 32 bytes.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006892 stick-table type binary len 32 size 30k expire 30m
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006893
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006894 acl clienthello req_ssl_hello_type 1
6895 acl serverhello rep_ssl_hello_type 2
6896
6897 # use tcp content accepts to detects ssl client and server hello.
6898 tcp-request inspect-delay 5s
6899 tcp-request content accept if clienthello
6900
6901 # no timeout on response inspect delay by default.
6902 tcp-response content accept if serverhello
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006903
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006904 # SSL session ID (SSLID) may be present on a client or server hello.
6905 # Its length is coded on 1 byte at offset 43 and its value starts
6906 # at offset 44.
6907
6908 # Match and learn on request if client hello.
6909 stick on payload_lv(43,1) if clienthello
6910
6911 # Learn on response if server hello.
6912 stick store-response payload_lv(43,1) if serverhello
Cyril Bontédc4d9032012-04-08 21:57:39 +02006913
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006914 server s1 192.168.1.1:443
6915 server s2 192.168.1.1:443
6916
6917 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
6918 extraction.
6919
6920
Willy Tarreaue9656522010-08-17 15:40:09 +02006921tcp-request connection <action> [{if | unless} <condition>]
6922 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +02006923 May be used in sections : defaults | frontend | listen | backend
6924 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +02006925 Arguments :
6926 <action> defines the action to perform if the condition applies. Valid
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02006927 actions include : "accept", "reject", "track-sc0", "track-sc1",
6928 "track-sc2", and "expect-proxy". See below for more details.
Willy Tarreau1a687942010-05-23 22:40:30 +02006929
Willy Tarreaue9656522010-08-17 15:40:09 +02006930 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006931
6932 Immediately after acceptance of a new incoming connection, it is possible to
6933 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +02006934 or dropped or have its counters tracked. Those conditions cannot make use of
6935 any data contents because the connection has not been read from yet, and the
6936 buffers are not yet allocated. This is used to selectively and very quickly
6937 accept or drop connections from various sources with a very low overhead. If
6938 some contents need to be inspected in order to take the decision, the
6939 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006940
Willy Tarreaue9656522010-08-17 15:40:09 +02006941 The "tcp-request connection" rules are evaluated in their exact declaration
6942 order. If no rule matches or if there is no rule, the default action is to
6943 accept the incoming connection. There is no specific limit to the number of
6944 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006945
Willy Tarreaue9656522010-08-17 15:40:09 +02006946 Three types of actions are supported :
6947 - accept :
6948 accepts the connection if the condition is true (when used with "if")
6949 or false (when used with "unless"). The first such rule executed ends
6950 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006951
Willy Tarreaue9656522010-08-17 15:40:09 +02006952 - reject :
6953 rejects the connection if the condition is true (when used with "if")
6954 or false (when used with "unless"). The first such rule executed ends
6955 the rules evaluation. Rejected connections do not even become a
6956 session, which is why they are accounted separately for in the stats,
6957 as "denied connections". They are not considered for the session
6958 rate-limit and are not logged either. The reason is that these rules
6959 should only be used to filter extremely high connection rates such as
6960 the ones encountered during a massive DDoS attack. Under these extreme
6961 conditions, the simple action of logging each event would make the
6962 system collapse and would considerably lower the filtering capacity. If
6963 logging is absolutely desired, then "tcp-request content" rules should
6964 be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006965
Willy Tarreau4f0d9192013-06-11 20:40:55 +02006966 - expect-proxy layer4 :
6967 configures the client-facing connection to receive a PROXY protocol
6968 header before any byte is read from the socket. This is equivalent to
6969 having the "accept-proxy" keyword on the "bind" line, except that using
6970 the TCP rule allows the PROXY protocol to be accepted only for certain
6971 IP address ranges using an ACL. This is convenient when multiple layers
6972 of load balancers are passed through by traffic coming from public
6973 hosts.
6974
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02006975 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] :
Willy Tarreaue9656522010-08-17 15:40:09 +02006976 enables tracking of sticky counters from current connection. These
6977 rules do not stop evaluation and do not change default action. Two sets
6978 of counters may be simultaneously tracked by the same connection. The
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02006979 first "track-sc0" rule executed enables tracking of the counters of the
6980 specified table as the first set. The first "track-sc1" rule executed
Willy Tarreaue9656522010-08-17 15:40:09 +02006981 enables tracking of the counters of the specified table as the second
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02006982 set. The first "track-sc2" rule executed enables tracking of the
6983 counters of the specified table as the third set. It is a recommended
6984 practice to use the first set of counters for the per-frontend counters
6985 and the second set for the per-backend ones. But this is just a
6986 guideline, all may be used everywhere.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006987
Willy Tarreaue9656522010-08-17 15:40:09 +02006988 These actions take one or two arguments :
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01006989 <key> is mandatory, and is a pattern extraction rule as described
Willy Tarreau74ca5042013-06-11 23:12:07 +02006990 in section 7.3. It describes what elements of the incoming
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01006991 request or connection will be analysed, extracted, combined,
6992 and used to select which table entry to update the counters.
6993 Note that "tcp-request connection" cannot use content-based
6994 fetches.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006995
Willy Tarreaue9656522010-08-17 15:40:09 +02006996 <table> is an optional table to be used instead of the default one,
6997 which is the stick-table declared in the current proxy. All
6998 the counters for the matches and updates for the key will
6999 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02007000
Willy Tarreaue9656522010-08-17 15:40:09 +02007001 Once a "track-sc*" rule is executed, the key is looked up in the table
7002 and if it is not found, an entry is allocated for it. Then a pointer to
7003 that entry is kept during all the session's life, and this entry's
7004 counters are updated as often as possible, every time the session's
7005 counters are updated, and also systematically when the session ends.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01007006 Counters are only updated for events that happen after the tracking has
7007 been started. For example, connection counters will not be updated when
7008 tracking layer 7 information, since the connection event happens before
7009 layer7 information is extracted.
7010
Willy Tarreaue9656522010-08-17 15:40:09 +02007011 If the entry tracks concurrent connection counters, one connection is
7012 counted for as long as the entry is tracked, and the entry will not
7013 expire during that time. Tracking counters also provides a performance
7014 advantage over just checking the keys, because only one table lookup is
7015 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02007016
Willy Tarreaue9656522010-08-17 15:40:09 +02007017 Note that the "if/unless" condition is optional. If no condition is set on
7018 the action, it is simply performed unconditionally. That can be useful for
7019 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02007020
Willy Tarreaue9656522010-08-17 15:40:09 +02007021 Example: accept all connections from white-listed hosts, reject too fast
7022 connection without counting them, and track accepted connections.
7023 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02007024
Willy Tarreaue9656522010-08-17 15:40:09 +02007025 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02007026 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02007027 tcp-request connection track-sc0 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +02007028
Willy Tarreaue9656522010-08-17 15:40:09 +02007029 Example: accept all connections from white-listed hosts, count all other
7030 connections and reject too fast ones. This results in abusive ones
7031 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02007032
Willy Tarreaue9656522010-08-17 15:40:09 +02007033 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02007034 tcp-request connection track-sc0 src
7035 tcp-request connection reject if { sc0_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02007036
Willy Tarreau4f0d9192013-06-11 20:40:55 +02007037 Example: enable the PROXY protocol for traffic coming from all known proxies.
7038
7039 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
7040
Willy Tarreau68c03ab2010-08-06 15:08:45 +02007041 See section 7 about ACL usage.
7042
Willy Tarreaue9656522010-08-17 15:40:09 +02007043 See also : "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +02007044
7045
Willy Tarreaue9656522010-08-17 15:40:09 +02007046tcp-request content <action> [{if | unless} <condition>]
7047 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +02007048 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02007049 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +02007050 Arguments :
7051 <action> defines the action to perform if the condition applies. Valid
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02007052 actions include : "accept", "reject", "track-sc0", "track-sc1",
7053 and "track-sc2". See "tcp-request connection" above for their
Willy Tarreaue25c9172013-05-28 18:32:20 +02007054 signification.
Willy Tarreau62644772008-07-16 18:36:06 +02007055
Willy Tarreaue9656522010-08-17 15:40:09 +02007056 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +02007057
Willy Tarreaue9656522010-08-17 15:40:09 +02007058 A request's contents can be analysed at an early stage of request processing
7059 called "TCP content inspection". During this stage, ACL-based rules are
7060 evaluated every time the request contents are updated, until either an
7061 "accept" or a "reject" rule matches, or the TCP request inspection delay
7062 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +02007063
Willy Tarreaue9656522010-08-17 15:40:09 +02007064 The first difference between these rules and "tcp-request connection" rules
7065 is that "tcp-request content" rules can make use of contents to take a
7066 decision. Most often, these decisions will consider a protocol recognition or
7067 validity. The second difference is that content-based rules can be used in
Willy Tarreauf3338342014-01-28 21:40:28 +01007068 both frontends and backends. In case of HTTP keep-alive with the client, all
7069 tcp-request content rules are evaluated again, so haproxy keeps a record of
7070 what sticky counters were assigned by a "tcp-request connection" versus a
7071 "tcp-request content" rule, and flushes all the content-related ones after
7072 processing an HTTP request, so that they may be evaluated again by the rules
7073 being evaluated again for the next request. This is of particular importance
7074 when the rule tracks some L7 information or when it is conditionned by an
7075 L7-based ACL, since tracking may change between requests.
Willy Tarreau62644772008-07-16 18:36:06 +02007076
Willy Tarreaue9656522010-08-17 15:40:09 +02007077 Content-based rules are evaluated in their exact declaration order. If no
7078 rule matches or if there is no rule, the default action is to accept the
7079 contents. There is no specific limit to the number of rules which may be
7080 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +02007081
Willy Tarreaue9656522010-08-17 15:40:09 +02007082 Three types of actions are supported :
7083 - accept :
7084 - reject :
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02007085 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
Willy Tarreau62644772008-07-16 18:36:06 +02007086
Willy Tarreaue9656522010-08-17 15:40:09 +02007087 They have the same meaning as their counter-parts in "tcp-request connection"
7088 so please refer to that section for a complete description.
Willy Tarreau62644772008-07-16 18:36:06 +02007089
Willy Tarreauf3338342014-01-28 21:40:28 +01007090 While there is nothing mandatory about it, it is recommended to use the
7091 track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request
7092 content" rules in the frontend, and track-sc2 for "tcp-request content"
7093 rules in the backend, because that makes the configuration more readable
7094 and easier to troubleshoot, but this is just a guideline and all counters
7095 may be used everywhere.
Willy Tarreau62644772008-07-16 18:36:06 +02007096
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007097 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +02007098 the action, it is simply performed unconditionally. That can be useful for
7099 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +02007100
Willy Tarreaue9656522010-08-17 15:40:09 +02007101 It is perfectly possible to match layer 7 contents with "tcp-request content"
Willy Tarreauc0239e02012-04-16 14:42:55 +02007102 rules, since HTTP-specific ACL matches are able to preliminarily parse the
7103 contents of a buffer before extracting the required data. If the buffered
7104 contents do not parse as a valid HTTP message, then the ACL does not match.
7105 The parser which is involved there is exactly the same as for all other HTTP
Willy Tarreauf3338342014-01-28 21:40:28 +01007106 processing, so there is no risk of parsing something differently. In an HTTP
7107 backend connected to from an HTTP frontend, it is guaranteed that HTTP
7108 contents will always be immediately present when the rule is evaluated first.
Willy Tarreau62644772008-07-16 18:36:06 +02007109
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01007110 Tracking layer7 information is also possible provided that the information
7111 are present when the rule is processed. The current solution for making the
7112 rule engine wait for such information is to set an inspect delay and to
7113 condition its execution with an ACL relying on such information.
7114
Willy Tarreau62644772008-07-16 18:36:06 +02007115 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +02007116 # Accept HTTP requests containing a Host header saying "example.com"
7117 # and reject everything else.
7118 acl is_host_com hdr(Host) -i example.com
7119 tcp-request inspect-delay 30s
Willy Tarreauc0239e02012-04-16 14:42:55 +02007120 tcp-request content accept if is_host_com
Willy Tarreaue9656522010-08-17 15:40:09 +02007121 tcp-request content reject
7122
7123 Example:
Willy Tarreau62644772008-07-16 18:36:06 +02007124 # reject SMTP connection if client speaks first
7125 tcp-request inspect-delay 30s
7126 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02007127 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +02007128
7129 # Forward HTTPS connection only if client speaks
7130 tcp-request inspect-delay 30s
7131 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02007132 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +02007133 tcp-request content reject
7134
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01007135 Example:
7136 # Track the last IP from X-Forwarded-For
7137 tcp-request inspect-delay 10s
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02007138 tcp-request content track-sc0 hdr(x-forwarded-for,-1) if HTTP
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01007139
7140 Example:
7141 # track request counts per "base" (concatenation of Host+URL)
7142 tcp-request inspect-delay 10s
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02007143 tcp-request content track-sc0 base table req-rate if HTTP
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01007144
Willy Tarreaue9656522010-08-17 15:40:09 +02007145 Example: track per-frontend and per-backend counters, block abusers at the
7146 frontend when the backend detects abuse.
7147
7148 frontend http
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02007149 # Use General Purpose Couter 0 in SC0 as a global abuse counter
Willy Tarreaue9656522010-08-17 15:40:09 +02007150 # protecting all our sites
7151 stick-table type ip size 1m expire 5m store gpc0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02007152 tcp-request connection track-sc0 src
7153 tcp-request connection reject if { sc0_get_gpc0 gt 0 }
Willy Tarreaue9656522010-08-17 15:40:09 +02007154 ...
7155 use_backend http_dynamic if { path_end .php }
7156
7157 backend http_dynamic
7158 # if a source makes too fast requests to this dynamic site (tracked
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02007159 # by SC1), block it globally in the frontend.
Willy Tarreaue9656522010-08-17 15:40:09 +02007160 stick-table type ip size 1m expire 5m store http_req_rate(10s)
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02007161 acl click_too_fast sc1_http_req_rate gt 10
7162 acl mark_as_abuser sc0_inc_gpc0 gt 0
7163 tcp-request content track-sc1 src
Willy Tarreaue9656522010-08-17 15:40:09 +02007164 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +02007165
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007166 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02007167
Willy Tarreaue9656522010-08-17 15:40:09 +02007168 See also : "tcp-request connection", "tcp-request inspect-delay"
Willy Tarreau62644772008-07-16 18:36:06 +02007169
7170
7171tcp-request inspect-delay <timeout>
7172 Set the maximum allowed time to wait for data during content inspection
7173 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02007174 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +02007175 Arguments :
7176 <timeout> is the timeout value specified in milliseconds by default, but
7177 can be in any other unit if the number is suffixed by the unit,
7178 as explained at the top of this document.
7179
7180 People using haproxy primarily as a TCP relay are often worried about the
7181 risk of passing any type of protocol to a server without any analysis. In
7182 order to be able to analyze the request contents, we must first withhold
7183 the data then analyze them. This statement simply enables withholding of
7184 data for at most the specified amount of time.
7185
Willy Tarreaufb356202010-08-03 14:02:05 +02007186 TCP content inspection applies very early when a connection reaches a
7187 frontend, then very early when the connection is forwarded to a backend. This
7188 means that a connection may experience a first delay in the frontend and a
7189 second delay in the backend if both have tcp-request rules.
7190
Willy Tarreau62644772008-07-16 18:36:06 +02007191 Note that when performing content inspection, haproxy will evaluate the whole
7192 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007193 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +02007194 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +01007195 contents are definitive. If no delay is set, haproxy will not wait at all
7196 and will immediately apply a verdict based on the available information.
7197 Obviously this is unlikely to be very useful and might even be racy, so such
7198 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +02007199
7200 As soon as a rule matches, the request is released and continues as usual. If
7201 the timeout is reached and no rule matches, the default policy will be to let
7202 it pass through unaffected.
7203
7204 For most protocols, it is enough to set it to a few seconds, as most clients
7205 send the full request immediately upon connection. Add 3 or more seconds to
7206 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +01007207 to use large values, for instance to ensure that the client never talks
Willy Tarreau62644772008-07-16 18:36:06 +02007208 before the server (eg: SMTP), or to wait for a client to talk before passing
7209 data to the server (eg: SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +02007210 least the inspection delay, otherwise it will expire first. If the client
7211 closes the connection or if the buffer is full, the delay immediately expires
7212 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +02007213
Willy Tarreau55165fe2009-05-10 12:02:55 +02007214 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +02007215 "timeout client".
7216
7217
Emeric Brun0a3b67f2010-09-24 15:34:53 +02007218tcp-response content <action> [{if | unless} <condition>]
7219 Perform an action on a session response depending on a layer 4-7 condition
7220 May be used in sections : defaults | frontend | listen | backend
7221 no | no | yes | yes
7222 Arguments :
7223 <action> defines the action to perform if the condition applies. Valid
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02007224 actions include : "accept", "close", "reject".
Emeric Brun0a3b67f2010-09-24 15:34:53 +02007225
7226 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
7227
7228 Response contents can be analysed at an early stage of response processing
7229 called "TCP content inspection". During this stage, ACL-based rules are
7230 evaluated every time the response contents are updated, until either an
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02007231 "accept", "close" or a "reject" rule matches, or a TCP response inspection
7232 delay is set and expires with no matching rule.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02007233
7234 Most often, these decisions will consider a protocol recognition or validity.
7235
7236 Content-based rules are evaluated in their exact declaration order. If no
7237 rule matches or if there is no rule, the default action is to accept the
7238 contents. There is no specific limit to the number of rules which may be
7239 inserted.
7240
7241 Two types of actions are supported :
7242 - accept :
7243 accepts the response if the condition is true (when used with "if")
7244 or false (when used with "unless"). The first such rule executed ends
7245 the rules evaluation.
7246
Willy Tarreaucc1e04b2013-09-11 23:20:29 +02007247 - close :
7248 immediately closes the connection with the server if the condition is
7249 true (when used with "if"), or false (when used with "unless"). The
7250 first such rule executed ends the rules evaluation. The main purpose of
7251 this action is to force a connection to be finished between a client
7252 and a server after an exchange when the application protocol expects
7253 some long time outs to elapse first. The goal is to eliminate idle
7254 connections which take signifiant resources on servers with certain
7255 protocols.
7256
Emeric Brun0a3b67f2010-09-24 15:34:53 +02007257 - reject :
7258 rejects the response if the condition is true (when used with "if")
7259 or false (when used with "unless"). The first such rule executed ends
Jamie Gloudonaaa21002012-08-25 00:18:33 -04007260 the rules evaluation. Rejected session are immediately closed.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02007261
7262 Note that the "if/unless" condition is optional. If no condition is set on
7263 the action, it is simply performed unconditionally. That can be useful for
7264 for changing the default action to a reject.
7265
Jamie Gloudonaaa21002012-08-25 00:18:33 -04007266 It is perfectly possible to match layer 7 contents with "tcp-response
7267 content" rules, but then it is important to ensure that a full response has
7268 been buffered, otherwise no contents will match. In order to achieve this,
7269 the best solution involves detecting the HTTP protocol during the inspection
Emeric Brun0a3b67f2010-09-24 15:34:53 +02007270 period.
7271
7272 See section 7 about ACL usage.
7273
7274 See also : "tcp-request content", "tcp-response inspect-delay"
7275
7276
7277tcp-response inspect-delay <timeout>
7278 Set the maximum allowed time to wait for a response during content inspection
7279 May be used in sections : defaults | frontend | listen | backend
7280 no | no | yes | yes
7281 Arguments :
7282 <timeout> is the timeout value specified in milliseconds by default, but
7283 can be in any other unit if the number is suffixed by the unit,
7284 as explained at the top of this document.
7285
7286 See also : "tcp-response content", "tcp-request inspect-delay".
7287
7288
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01007289timeout check <timeout>
7290 Set additional check timeout, but only after a connection has been already
7291 established.
7292
7293 May be used in sections: defaults | frontend | listen | backend
7294 yes | no | yes | yes
7295 Arguments:
7296 <timeout> is the timeout value specified in milliseconds by default, but
7297 can be in any other unit if the number is suffixed by the unit,
7298 as explained at the top of this document.
7299
7300 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
7301 for check and "timeout check" as an additional read timeout. The "min" is
7302 used so that people running with *very* long "timeout connect" (eg. those
7303 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +01007304 (Please also note that there is no valid reason to have such long connect
7305 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
7306 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01007307
7308 If "timeout check" is not set haproxy uses "inter" for complete check
7309 timeout (connect + read) exactly like all <1.3.15 version.
7310
7311 In most cases check request is much simpler and faster to handle than normal
7312 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +01007313 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01007314
7315 This parameter is specific to backends, but can be specified once for all in
7316 "defaults" sections. This is in fact one of the easiest solutions not to
7317 forget about it.
7318
Willy Tarreau41a340d2008-01-22 12:25:31 +01007319 See also: "timeout connect", "timeout queue", "timeout server",
7320 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01007321
7322
Willy Tarreau0ba27502007-12-24 16:55:16 +01007323timeout client <timeout>
7324timeout clitimeout <timeout> (deprecated)
7325 Set the maximum inactivity time on the client side.
7326 May be used in sections : defaults | frontend | listen | backend
7327 yes | yes | yes | no
7328 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01007329 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01007330 can be in any other unit if the number is suffixed by the unit,
7331 as explained at the top of this document.
7332
7333 The inactivity timeout applies when the client is expected to acknowledge or
7334 send data. In HTTP mode, this timeout is particularly important to consider
7335 during the first phase, when the client sends the request, and during the
7336 response while it is reading data sent by the server. The value is specified
7337 in milliseconds by default, but can be in any other unit if the number is
7338 suffixed by the unit, as specified at the top of this document. In TCP mode
7339 (and to a lesser extent, in HTTP mode), it is highly recommended that the
7340 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01007341 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01007342 losses by specifying timeouts that are slightly above multiples of 3 seconds
Willy Tarreauce887fd2012-05-12 12:50:00 +02007343 (eg: 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
7344 sessions (eg: WebSocket and HTTP), it's worth considering "timeout tunnel",
7345 which overrides "timeout client" and "timeout server" for tunnels.
Willy Tarreau0ba27502007-12-24 16:55:16 +01007346
7347 This parameter is specific to frontends, but can be specified once for all in
7348 "defaults" sections. This is in fact one of the easiest solutions not to
7349 forget about it. An unspecified timeout results in an infinite timeout, which
7350 is not recommended. Such a usage is accepted and works but reports a warning
7351 during startup because it may results in accumulation of expired sessions in
7352 the system if the system's timeouts are not configured either.
7353
7354 This parameter replaces the old, deprecated "clitimeout". It is recommended
7355 to use it to write new configurations. The form "timeout clitimeout" is
7356 provided only by backwards compatibility but its use is strongly discouraged.
7357
Willy Tarreauce887fd2012-05-12 12:50:00 +02007358 See also : "clitimeout", "timeout server", "timeout tunnel".
Willy Tarreau0ba27502007-12-24 16:55:16 +01007359
7360
7361timeout connect <timeout>
7362timeout contimeout <timeout> (deprecated)
7363 Set the maximum time to wait for a connection attempt to a server to succeed.
7364 May be used in sections : defaults | frontend | listen | backend
7365 yes | no | yes | yes
7366 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01007367 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01007368 can be in any other unit if the number is suffixed by the unit,
7369 as explained at the top of this document.
7370
7371 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01007372 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01007373 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01007374 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01007375 connect timeout also presets both queue and tarpit timeouts to the same value
7376 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +01007377
7378 This parameter is specific to backends, but can be specified once for all in
7379 "defaults" sections. This is in fact one of the easiest solutions not to
7380 forget about it. An unspecified timeout results in an infinite timeout, which
7381 is not recommended. Such a usage is accepted and works but reports a warning
7382 during startup because it may results in accumulation of failed sessions in
7383 the system if the system's timeouts are not configured either.
7384
7385 This parameter replaces the old, deprecated "contimeout". It is recommended
7386 to use it to write new configurations. The form "timeout contimeout" is
7387 provided only by backwards compatibility but its use is strongly discouraged.
7388
Willy Tarreau41a340d2008-01-22 12:25:31 +01007389 See also: "timeout check", "timeout queue", "timeout server", "contimeout",
7390 "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +01007391
7392
Willy Tarreaub16a5742010-01-10 14:46:16 +01007393timeout http-keep-alive <timeout>
7394 Set the maximum allowed time to wait for a new HTTP request to appear
7395 May be used in sections : defaults | frontend | listen | backend
7396 yes | yes | yes | yes
7397 Arguments :
7398 <timeout> is the timeout value specified in milliseconds by default, but
7399 can be in any other unit if the number is suffixed by the unit,
7400 as explained at the top of this document.
7401
7402 By default, the time to wait for a new request in case of keep-alive is set
7403 by "timeout http-request". However this is not always convenient because some
7404 people want very short keep-alive timeouts in order to release connections
7405 faster, and others prefer to have larger ones but still have short timeouts
7406 once the request has started to present itself.
7407
7408 The "http-keep-alive" timeout covers these needs. It will define how long to
7409 wait for a new HTTP request to start coming after a response was sent. Once
7410 the first byte of request has been seen, the "http-request" timeout is used
7411 to wait for the complete request to come. Note that empty lines prior to a
7412 new request do not refresh the timeout and are not counted as a new request.
7413
7414 There is also another difference between the two timeouts : when a connection
7415 expires during timeout http-keep-alive, no error is returned, the connection
7416 just closes. If the connection expires in "http-request" while waiting for a
7417 connection to complete, a HTTP 408 error is returned.
7418
7419 In general it is optimal to set this value to a few tens to hundreds of
7420 milliseconds, to allow users to fetch all objects of a page at once but
7421 without waiting for further clicks. Also, if set to a very small value (eg:
7422 1 millisecond) it will probably only accept pipelined requests but not the
7423 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +02007424 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +01007425
7426 If this parameter is not set, the "http-request" timeout applies, and if both
7427 are not set, "timeout client" still applies at the lower level. It should be
7428 set in the frontend to take effect, unless the frontend is in TCP mode, in
7429 which case the HTTP backend's timeout will be used.
7430
7431 See also : "timeout http-request", "timeout client".
7432
7433
Willy Tarreau036fae02008-01-06 13:24:40 +01007434timeout http-request <timeout>
7435 Set the maximum allowed time to wait for a complete HTTP request
7436 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +02007437 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +01007438 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01007439 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +01007440 can be in any other unit if the number is suffixed by the unit,
7441 as explained at the top of this document.
7442
7443 In order to offer DoS protection, it may be required to lower the maximum
7444 accepted time to receive a complete HTTP request without affecting the client
7445 timeout. This helps protecting against established connections on which
7446 nothing is sent. The client timeout cannot offer a good protection against
7447 this abuse because it is an inactivity timeout, which means that if the
7448 attacker sends one character every now and then, the timeout will not
7449 trigger. With the HTTP request timeout, no matter what speed the client
7450 types, the request will be aborted if it does not complete in time.
7451
7452 Note that this timeout only applies to the header part of the request, and
7453 not to any data. As soon as the empty line is received, this timeout is not
Willy Tarreaub16a5742010-01-10 14:46:16 +01007454 used anymore. It is used again on keep-alive connections to wait for a second
7455 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +01007456
7457 Generally it is enough to set it to a few seconds, as most clients send the
7458 full request immediately upon connection. Add 3 or more seconds to cover TCP
7459 retransmits but that's all. Setting it to very low values (eg: 50 ms) will
7460 generally work on local networks as long as there are no packet losses. This
7461 will prevent people from sending bare HTTP requests using telnet.
7462
7463 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +02007464 chunk of the incoming request. It should be set in the frontend to take
7465 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
7466 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +01007467
Willy Tarreaub16a5742010-01-10 14:46:16 +01007468 See also : "timeout http-keep-alive", "timeout client".
Willy Tarreau036fae02008-01-06 13:24:40 +01007469
Willy Tarreau844e3c52008-01-11 16:28:18 +01007470
7471timeout queue <timeout>
7472 Set the maximum time to wait in the queue for a connection slot to be free
7473 May be used in sections : defaults | frontend | listen | backend
7474 yes | no | yes | yes
7475 Arguments :
7476 <timeout> is the timeout value specified in milliseconds by default, but
7477 can be in any other unit if the number is suffixed by the unit,
7478 as explained at the top of this document.
7479
7480 When a server's maxconn is reached, connections are left pending in a queue
7481 which may be server-specific or global to the backend. In order not to wait
7482 indefinitely, a timeout is applied to requests pending in the queue. If the
7483 timeout is reached, it is considered that the request will almost never be
7484 served, so it is dropped and a 503 error is returned to the client.
7485
7486 The "timeout queue" statement allows to fix the maximum time for a request to
7487 be left pending in a queue. If unspecified, the same value as the backend's
7488 connection timeout ("timeout connect") is used, for backwards compatibility
7489 with older versions with no "timeout queue" parameter.
7490
7491 See also : "timeout connect", "contimeout".
7492
7493
7494timeout server <timeout>
7495timeout srvtimeout <timeout> (deprecated)
7496 Set the maximum inactivity time on the server side.
7497 May be used in sections : defaults | frontend | listen | backend
7498 yes | no | yes | yes
7499 Arguments :
7500 <timeout> is the timeout value specified in milliseconds by default, but
7501 can be in any other unit if the number is suffixed by the unit,
7502 as explained at the top of this document.
7503
7504 The inactivity timeout applies when the server is expected to acknowledge or
7505 send data. In HTTP mode, this timeout is particularly important to consider
7506 during the first phase of the server's response, when it has to send the
7507 headers, as it directly represents the server's processing time for the
7508 request. To find out what value to put there, it's often good to start with
7509 what would be considered as unacceptable response times, then check the logs
7510 to observe the response time distribution, and adjust the value accordingly.
7511
7512 The value is specified in milliseconds by default, but can be in any other
7513 unit if the number is suffixed by the unit, as specified at the top of this
7514 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
7515 recommended that the client timeout remains equal to the server timeout in
7516 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01007517 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01007518 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreauce887fd2012-05-12 12:50:00 +02007519 seconds (eg: 4 or 5 seconds minimum). If some long-lived sessions are mixed
7520 with short-lived sessions (eg: WebSocket and HTTP), it's worth considering
7521 "timeout tunnel", which overrides "timeout client" and "timeout server" for
7522 tunnels.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007523
7524 This parameter is specific to backends, but can be specified once for all in
7525 "defaults" sections. This is in fact one of the easiest solutions not to
7526 forget about it. An unspecified timeout results in an infinite timeout, which
7527 is not recommended. Such a usage is accepted and works but reports a warning
7528 during startup because it may results in accumulation of expired sessions in
7529 the system if the system's timeouts are not configured either.
7530
7531 This parameter replaces the old, deprecated "srvtimeout". It is recommended
7532 to use it to write new configurations. The form "timeout srvtimeout" is
7533 provided only by backwards compatibility but its use is strongly discouraged.
7534
Willy Tarreauce887fd2012-05-12 12:50:00 +02007535 See also : "srvtimeout", "timeout client" and "timeout tunnel".
Willy Tarreau844e3c52008-01-11 16:28:18 +01007536
7537
7538timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +01007539 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +01007540 May be used in sections : defaults | frontend | listen | backend
7541 yes | yes | yes | yes
7542 Arguments :
7543 <timeout> is the tarpit duration specified in milliseconds by default, but
7544 can be in any other unit if the number is suffixed by the unit,
7545 as explained at the top of this document.
7546
7547 When a connection is tarpitted using "reqtarpit", it is maintained open with
7548 no activity for a certain amount of time, then closed. "timeout tarpit"
7549 defines how long it will be maintained open.
7550
7551 The value is specified in milliseconds by default, but can be in any other
7552 unit if the number is suffixed by the unit, as specified at the top of this
7553 document. If unspecified, the same value as the backend's connection timeout
7554 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +01007555 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007556
7557 See also : "timeout connect", "contimeout".
7558
7559
Willy Tarreauce887fd2012-05-12 12:50:00 +02007560timeout tunnel <timeout>
7561 Set the maximum inactivity time on the client and server side for tunnels.
7562 May be used in sections : defaults | frontend | listen | backend
7563 yes | no | yes | yes
7564 Arguments :
7565 <timeout> is the timeout value specified in milliseconds by default, but
7566 can be in any other unit if the number is suffixed by the unit,
7567 as explained at the top of this document.
7568
Jamie Gloudonaaa21002012-08-25 00:18:33 -04007569 The tunnel timeout applies when a bidirectional connection is established
Willy Tarreauce887fd2012-05-12 12:50:00 +02007570 between a client and a server, and the connection remains inactive in both
7571 directions. This timeout supersedes both the client and server timeouts once
7572 the connection becomes a tunnel. In TCP, this timeout is used as soon as no
7573 analyser remains attached to either connection (eg: tcp content rules are
7574 accepted). In HTTP, this timeout is used when a connection is upgraded (eg:
7575 when switching to the WebSocket protocol, or forwarding a CONNECT request
7576 to a proxy), or after the first response when no keepalive/close option is
7577 specified.
7578
7579 The value is specified in milliseconds by default, but can be in any other
7580 unit if the number is suffixed by the unit, as specified at the top of this
7581 document. Whatever the expected normal idle time, it is a good practice to
7582 cover at least one or several TCP packet losses by specifying timeouts that
7583 are slightly above multiples of 3 seconds (eg: 4 or 5 seconds minimum).
7584
7585 This parameter is specific to backends, but can be specified once for all in
7586 "defaults" sections. This is in fact one of the easiest solutions not to
7587 forget about it.
7588
7589 Example :
7590 defaults http
7591 option http-server-close
7592 timeout connect 5s
7593 timeout client 30s
7594 timeout client 30s
7595 timeout server 30s
7596 timeout tunnel 1h # timeout to use with WebSocket and CONNECT
7597
7598 See also : "timeout client", "timeout server".
7599
7600
Willy Tarreau844e3c52008-01-11 16:28:18 +01007601transparent (deprecated)
7602 Enable client-side transparent proxying
7603 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01007604 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01007605 Arguments : none
7606
7607 This keyword was introduced in order to provide layer 7 persistence to layer
7608 3 load balancers. The idea is to use the OS's ability to redirect an incoming
7609 connection for a remote address to a local process (here HAProxy), and let
7610 this process know what address was initially requested. When this option is
7611 used, sessions without cookies will be forwarded to the original destination
7612 IP address of the incoming request (which should match that of another
7613 equipment), while requests with cookies will still be forwarded to the
7614 appropriate server.
7615
7616 The "transparent" keyword is deprecated, use "option transparent" instead.
7617
7618 Note that contrary to a common belief, this option does NOT make HAProxy
7619 present the client's IP to the server when establishing the connection.
7620
Willy Tarreau844e3c52008-01-11 16:28:18 +01007621 See also: "option transparent"
7622
William Lallemanda73203e2012-03-12 12:48:57 +01007623unique-id-format <string>
7624 Generate a unique ID for each request.
7625 May be used in sections : defaults | frontend | listen | backend
7626 yes | yes | yes | no
7627 Arguments :
7628 <string> is a log-format string.
7629
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007630 This keyword creates a ID for each request using the custom log format. A
7631 unique ID is useful to trace a request passing through many components of
7632 a complex infrastructure. The newly created ID may also be logged using the
7633 %ID tag the log-format string.
William Lallemanda73203e2012-03-12 12:48:57 +01007634
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007635 The format should be composed from elements that are guaranteed to be
7636 unique when combined together. For instance, if multiple haproxy instances
7637 are involved, it might be important to include the node name. It is often
7638 needed to log the incoming connection's source and destination addresses
7639 and ports. Note that since multiple requests may be performed over the same
7640 connection, including a request counter may help differentiate them.
7641 Similarly, a timestamp may protect against a rollover of the counter.
7642 Logging the process ID will avoid collisions after a service restart.
William Lallemanda73203e2012-03-12 12:48:57 +01007643
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007644 It is recommended to use hexadecimal notation for many fields since it
7645 makes them more compact and saves space in logs.
William Lallemanda73203e2012-03-12 12:48:57 +01007646
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007647 Example:
William Lallemanda73203e2012-03-12 12:48:57 +01007648
7649 unique-id-format %{+X}o\ %Ci:%Cp_%Fi:%Fp_%Ts_%rt:%pid
7650
7651 will generate:
7652
7653 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
7654
7655 See also: "unique-id-header"
7656
7657unique-id-header <name>
7658 Add a unique ID header in the HTTP request.
7659 May be used in sections : defaults | frontend | listen | backend
7660 yes | yes | yes | no
7661 Arguments :
7662 <name> is the name of the header.
7663
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007664 Add a unique-id header in the HTTP request sent to the server, using the
7665 unique-id-format. It can't work if the unique-id-format doesn't exist.
William Lallemanda73203e2012-03-12 12:48:57 +01007666
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007667 Example:
William Lallemanda73203e2012-03-12 12:48:57 +01007668
7669 unique-id-format %{+X}o\ %Ci:%Cp_%Fi:%Fp_%Ts_%rt:%pid
7670 unique-id-header X-Unique-ID
7671
7672 will generate:
7673
7674 X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
7675
7676 See also: "unique-id-format"
Willy Tarreau844e3c52008-01-11 16:28:18 +01007677
7678use_backend <backend> if <condition>
7679use_backend <backend> unless <condition>
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02007680 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007681 May be used in sections : defaults | frontend | listen | backend
7682 no | yes | yes | no
7683 Arguments :
7684 <backend> is the name of a valid backend or "listen" section.
7685
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007686 <condition> is a condition composed of ACLs, as described in section 7.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007687
7688 When doing content-switching, connections arrive on a frontend and are then
7689 dispatched to various backends depending on a number of conditions. The
7690 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02007691 "use_backend" keyword. While it is normally used with HTTP processing, it can
7692 also be used in pure TCP, either without content using stateless ACLs (eg:
7693 source address validation) or combined with a "tcp-request" rule to wait for
7694 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007695
7696 There may be as many "use_backend" rules as desired. All of these rules are
7697 evaluated in their declaration order, and the first one which matches will
7698 assign the backend.
7699
7700 In the first form, the backend will be used if the condition is met. In the
7701 second form, the backend will be used if the condition is not met. If no
7702 condition is valid, the backend defined with "default_backend" will be used.
7703 If no default backend is defined, either the servers in the same section are
7704 used (in case of a "listen" section) or, in case of a frontend, no server is
7705 used and a 503 service unavailable response is returned.
7706
Willy Tarreau51aecc72009-07-12 09:47:04 +02007707 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007708 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +02007709 and backend processing will immediately follow, or the backend will wait for
7710 a complete HTTP request to get in. This feature is useful when a frontend
7711 must decode several protocols on a unique port, one of them being HTTP.
7712
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02007713 See also: "default_backend", "tcp-request", and section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +01007714
Willy Tarreau036fae02008-01-06 13:24:40 +01007715
Willy Tarreau4a5cade2012-04-05 21:09:48 +02007716use-server <server> if <condition>
7717use-server <server> unless <condition>
7718 Only use a specific server if/unless an ACL-based condition is matched.
7719 May be used in sections : defaults | frontend | listen | backend
7720 no | no | yes | yes
7721 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007722 <server> is the name of a valid server in the same backend section.
Willy Tarreau4a5cade2012-04-05 21:09:48 +02007723
7724 <condition> is a condition composed of ACLs, as described in section 7.
7725
7726 By default, connections which arrive to a backend are load-balanced across
7727 the available servers according to the configured algorithm, unless a
7728 persistence mechanism such as a cookie is used and found in the request.
7729
7730 Sometimes it is desirable to forward a particular request to a specific
7731 server without having to declare a dedicated backend for this server. This
7732 can be achieved using the "use-server" rules. These rules are evaluated after
7733 the "redirect" rules and before evaluating cookies, and they have precedence
7734 on them. There may be as many "use-server" rules as desired. All of these
7735 rules are evaluated in their declaration order, and the first one which
7736 matches will assign the server.
7737
7738 If a rule designates a server which is down, and "option persist" is not used
7739 and no force-persist rule was validated, it is ignored and evaluation goes on
7740 with the next rules until one matches.
7741
7742 In the first form, the server will be used if the condition is met. In the
7743 second form, the server will be used if the condition is not met. If no
7744 condition is valid, the processing continues and the server will be assigned
7745 according to other persistence mechanisms.
7746
7747 Note that even if a rule is matched, cookie processing is still performed but
7748 does not assign the server. This allows prefixed cookies to have their prefix
7749 stripped.
7750
7751 The "use-server" statement works both in HTTP and TCP mode. This makes it
7752 suitable for use with content-based inspection. For instance, a server could
7753 be selected in a farm according to the TLS SNI field. And if these servers
7754 have their weight set to zero, they will not be used for other traffic.
7755
7756 Example :
7757 # intercept incoming TLS requests based on the SNI field
7758 use-server www if { req_ssl_sni -i www.example.com }
7759 server www 192.168.0.1:443 weight 0
7760 use-server mail if { req_ssl_sni -i mail.example.com }
7761 server mail 192.168.0.1:587 weight 0
7762 use-server imap if { req_ssl_sni -i imap.example.com }
7763 server mail 192.168.0.1:993 weight 0
7764 # all the rest is forwarded to this server
7765 server default 192.168.0.2:443 check
7766
7767 See also: "use_backend", serction 5 about server and section 7 about ACLs.
7768
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007769
77705. Bind and Server options
7771--------------------------
7772
7773The "bind", "server" and "default-server" keywords support a number of settings
7774depending on some build options and on the system HAProxy was built on. These
7775settings generally each consist in one word sometimes followed by a value,
7776written on the same line as the "bind" or "server" line. All these options are
7777described in this section.
7778
7779
77805.1. Bind options
7781-----------------
7782
7783The "bind" keyword supports a certain number of settings which are all passed
7784as arguments on the same line. The order in which those arguments appear makes
7785no importance, provided that they appear after the bind address. All of these
7786parameters are optional. Some of them consist in a single words (booleans),
7787while other ones expect a value after them. In this case, the value must be
7788provided immediately after the setting name.
7789
7790The currently supported settings are the following ones.
7791
7792accept-proxy
7793 Enforces the use of the PROXY protocol over any connection accepted by any of
7794 the sockets declared on the same line. The PROXY protocol dictates the layer
7795 3/4 addresses of the incoming connection to be used everywhere an address is
7796 used, with the only exception of "tcp-request connection" rules which will
7797 only see the real connection address. Logs will reflect the addresses
7798 indicated in the protocol, unless it is violated, in which case the real
7799 address will still be used. This keyword combined with support from external
7800 components can be used as an efficient and reliable alternative to the
7801 X-Forwarded-For mechanism which is not always reliable and not even always
Willy Tarreau4f0d9192013-06-11 20:40:55 +02007802 usable. See also "tcp-request connection expect-proxy" for a finer-grained
7803 setting of which client is allowed to use the protocol.
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007804
Willy Tarreauab861d32013-04-02 02:30:41 +02007805alpn <protocols>
7806 This enables the TLS ALPN extension and advertises the specified protocol
7807 list as supported on top of ALPN. The protocol list consists in a comma-
7808 delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
7809 quotes). This requires that the SSL library is build with support for TLS
7810 extensions enabled (check with haproxy -vv). The ALPN extension replaces the
7811 initial NPN extension.
7812
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007813backlog <backlog>
7814 Sets the socket's backlog to this value. If unspecified, the frontend's
7815 backlog is used instead, which generally defaults to the maxconn value.
7816
Emeric Brun7fb34422012-09-28 15:26:15 +02007817ecdhe <named curve>
7818 This setting is only available when support for OpenSSL was built in. It sets
Emeric Brun6924ef82013-03-06 14:08:53 +01007819 the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default,
7820 used named curve is prime256v1.
Emeric Brun7fb34422012-09-28 15:26:15 +02007821
Emeric Brunfd33a262012-10-11 16:28:27 +02007822ca-file <cafile>
Emeric Brun1a073b42012-09-28 17:07:34 +02007823 This setting is only available when support for OpenSSL was built in. It
7824 designates a PEM file from which to load CA certificates used to verify
7825 client's certificate.
7826
Emeric Brunb6dc9342012-09-28 17:55:37 +02007827ca-ignore-err [all|<errorID>,...]
7828 This setting is only available when support for OpenSSL was built in.
7829 Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
7830 If set to 'all', all errors are ignored. SSL handshake is not aborted if an
7831 error is ignored.
7832
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007833ciphers <ciphers>
7834 This setting is only available when support for OpenSSL was built in. It sets
7835 the string describing the list of cipher algorithms ("cipher suite") that are
7836 negociated during the SSL/TLS handshake. The format of the string is defined
7837 in "man 1 ciphers" from OpenSSL man pages, and can be for instance a string
7838 such as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes).
7839
Emeric Brunfd33a262012-10-11 16:28:27 +02007840crl-file <crlfile>
Emeric Brun1a073b42012-09-28 17:07:34 +02007841 This setting is only available when support for OpenSSL was built in. It
7842 designates a PEM file from which to load certificate revocation list used
7843 to verify client's certificate.
7844
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007845crt <cert>
Alex Davies0fbf0162013-03-02 16:04:50 +00007846 This setting is only available when support for OpenSSL was built in. It
7847 designates a PEM file containing both the required certificates and any
7848 associated private keys. This file can be built by concatenating multiple
7849 PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA
7850 requires an intermediate certificate, this can also be concatenated into this
7851 file.
7852
7853 If the OpenSSL used supports Diffie-Hellman, parameters present in this file
7854 are loaded.
7855
7856 If a directory name is used instead of a PEM file, then all files found in
7857 that directory will be loaded. This directive may be specified multiple times
7858 in order to load certificates from multiple files or directories. The
7859 certificates will be presented to clients who provide a valid TLS Server Name
7860 Indication field matching one of their CN or alt subjects. Wildcards are
7861 supported, where a wildcard character '*' is used instead of the first
7862 hostname component (eg: *.example.org matches www.example.org but not
7863 www.sub.example.org).
7864
7865 If no SNI is provided by the client or if the SSL library does not support
7866 TLS extensions, or if the client provides an SNI hostname which does not
7867 match any certificate, then the first loaded certificate will be presented.
7868 This means that when loading certificates from a directory, it is highly
7869 recommended to load the default one first as a file.
7870
Emeric Brune032bfa2012-09-28 13:01:45 +02007871 Note that the same cert may be loaded multiple times without side effects.
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007872
Alex Davies0fbf0162013-03-02 16:04:50 +00007873 Some CAs (such as Godaddy) offer a drop down list of server types that do not
7874 include HAProxy when obtaining a certificate. If this happens be sure to
7875 choose a webserver that the CA believes requires a intermediate CA (for
7876 Godaddy, selection Apache Tomcat will get the correct bundle, but many
7877 others, e.g. nginx, result in a wrong bundle that will not work for some
7878 clients).
7879
Emeric Brunb6dc9342012-09-28 17:55:37 +02007880crt-ignore-err <errors>
Alex Davies0fbf0162013-03-02 16:04:50 +00007881 This setting is only available when support for OpenSSL was built in. Sets a
7882 comma separated list of errorIDs to ignore during verify at depth == 0. If
7883 set to 'all', all errors are ignored. SSL handshake is not abored if an error
7884 is ignored.
Emeric Brunb6dc9342012-09-28 17:55:37 +02007885
Emmanuel Hocdetfe616562013-01-22 15:31:15 +01007886crt-list <file>
7887 This setting is only available when support for OpenSSL was built in. It
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +02007888 designates a list of PEM file with an optional list of SNI filter per
7889 certificate, with the following format for each line :
Emmanuel Hocdetfe616562013-01-22 15:31:15 +01007890
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +02007891 <crtfile> [[!]<snifilter> ...]
Emmanuel Hocdetfe616562013-01-22 15:31:15 +01007892
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +02007893 Wildcards are supported in the SNI filter. Negative filter are also supported,
7894 only useful in combination with a wildcard filter to exclude a particular SNI.
7895 The certificates will be presented to clients who provide a valid TLS Server
7896 Name Indication field matching one of the SNI filters. If no SNI filter is
7897 specified, the CN and alt subjects are used. This directive may be specified
7898 multiple times. See the "crt" option for more information. The default
7899 certificate is still needed to meet OpenSSL expectations. If it is not used,
7900 the 'strict-sni' option may be used.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +01007901
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007902defer-accept
7903 Is an optional keyword which is supported only on certain Linux kernels. It
7904 states that a connection will only be accepted once some data arrive on it,
7905 or at worst after the first retransmit. This should be used only on protocols
7906 for which the client talks first (eg: HTTP). It can slightly improve
7907 performance by ensuring that most of the request is already available when
7908 the connection is accepted. On the other hand, it will not be able to detect
7909 connections which don't talk. It is important to note that this option is
7910 broken in all kernels up to 2.6.31, as the connection is never accepted until
7911 the client talks. This can cause issues with front firewalls which would see
7912 an established connection while the proxy will only see it in SYN_RECV. This
7913 option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
7914
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007915force-sslv3
7916 This option enforces use of SSLv3 only on SSL connections instanciated from
7917 this listener. SSLv3 is generally less expensive than the TLS counterparts
7918 for high connection rates. See also "force-tls*", "no-sslv3", and "no-tls*".
7919
7920force-tlsv10
7921 This option enforces use of TLSv1.0 only on SSL connections instanciated from
7922 this listener. See also "force-tls*", "no-sslv3", and "no-tls*".
7923
7924force-tlsv11
7925 This option enforces use of TLSv1.1 only on SSL connections instanciated from
7926 this listener. See also "force-tls*", "no-sslv3", and "no-tls*".
7927
7928force-tlsv12
7929 This option enforces use of TLSv1.2 only on SSL connections instanciated from
7930 this listener. See also "force-tls*", "no-sslv3", and "no-tls*".
7931
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007932gid <gid>
7933 Sets the group of the UNIX sockets to the designated system gid. It can also
7934 be set by default in the global section's "unix-bind" statement. Note that
7935 some platforms simply ignore this. This setting is equivalent to the "group"
7936 setting except that the group ID is used instead of its name. This setting is
7937 ignored by non UNIX sockets.
7938
7939group <group>
7940 Sets the group of the UNIX sockets to the designated system group. It can
7941 also be set by default in the global section's "unix-bind" statement. Note
7942 that some platforms simply ignore this. This setting is equivalent to the
7943 "gid" setting except that the group name is used instead of its gid. This
7944 setting is ignored by non UNIX sockets.
7945
7946id <id>
7947 Fixes the socket ID. By default, socket IDs are automatically assigned, but
7948 sometimes it is more convenient to fix them to ease monitoring. This value
7949 must be strictly positive and unique within the listener/frontend. This
7950 option can only be used when defining only a single socket.
7951
7952interface <interface>
Lukas Tribusfce2e962013-02-12 22:13:19 +01007953 Restricts the socket to a specific interface. When specified, only packets
7954 received from that particular interface are processed by the socket. This is
7955 currently only supported on Linux. The interface must be a primary system
7956 interface, not an aliased interface. It is also possible to bind multiple
7957 frontends to the same address if they are bound to different interfaces. Note
7958 that binding to a network interface requires root privileges. This parameter
7959 is only compatible with TCPv4/TCPv6 sockets.
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007960
Willy Tarreauabb175f2012-09-24 12:43:26 +02007961level <level>
7962 This setting is used with the stats sockets only to restrict the nature of
7963 the commands that can be issued on the socket. It is ignored by other
7964 sockets. <level> can be one of :
7965 - "user" is the least privileged level ; only non-sensitive stats can be
7966 read, and no change is allowed. It would make sense on systems where it
7967 is not easy to restrict access to the socket.
7968 - "operator" is the default level and fits most common uses. All data can
7969 be read, and only non-sensitive changes are permitted (eg: clear max
7970 counters).
7971 - "admin" should be used with care, as everything is permitted (eg: clear
7972 all counters).
7973
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007974maxconn <maxconn>
7975 Limits the sockets to this number of concurrent connections. Extraneous
7976 connections will remain in the system's backlog until a connection is
7977 released. If unspecified, the limit will be the same as the frontend's
7978 maxconn. Note that in case of port ranges or multiple addresses, the same
7979 value will be applied to each socket. This setting enables different
7980 limitations on expensive sockets, for instance SSL entries which may easily
7981 eat all memory.
7982
7983mode <mode>
7984 Sets the octal mode used to define access permissions on the UNIX socket. It
7985 can also be set by default in the global section's "unix-bind" statement.
7986 Note that some platforms simply ignore this. This setting is ignored by non
7987 UNIX sockets.
7988
7989mss <maxseg>
7990 Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming
7991 connections. This can be used to force a lower MSS for certain specific
7992 ports, for instance for connections passing through a VPN. Note that this
7993 relies on a kernel feature which is theoretically supported under Linux but
7994 was buggy in all versions prior to 2.6.28. It may or may not work on other
7995 operating systems. It may also not change the advertised value but change the
7996 effective size of outgoing segments. The commonly advertised value for TCPv4
7997 over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is
7998 positive, it will be used as the advertised MSS. If it is negative, it will
7999 indicate by how much to reduce the incoming connection's advertised MSS for
8000 outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.
8001
8002name <name>
8003 Sets an optional name for these sockets, which will be reported on the stats
8004 page.
8005
8006nice <nice>
8007 Sets the 'niceness' of connections initiated from the socket. Value must be
8008 in the range -1024..1024 inclusive, and defaults to zero. Positive values
8009 means that such connections are more friendly to others and easily offer
8010 their place in the scheduler. On the opposite, negative values mean that
8011 connections want to run with a higher priority than others. The difference
8012 only happens under high loads when the system is close to saturation.
8013 Negative values are appropriate for low-latency or administration services,
8014 and high values are generally recommended for CPU intensive tasks such as SSL
8015 processing or bulk transfers which are less sensible to latency. For example,
8016 it may make sense to use a positive value for an SMTP socket and a negative
8017 one for an RDP socket.
8018
Emeric Brun9b3009b2012-10-05 11:55:06 +02008019no-sslv3
Willy Tarreaub6205fd2012-09-24 12:27:33 +02008020 This setting is only available when support for OpenSSL was built in. It
8021 disables support for SSLv3 on any sockets instanciated from the listener when
8022 SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
Emeric Brun2cb7ae52012-10-05 14:14:21 +02008023 be enabled using any configuration option. See also "force-tls*",
8024 and "force-sslv3".
Willy Tarreaub6205fd2012-09-24 12:27:33 +02008025
Emeric Brun90ad8722012-10-02 14:00:59 +02008026no-tls-tickets
8027 This setting is only available when support for OpenSSL was built in. It
8028 disables the stateless session resumption (RFC 5077 TLS Ticket
8029 extension) and force to use stateful session resumption. Stateless
8030 session resumption is more expensive in CPU usage.
8031
Emeric Brun9b3009b2012-10-05 11:55:06 +02008032no-tlsv10
Willy Tarreaub6205fd2012-09-24 12:27:33 +02008033 This setting is only available when support for OpenSSL was built in. It
Emeric Brun2cb7ae52012-10-05 14:14:21 +02008034 disables support for TLSv1.0 on any sockets instanciated from the listener
8035 when SSL is supported. Note that SSLv2 is forced disabled in the code and
8036 cannot be enabled using any configuration option. See also "force-tls*",
8037 and "force-sslv3".
Willy Tarreaub6205fd2012-09-24 12:27:33 +02008038
Emeric Brun9b3009b2012-10-05 11:55:06 +02008039no-tlsv11
Emeric Brunf5da4932012-09-28 19:42:54 +02008040 This setting is only available when support for OpenSSL was built in. It
Emeric Brun2cb7ae52012-10-05 14:14:21 +02008041 disables support for TLSv1.1 on any sockets instanciated from the listener
8042 when SSL is supported. Note that SSLv2 is forced disabled in the code and
8043 cannot be enabled using any configuration option. See also "force-tls*",
8044 and "force-sslv3".
Emeric Brunf5da4932012-09-28 19:42:54 +02008045
Emeric Brun9b3009b2012-10-05 11:55:06 +02008046no-tlsv12
Emeric Brunf5da4932012-09-28 19:42:54 +02008047 This setting is only available when support for OpenSSL was built in. It
Emeric Brun2cb7ae52012-10-05 14:14:21 +02008048 disables support for TLSv1.2 on any sockets instanciated from the listener
8049 when SSL is supported. Note that SSLv2 is forced disabled in the code and
8050 cannot be enabled using any configuration option. See also "force-tls*",
8051 and "force-sslv3".
Emeric Brunf5da4932012-09-28 19:42:54 +02008052
Willy Tarreau6c9a3d52012-10-18 18:57:14 +02008053npn <protocols>
8054 This enables the NPN TLS extension and advertises the specified protocol list
8055 as supported on top of NPN. The protocol list consists in a comma-delimited
8056 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
8057 This requires that the SSL library is build with support for TLS extensions
Willy Tarreauab861d32013-04-02 02:30:41 +02008058 enabled (check with haproxy -vv). Note that the NPN extension has been
8059 replaced with the ALPN extension (see the "alpn" keyword).
Willy Tarreau6c9a3d52012-10-18 18:57:14 +02008060
Willy Tarreaub6205fd2012-09-24 12:27:33 +02008061ssl
8062 This setting is only available when support for OpenSSL was built in. It
8063 enables SSL deciphering on connections instanciated from this listener. A
8064 certificate is necessary (see "crt" above). All contents in the buffers will
8065 appear in clear text, so that ACLs and HTTP processing will only have access
8066 to deciphered contents.
8067
Emmanuel Hocdet65623372013-01-24 17:17:15 +01008068strict-sni
8069 This setting is only available when support for OpenSSL was built in. The
8070 SSL/TLS negotiation is allow only if the client provided an SNI which match
8071 a certificate. The default certificate is not used.
8072 See the "crt" option for more information.
8073
Willy Tarreau1c862c52012-10-05 16:21:00 +02008074tfo
Lukas Tribus0defb902013-02-13 23:35:39 +01008075 Is an optional keyword which is supported only on Linux kernels >= 3.7. It
Willy Tarreau1c862c52012-10-05 16:21:00 +02008076 enables TCP Fast Open on the listening socket, which means that clients which
8077 support this feature will be able to send a request and receive a response
8078 during the 3-way handshake starting from second connection, thus saving one
8079 round-trip after the first connection. This only makes sense with protocols
8080 that use high connection rates and where each round trip matters. This can
8081 possibly cause issues with many firewalls which do not accept data on SYN
8082 packets, so this option should only be enabled once well tested. This option
Lukas Tribus0999f762013-04-02 16:43:24 +02008083 is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may
8084 need to build HAProxy with USE_TFO=1 if your libc doesn't define
8085 TCP_FASTOPEN.
Willy Tarreau1c862c52012-10-05 16:21:00 +02008086
Willy Tarreaub6205fd2012-09-24 12:27:33 +02008087transparent
8088 Is an optional keyword which is supported only on certain Linux kernels. It
8089 indicates that the addresses will be bound even if they do not belong to the
8090 local machine, and that packets targeting any of these addresses will be
8091 intercepted just as if the addresses were locally configured. This normally
8092 requires that IP forwarding is enabled. Caution! do not use this with the
8093 default address '*', as it would redirect any traffic for the specified port.
8094 This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1.
8095 This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on
8096 kernel version. Some distribution kernels include backports of the feature,
8097 so check for support with your vendor.
8098
Willy Tarreau77e3af92012-11-24 15:07:23 +01008099v4v6
8100 Is an optional keyword which is supported only on most recent systems
8101 including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4
8102 and IPv6 when it uses the default address. Doing so is sometimes necessary
8103 on systems which bind to IPv6 only by default. It has no effect on non-IPv6
8104 sockets, and is overriden by the "v6only" option.
8105
Willy Tarreau9b6700f2012-11-24 11:55:28 +01008106v6only
8107 Is an optional keyword which is supported only on most recent systems
8108 including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only
8109 when it uses the default address. Doing so is sometimes preferred to doing it
Willy Tarreau77e3af92012-11-24 15:07:23 +01008110 system-wide as it is per-listener. It has no effect on non-IPv6 sockets and
8111 has precedence over the "v4v6" option.
Willy Tarreau9b6700f2012-11-24 11:55:28 +01008112
Willy Tarreaub6205fd2012-09-24 12:27:33 +02008113uid <uid>
8114 Sets the owner of the UNIX sockets to the designated system uid. It can also
8115 be set by default in the global section's "unix-bind" statement. Note that
8116 some platforms simply ignore this. This setting is equivalent to the "user"
8117 setting except that the user numeric ID is used instead of its name. This
8118 setting is ignored by non UNIX sockets.
8119
8120user <user>
8121 Sets the owner of the UNIX sockets to the designated system user. It can also
8122 be set by default in the global section's "unix-bind" statement. Note that
8123 some platforms simply ignore this. This setting is equivalent to the "uid"
8124 setting except that the user name is used instead of its uid. This setting is
8125 ignored by non UNIX sockets.
8126
Emeric Brun1a073b42012-09-28 17:07:34 +02008127verify [none|optional|required]
8128 This setting is only available when support for OpenSSL was built in. If set
8129 to 'none', client certificate is not requested. This is the default. In other
8130 cases, a client certificate is requested. If the client does not provide a
8131 certificate after the request and if 'verify' is set to 'required', then the
8132 handshake is aborted, while it would have succeeded if set to 'optional'. The
Emeric Brunfd33a262012-10-11 16:28:27 +02008133 certificate provided by the client is always verified using CAs from
8134 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
8135 is aborted, regardless of the 'verify' option, unless the error code exactly
8136 matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.
Willy Tarreau4a5cade2012-04-05 21:09:48 +02008137
Willy Tarreaub6205fd2012-09-24 12:27:33 +020081385.2. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +01008139------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02008140
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01008141The "server" and "default-server" keywords support a certain number of settings
8142which are all passed as arguments on the server line. The order in which those
8143arguments appear does not count, and they are all optional. Some of those
8144settings are single words (booleans) while others expect one or several values
8145after them. In this case, the values must immediately follow the setting name.
8146Except default-server, all those settings must be specified after the server's
8147address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +02008148
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008149 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01008150 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +02008151
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008152The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +01008153
Willy Tarreauceb4ac92012-04-28 00:41:46 +02008154addr <ipv4|ipv6>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008155 Using the "addr" parameter, it becomes possible to use a different IP address
8156 to send health-checks. On some servers, it may be desirable to dedicate an IP
8157 address to specific component able to perform complex tests which are more
8158 suitable to health-checks than the application. This parameter is ignored if
8159 the "check" parameter is not set. See also the "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +02008160
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008161 Supported in default-server: No
8162
Simon Hormand60d6912013-11-25 10:46:36 +09008163agent-check
8164 Enable an auxiliary agent check which is run independently of a regular
8165 health check. An agent health check is performed by making a TCP
8166 connection to the port set by the "agent-port" parameter" and reading
8167 an ASCII string. The string should have one of the following forms:
8168
8169 * An ASCII representation of an positive integer percentage.
8170 e.g. "75%"
8171
8172 Values in this format will set the weight proportional to the initial
8173 weight of a server as configured when haproxy starts.
8174
8175 * The string "drain".
8176
8177 This will cause the weight of a server to be set to 0, and thus it will
8178 not accept any new connections other than those that are accepted via
8179 persistence.
8180
8181 * The string "down", optionally followed by a description string.
8182
8183 Mark the server as down and log the description string as the reason.
8184
8185 * The string "stopped", optionally followed by a description string.
8186
8187 This currently has the same behaviour as "down".
8188
8189 * The string "fail", optionally followed by a description string.
8190
8191 This currently has the same behaviour as "down".
8192
Simon Horman2f1f9552013-11-25 10:46:37 +09008193 Failure to connect to the agent is not considered an error as connectivity
8194 is tested by the regular health check which is enabled by the "check"
8195 parameter.
8196
Simon Hormand60d6912013-11-25 10:46:36 +09008197 Requires the ""agent-port" parameter to be set.
8198 See also the "agent-check" parameter.
8199
8200 Supported in default-server: No
8201
8202agent-inter <delay>
8203 The "agent-inter" parameter sets the interval between two agent checks
8204 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
8205
8206 Just as with every other time-based parameter, it may be entered in any
8207 other explicit unit among { us, ms, s, m, h, d }. The "agent-inter"
8208 parameter also serves as a timeout for agent checks "timeout check" is
8209 not set. In order to reduce "resonance" effects when multiple servers are
8210 hosted on the same hardware, the agent and health checks of all servers
8211 are started with a small time offset between them. It is also possible to
8212 add some random noise in the agent and health checks interval using the
8213 global "spread-checks" keyword. This makes sense for instance when a lot
8214 of backends use the same servers.
8215
8216 See also the "agent-check" and "agent-port" parameters.
8217
8218 Supported in default-server: Yes
8219
8220agent-port <port>
8221 The "agent-port" parameter sets the TCP port used for agent checks.
8222
8223 See also the "agent-check" and "agent-inter" parameters.
8224
8225 Supported in default-server: Yes
8226
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008227backup
8228 When "backup" is present on a server line, the server is only used in load
8229 balancing when all other non-backup servers are unavailable. Requests coming
8230 with a persistence cookie referencing the server will always be served
8231 though. By default, only the first operational backup server is used, unless
8232 the "allbackups" option is set in the backend. See also the "allbackups"
8233 option.
Willy Tarreau6a06a402007-07-15 20:15:28 +02008234
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008235 Supported in default-server: No
8236
Emeric Brunef42d922012-10-11 16:11:36 +02008237ca-file <cafile>
8238 This setting is only available when support for OpenSSL was built in. It
8239 designates a PEM file from which to load CA certificates used to verify
8240 server's certificate.
8241
8242 Supported in default-server: No
8243
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008244check
8245 This option enables health checks on the server. By default, a server is
Patrick Mézardb7aeec62012-01-22 16:01:22 +01008246 always considered available. If "check" is set, the server is available when
8247 accepting periodic TCP connections, to ensure that it is really able to serve
8248 requests. The default address and port to send the tests to are those of the
8249 server, and the default source is the same as the one defined in the
8250 backend. It is possible to change the address using the "addr" parameter, the
8251 port using the "port" parameter, the source address using the "source"
8252 address, and the interval and timers using the "inter", "rise" and "fall"
Simon Hormanafc47ee2013-11-25 10:46:35 +09008253 parameters. The request method is define in the backend using the "httpchk",
8254 "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please
8255 refer to those options and parameters for more information.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008256
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008257 Supported in default-server: No
8258
Willy Tarreau6c16adc2012-10-05 00:04:16 +02008259check-send-proxy
8260 This option forces emission of a PROXY protocol line with outgoing health
8261 checks, regardless of whether the server uses send-proxy or not for the
8262 normal traffic. By default, the PROXY protocol is enabled for health checks
8263 if it is already enabled for normal traffic and if no "port" nor "addr"
8264 directive is present. However, if such a directive is present, the
8265 "check-send-proxy" option needs to be used to force the use of the
8266 protocol. See also the "send-proxy" option for more information.
8267
8268 Supported in default-server: No
8269
Willy Tarreau763a95b2012-10-04 23:15:39 +02008270check-ssl
8271 This option forces encryption of all health checks over SSL, regardless of
8272 whether the server uses SSL or not for the normal traffic. This is generally
8273 used when an explicit "port" or "addr" directive is specified and SSL health
8274 checks are not inherited. It is important to understand that this option
8275 inserts an SSL transport layer below the ckecks, so that a simple TCP connect
8276 check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
8277 common use is to send HTTPS checks by combining "httpchk" with SSL checks.
8278 All SSL settings are common to health checks and traffic (eg: ciphers).
8279 See the "ssl" option for more information.
8280
8281 Supported in default-server: No
8282
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02008283ciphers <ciphers>
8284 This option sets the string describing the list of cipher algorithms that is
8285 is negociated during the SSL/TLS handshake with the server. The format of the
8286 string is defined in "man 1 ciphers". When SSL is used to communicate with
8287 servers on the local network, it is common to see a weaker set of algorithms
8288 than what is used over the internet. Doing so reduces CPU usage on both the
8289 server and haproxy while still keeping it compatible with deployed software.
8290 Some algorithms such as RC4-SHA1 are reasonably cheap. If no security at all
8291 is needed and just connectivity, using DES can be appropriate.
8292
Willy Tarreau763a95b2012-10-04 23:15:39 +02008293 Supported in default-server: No
8294
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008295cookie <value>
8296 The "cookie" parameter sets the cookie value assigned to the server to
8297 <value>. This value will be checked in incoming requests, and the first
8298 operational server possessing the same value will be selected. In return, in
8299 cookie insertion or rewrite modes, this value will be assigned to the cookie
8300 sent to the client. There is nothing wrong in having several servers sharing
8301 the same cookie value, and it is in fact somewhat common between normal and
8302 backup servers. See also the "cookie" keyword in backend section.
8303
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008304 Supported in default-server: No
8305
Emeric Brunef42d922012-10-11 16:11:36 +02008306crl-file <crlfile>
8307 This setting is only available when support for OpenSSL was built in. It
8308 designates a PEM file from which to load certificate revocation list used
8309 to verify server's certificate.
8310
8311 Supported in default-server: No
8312
Emeric Bruna7aa3092012-10-26 12:58:00 +02008313crt <cert>
8314 This setting is only available when support for OpenSSL was built in.
8315 It designates a PEM file from which to load both a certificate and the
8316 associated private key. This file can be built by concatenating both PEM
8317 files into one. This certificate will be sent if the server send a client
8318 certificate request.
8319
8320 Supported in default-server: No
8321
Willy Tarreau96839092010-03-29 10:02:24 +02008322disabled
8323 The "disabled" keyword starts the server in the "disabled" state. That means
8324 that it is marked down in maintenance mode, and no connection other than the
8325 ones allowed by persist mode will reach it. It is very well suited to setup
8326 new servers, because normal traffic will never reach them, while it is still
8327 possible to test the service by making use of the force-persist mechanism.
8328
8329 Supported in default-server: No
8330
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008331error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +01008332 If health observing is enabled, the "error-limit" parameter specifies the
8333 number of consecutive errors that triggers event selected by the "on-error"
8334 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01008335
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008336 Supported in default-server: Yes
8337
8338 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01008339
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008340fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008341 The "fall" parameter states that a server will be considered as dead after
8342 <count> consecutive unsuccessful health checks. This value defaults to 3 if
8343 unspecified. See also the "check", "inter" and "rise" parameters.
8344
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008345 Supported in default-server: Yes
8346
Emeric Brun8694b9a2012-10-05 14:39:07 +02008347force-sslv3
8348 This option enforces use of SSLv3 only when SSL is used to communicate with
8349 the server. SSLv3 is generally less expensive than the TLS counterparts for
8350 high connection rates. See also "no-tlsv*", "no-sslv3".
8351
8352 Supported in default-server: No
8353
8354force-tlsv10
8355 This option enforces use of TLSv1.0 only when SSL is used to communicate with
8356 the server. See also "no-tlsv*", "no-sslv3".
8357
8358 Supported in default-server: No
8359
8360force-tlsv11
8361 This option enforces use of TLSv1.1 only when SSL is used to communicate with
8362 the server. See also "no-tlsv*", "no-sslv3".
8363
8364 Supported in default-server: No
8365
8366force-tlsv12
8367 This option enforces use of TLSv1.2 only when SSL is used to communicate with
8368 the server. See also "no-tlsv*", "no-sslv3".
8369
8370 Supported in default-server: No
8371
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008372id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02008373 Set a persistent ID for the server. This ID must be positive and unique for
8374 the proxy. An unused ID will automatically be assigned if unset. The first
8375 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008376
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008377 Supported in default-server: No
8378
8379inter <delay>
8380fastinter <delay>
8381downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008382 The "inter" parameter sets the interval between two consecutive health checks
8383 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
8384 It is also possible to use "fastinter" and "downinter" to optimize delays
8385 between checks depending on the server state :
8386
8387 Server state | Interval used
8388 ---------------------------------+-----------------------------------------
8389 UP 100% (non-transitional) | "inter"
8390 ---------------------------------+-----------------------------------------
8391 Transitionally UP (going down), |
8392 Transitionally DOWN (going up), | "fastinter" if set, "inter" otherwise.
8393 or yet unchecked. |
8394 ---------------------------------+-----------------------------------------
8395 DOWN 100% (non-transitional) | "downinter" if set, "inter" otherwise.
8396 ---------------------------------+-----------------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +01008397
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008398 Just as with every other time-based parameter, they can be entered in any
8399 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
8400 serves as a timeout for health checks sent to servers if "timeout check" is
8401 not set. In order to reduce "resonance" effects when multiple servers are
Simon Hormand60d6912013-11-25 10:46:36 +09008402 hosted on the same hardware, the agent and health checks of all servers
8403 are started with a small time offset between them. It is also possible to
8404 add some random noise in the agent and health checks interval using the
8405 global "spread-checks" keyword. This makes sense for instance when a lot
8406 of backends use the same servers.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008407
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008408 Supported in default-server: Yes
8409
8410maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008411 The "maxconn" parameter specifies the maximal number of concurrent
8412 connections that will be sent to this server. If the number of incoming
8413 concurrent requests goes higher than this value, they will be queued, waiting
8414 for a connection to be released. This parameter is very important as it can
8415 save fragile servers from going down under extreme loads. If a "minconn"
8416 parameter is specified, the limit becomes dynamic. The default value is "0"
8417 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
8418 the backend's "fullconn" keyword.
8419
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008420 Supported in default-server: Yes
8421
8422maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008423 The "maxqueue" parameter specifies the maximal number of connections which
8424 will wait in the queue for this server. If this limit is reached, next
8425 requests will be redispatched to other servers instead of indefinitely
8426 waiting to be served. This will break persistence but may allow people to
8427 quickly re-log in when the server they try to connect to is dying. The
8428 default value is "0" which means the queue is unlimited. See also the
8429 "maxconn" and "minconn" parameters.
8430
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008431 Supported in default-server: Yes
8432
8433minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008434 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
8435 limit following the backend's load. The server will always accept at least
8436 <minconn> connections, never more than <maxconn>, and the limit will be on
8437 the ramp between both values when the backend has less than <fullconn>
8438 concurrent connections. This makes it possible to limit the load on the
8439 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008440 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008441 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01008442
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008443 Supported in default-server: Yes
8444
Emeric Brun9b3009b2012-10-05 11:55:06 +02008445no-sslv3
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02008446 This option disables support for SSLv3 when SSL is used to communicate with
8447 the server. Note that SSLv2 is disabled in the code and cannot be enabled
Emeric Brun8694b9a2012-10-05 14:39:07 +02008448 using any configuration option. See also "force-sslv3", "force-tlsv*".
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02008449
Willy Tarreau763a95b2012-10-04 23:15:39 +02008450 Supported in default-server: No
8451
Emeric Brunf9c5c472012-10-11 15:28:34 +02008452no-tls-tickets
8453 This setting is only available when support for OpenSSL was built in. It
8454 disables the stateless session resumption (RFC 5077 TLS Ticket
8455 extension) and force to use stateful session resumption. Stateless
8456 session resumption is more expensive in CPU usage for servers.
8457
8458 Supported in default-server: No
8459
Emeric Brun9b3009b2012-10-05 11:55:06 +02008460no-tlsv10
Emeric Brun8694b9a2012-10-05 14:39:07 +02008461 This option disables support for TLSv1.0 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +02008462 the server. Note that SSLv2 is disabled in the code and cannot be enabled
8463 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun8694b9a2012-10-05 14:39:07 +02008464 often makes sense to disable it when communicating with local servers. See
8465 also "force-sslv3", "force-tlsv*".
Emeric Brunf5da4932012-09-28 19:42:54 +02008466
Willy Tarreau763a95b2012-10-04 23:15:39 +02008467 Supported in default-server: No
8468
Emeric Brun9b3009b2012-10-05 11:55:06 +02008469no-tlsv11
Emeric Brun8694b9a2012-10-05 14:39:07 +02008470 This option disables support for TLSv1.1 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +02008471 the server. Note that SSLv2 is disabled in the code and cannot be enabled
8472 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun8694b9a2012-10-05 14:39:07 +02008473 often makes sense to disable it when communicating with local servers. See
8474 also "force-sslv3", "force-tlsv*".
Emeric Brunf5da4932012-09-28 19:42:54 +02008475
Willy Tarreau763a95b2012-10-04 23:15:39 +02008476 Supported in default-server: No
8477
Emeric Brun9b3009b2012-10-05 11:55:06 +02008478no-tlsv12
Emeric Brun8694b9a2012-10-05 14:39:07 +02008479 This option disables support for TLSv1.2 when SSL is used to communicate with
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02008480 the server. Note that SSLv2 is disabled in the code and cannot be enabled
8481 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun8694b9a2012-10-05 14:39:07 +02008482 often makes sense to disable it when communicating with local servers. See
8483 also "force-sslv3", "force-tlsv*".
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02008484
Willy Tarreau763a95b2012-10-04 23:15:39 +02008485 Supported in default-server: No
8486
Simon Hormanfa461682011-06-25 09:39:49 +09008487non-stick
8488 Never add connections allocated to this sever to a stick-table.
8489 This may be used in conjunction with backup to ensure that
8490 stick-table persistence is disabled for backup servers.
8491
Willy Tarreau763a95b2012-10-04 23:15:39 +02008492 Supported in default-server: No
8493
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01008494observe <mode>
8495 This option enables health adjusting based on observing communication with
8496 the server. By default this functionality is disabled and enabling it also
8497 requires to enable health checks. There are two supported modes: "layer4" and
8498 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
8499 significant. In layer7, which is only allowed for http proxies, responses
8500 received from server are verified, like valid/wrong http code, unparsable
Willy Tarreau150d1462012-03-10 08:19:02 +01008501 headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01008502
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008503 Supported in default-server: No
8504
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01008505 See also the "check", "on-error" and "error-limit".
8506
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008507on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01008508 Select what should happen when enough consecutive errors are detected.
8509 Currently, four modes are available:
8510 - fastinter: force fastinter
8511 - fail-check: simulate a failed check, also forces fastinter (default)
8512 - sudden-death: simulate a pre-fatal failed health check, one more failed
8513 check will mark a server down, forces fastinter
8514 - mark-down: mark the server immediately down and force fastinter
8515
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008516 Supported in default-server: Yes
8517
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01008518 See also the "check", "observe" and "error-limit".
8519
Simon Hormane0d1bfb2011-06-21 14:34:58 +09008520on-marked-down <action>
8521 Modify what occurs when a server is marked down.
8522 Currently one action is available:
Justin Karnegeseb2c24a2012-05-24 15:28:52 -07008523 - shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
8524 all connections to the server are immediately terminated when the server
8525 goes down. It might be used if the health check detects more complex cases
8526 than a simple connection status, and long timeouts would cause the service
8527 to remain unresponsive for too long a time. For instance, a health check
8528 might detect that a database is stuck and that there's no chance to reuse
8529 existing connections anymore. Connections killed this way are logged with
8530 a 'D' termination code (for "Down").
Simon Hormane0d1bfb2011-06-21 14:34:58 +09008531
8532 Actions are disabled by default
8533
8534 Supported in default-server: Yes
8535
Justin Karnegeseb2c24a2012-05-24 15:28:52 -07008536on-marked-up <action>
8537 Modify what occurs when a server is marked up.
8538 Currently one action is available:
8539 - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
8540 done only if the server is not in backup state and if it is not disabled
8541 (it must have an effective weight > 0). This can be used sometimes to force
8542 an active server to take all the traffic back after recovery when dealing
8543 with long sessions (eg: LDAP, SQL, ...). Doing this can cause more trouble
8544 than it tries to solve (eg: incomplete transactions), so use this feature
8545 with extreme care. Sessions killed because a server comes up are logged
8546 with an 'U' termination code (for "Up").
8547
8548 Actions are disabled by default
8549
8550 Supported in default-server: Yes
8551
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008552port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008553 Using the "port" parameter, it becomes possible to use a different port to
8554 send health-checks. On some servers, it may be desirable to dedicate a port
8555 to a specific component able to perform complex tests which are more suitable
8556 to health-checks than the application. It is common to run a simple script in
8557 inetd for instance. This parameter is ignored if the "check" parameter is not
8558 set. See also the "addr" parameter.
8559
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008560 Supported in default-server: Yes
8561
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008562redir <prefix>
8563 The "redir" parameter enables the redirection mode for all GET and HEAD
8564 requests addressing this server. This means that instead of having HAProxy
8565 forward the request to the server, it will send an "HTTP 302" response with
8566 the "Location" header composed of this prefix immediately followed by the
8567 requested URI beginning at the leading '/' of the path component. That means
8568 that no trailing slash should be used after <prefix>. All invalid requests
8569 will be rejected, and all non-GET or HEAD requests will be normally served by
8570 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008571 mangling nor cookie insertion is possible in the response. However, cookies in
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008572 requests are still analysed, making this solution completely usable to direct
8573 users to a remote location in case of local disaster. Main use consists in
8574 increasing bandwidth for static servers by having the clients directly
8575 connect to them. Note: never use a relative location here, it would cause a
8576 loop between the client and HAProxy!
8577
8578 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
8579
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008580 Supported in default-server: No
8581
8582rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008583 The "rise" parameter states that a server will be considered as operational
8584 after <count> consecutive successful health checks. This value defaults to 2
8585 if unspecified. See also the "check", "inter" and "fall" parameters.
8586
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008587 Supported in default-server: Yes
8588
Willy Tarreau5ab04ec2011-03-20 10:32:26 +01008589send-proxy
8590 The "send-proxy" parameter enforces use of the PROXY protocol over any
8591 connection established to this server. The PROXY protocol informs the other
8592 end about the layer 3/4 addresses of the incoming connection, so that it can
8593 know the client's address or the public address it accessed to, whatever the
8594 upper layer protocol. For connections accepted by an "accept-proxy" listener,
8595 the advertised address will be used. Only TCPv4 and TCPv6 address families
8596 are supported. Other families such as Unix sockets, will report an UNKNOWN
8597 family. Servers using this option can fully be chained to another instance of
8598 haproxy listening with an "accept-proxy" setting. This setting must not be
Willy Tarreau6c16adc2012-10-05 00:04:16 +02008599 used if the server isn't aware of the protocol. When health checks are sent
8600 to the server, the PROXY protocol is automatically used when this option is
8601 set, unless there is an explicit "port" or "addr" directive, in which case an
8602 explicit "check-send-proxy" directive would also be needed to use the PROXY
8603 protocol. See also the "accept-proxy" option of the "bind" keyword.
Willy Tarreau5ab04ec2011-03-20 10:32:26 +01008604
8605 Supported in default-server: No
8606
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008607slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008608 The "slowstart" parameter for a server accepts a value in milliseconds which
8609 indicates after how long a server which has just come back up will run at
8610 full speed. Just as with every other time-based parameter, it can be entered
8611 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
8612 linearly from 0 to 100% during this time. The limitation applies to two
8613 parameters :
8614
8615 - maxconn: the number of connections accepted by the server will grow from 1
8616 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
8617
8618 - weight: when the backend uses a dynamic weighted algorithm, the weight
8619 grows linearly from 1 to 100%. In this case, the weight is updated at every
8620 health-check. For this reason, it is important that the "inter" parameter
8621 is smaller than the "slowstart", in order to maximize the number of steps.
8622
8623 The slowstart never applies when haproxy starts, otherwise it would cause
8624 trouble to running servers. It only applies when a server has been previously
8625 seen as failed.
8626
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008627 Supported in default-server: Yes
8628
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02008629source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02008630source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02008631source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008632 The "source" parameter sets the source address which will be used when
8633 connecting to the server. It follows the exact same parameters and principle
8634 as the backend "source" keyword, except that it only applies to the server
8635 referencing it. Please consult the "source" keyword for details.
8636
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02008637 Additionally, the "source" statement on a server line allows one to specify a
8638 source port range by indicating the lower and higher bounds delimited by a
8639 dash ('-'). Some operating systems might require a valid IP address when a
8640 source port range is specified. It is permitted to have the same IP/range for
8641 several servers. Doing so makes it possible to bypass the maximum of 64k
8642 total concurrent connections. The limit will then reach 64k connections per
8643 server.
8644
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008645 Supported in default-server: No
8646
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02008647ssl
Willy Tarreau44f65392013-06-25 07:56:20 +02008648 This option enables SSL ciphering on outgoing connections to the server. It
8649 is critical to verify server certificates using "verify" when using SSL to
8650 connect to servers, otherwise the communication is prone to trivial man in
8651 the-middle attacks rendering SSL useless. When this option is used, health
8652 checks are automatically sent in SSL too unless there is a "port" or an
8653 "addr" directive indicating the check should be sent to a different location.
8654 See the "check-ssl" optino to force SSL health checks.
Willy Tarreau763a95b2012-10-04 23:15:39 +02008655
8656 Supported in default-server: No
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02008657
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008658track [<proxy>/]<server>
8659 This option enables ability to set the current state of the server by
8660 tracking another one. Only a server with checks enabled can be tracked
8661 so it is not possible for example to track a server that tracks another
8662 one. If <proxy> is omitted the current one is used. If disable-on-404 is
8663 used, it has to be enabled on both proxies.
8664
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008665 Supported in default-server: No
8666
Emeric Brunef42d922012-10-11 16:11:36 +02008667verify [none|required]
8668 This setting is only available when support for OpenSSL was built in. If set
Emeric Brun850efd52014-01-29 12:24:34 +01008669 to 'none', server certificate is not verified. In the other case, The
8670 certificate provided by the server is verified using CAs from 'ca-file'
8671 and optional CRLs from 'crl-file'. If 'ssl_server_verify' is not specified
8672 in global section, this is the default. On verify failure the handshake
Willy Tarreau44f65392013-06-25 07:56:20 +02008673 is aborted. It is critically important to verify server certificates when
8674 using SSL to connect to servers, otherwise the communication is prone to
8675 trivial man-in-the-middle attacks rendering SSL totally useless.
Emeric Brunef42d922012-10-11 16:11:36 +02008676
8677 Supported in default-server: No
8678
Evan Broderbe554312013-06-27 00:05:25 -07008679verifyhost <hostname>
8680 This setting is only available when support for OpenSSL was built in, and
8681 only takes effect if 'verify required' is also specified. When set, the
8682 hostnames in the subject and subjectAlternateNames of the certificate
8683 provided by the server are checked. If none of the hostnames in the
8684 certificate match the specified hostname, the handshake is aborted. The
8685 hostnames in the server-provided certificate may include wildcards.
8686
8687 Supported in default-server: No
8688
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008689weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008690 The "weight" parameter is used to adjust the server's weight relative to
8691 other servers. All servers will receive a load proportional to their weight
8692 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +02008693 load. The default weight is 1, and the maximal value is 256. A value of 0
8694 means the server will not participate in load-balancing but will still accept
8695 persistent connections. If this parameter is used to distribute the load
8696 according to server's capacity, it is recommended to start with values which
8697 can both grow and shrink, for instance between 10 and 100 to leave enough
8698 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008699
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01008700 Supported in default-server: Yes
8701
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008702
87036. HTTP header manipulation
8704---------------------------
8705
8706In HTTP mode, it is possible to rewrite, add or delete some of the request and
8707response headers based on regular expressions. It is also possible to block a
8708request or a response if a particular header matches a regular expression,
8709which is enough to stop most elementary protocol attacks, and to protect
Willy Tarreau70dffda2014-01-30 03:07:23 +01008710against information leak from the internal network.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008711
Willy Tarreau70dffda2014-01-30 03:07:23 +01008712If HAProxy encounters an "Informational Response" (status code 1xx), it is able
8713to process all rsp* rules which can allow, deny, rewrite or delete a header,
8714but it will refuse to add a header to any such messages as this is not
8715HTTP-compliant. The reason for still processing headers in such responses is to
8716stop and/or fix any possible information leak which may happen, for instance
8717because another downstream equipment would unconditionally add a header, or if
8718a server name appears there. When such messages are seen, normal processing
8719still occurs on the next non-informational messages.
Willy Tarreau816b9792009-09-15 21:25:21 +02008720
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008721This section covers common usage of the following keywords, described in detail
8722in section 4.2 :
8723
8724 - reqadd <string>
8725 - reqallow <search>
8726 - reqiallow <search>
8727 - reqdel <search>
8728 - reqidel <search>
8729 - reqdeny <search>
8730 - reqideny <search>
8731 - reqpass <search>
8732 - reqipass <search>
8733 - reqrep <search> <replace>
8734 - reqirep <search> <replace>
8735 - reqtarpit <search>
8736 - reqitarpit <search>
8737 - rspadd <string>
8738 - rspdel <search>
8739 - rspidel <search>
8740 - rspdeny <search>
8741 - rspideny <search>
8742 - rsprep <search> <replace>
8743 - rspirep <search> <replace>
8744
8745With all these keywords, the same conventions are used. The <search> parameter
8746is a POSIX extended regular expression (regex) which supports grouping through
8747parenthesis (without the backslash). Spaces and other delimiters must be
8748prefixed with a backslash ('\') to avoid confusion with a field delimiter.
8749Other characters may be prefixed with a backslash to change their meaning :
8750
8751 \t for a tab
8752 \r for a carriage return (CR)
8753 \n for a new line (LF)
8754 \ to mark a space and differentiate it from a delimiter
8755 \# to mark a sharp and differentiate it from a comment
8756 \\ to use a backslash in a regex
8757 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
8758 \xXX to write the ASCII hex code XX as in the C language
8759
8760The <replace> parameter contains the string to be used to replace the largest
8761portion of text matching the regex. It can make use of the special characters
8762above, and can reference a substring which is delimited by parenthesis in the
8763regex, by writing a backslash ('\') immediately followed by one digit from 0 to
87649 indicating the group position (0 designating the entire line). This practice
8765is very common to users of the "sed" program.
8766
8767The <string> parameter represents the string which will systematically be added
8768after the last header line. It can also use special character sequences above.
8769
8770Notes related to these keywords :
8771---------------------------------
8772 - these keywords are not always convenient to allow/deny based on header
8773 contents. It is strongly recommended to use ACLs with the "block" keyword
8774 instead, resulting in far more flexible and manageable rules.
8775
8776 - lines are always considered as a whole. It is not possible to reference
8777 a header name only or a value only. This is important because of the way
8778 headers are written (notably the number of spaces after the colon).
8779
8780 - the first line is always considered as a header, which makes it possible to
8781 rewrite or filter HTTP requests URIs or response codes, but in turn makes
8782 it harder to distinguish between headers and request line. The regex prefix
8783 ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix
8784 ^[^ \t:]*: matches any header name followed by a colon.
8785
8786 - for performances reasons, the number of characters added to a request or to
8787 a response is limited at build time to values between 1 and 4 kB. This
8788 should normally be far more than enough for most usages. If it is too short
8789 on occasional usages, it is possible to gain some space by removing some
8790 useless headers before adding new ones.
8791
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008792 - keywords beginning with "reqi" and "rspi" are the same as their counterpart
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008793 without the 'i' letter except that they ignore case when matching patterns.
8794
8795 - when a request passes through a frontend then a backend, all req* rules
8796 from the frontend will be evaluated, then all req* rules from the backend
8797 will be evaluated. The reverse path is applied to responses.
8798
8799 - req* statements are applied after "block" statements, so that "block" is
8800 always the first one, but before "use_backend" in order to permit rewriting
Willy Tarreaud72758d2010-01-12 10:42:19 +01008801 before switching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008802
8803
Willy Tarreau74ca5042013-06-11 23:12:07 +020088047. Using ACLs and fetching samples
8805----------------------------------
8806
8807Haproxy is capable of extracting data from request or response streams, from
8808client or server information, from tables, environmental information etc...
8809The action of extracting such data is called fetching a sample. Once retrieved,
8810these samples may be used for various purposes such as a key to a stick-table,
8811but most common usages consist in matching them against predefined constant
8812data called patterns.
8813
8814
88157.1. ACL basics
8816---------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008817
8818The use of Access Control Lists (ACL) provides a flexible solution to perform
8819content switching and generally to take decisions based on content extracted
8820from the request, the response or any environmental status. The principle is
8821simple :
8822
Willy Tarreau74ca5042013-06-11 23:12:07 +02008823 - extract a data sample from a stream, table or the environment
Willy Tarreaue6b11e42013-11-26 19:02:32 +01008824 - optionally apply some format conversion to the extracted sample
Willy Tarreau74ca5042013-06-11 23:12:07 +02008825 - apply one or multiple pattern matching methods on this sample
8826 - perform actions only when a pattern matches the sample
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008827
Willy Tarreau74ca5042013-06-11 23:12:07 +02008828The actions generally consist in blocking a request, selecting a backend, or
8829adding a header.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008830
8831In order to define a test, the "acl" keyword is used. The syntax is :
8832
Willy Tarreau74ca5042013-06-11 23:12:07 +02008833 acl <aclname> <criterion> [flags] [operator] [<value>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008834
8835This creates a new ACL <aclname> or completes an existing one with new tests.
8836Those tests apply to the portion of request/response specified in <criterion>
8837and may be adjusted with optional flags [flags]. Some criteria also support
Willy Tarreaue6b11e42013-11-26 19:02:32 +01008838an operator which may be specified before the set of values. Optionally some
8839conversion operators may be applied to the sample, and they will be specified
8840as a comma-delimited list of keywords just after the first keyword. The values
8841are of the type supported by the criterion, and are separated by spaces.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008842
8843ACL names must be formed from upper and lower case letters, digits, '-' (dash),
8844'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
8845which means that "my_acl" and "My_Acl" are two different ACLs.
8846
8847There is no enforced limit to the number of ACLs. The unused ones do not affect
8848performance, they just consume a small amount of memory.
8849
Willy Tarreau74ca5042013-06-11 23:12:07 +02008850The criterion generally is the name of a sample fetch method, or one of its ACL
8851specific declinations. The default test method is implied by the output type of
8852this sample fetch method. The ACL declinations can describe alternate matching
Willy Tarreaue6b11e42013-11-26 19:02:32 +01008853methods of a same sample fetch method. The sample fetch methods are the only
8854ones supporting a conversion.
Willy Tarreau74ca5042013-06-11 23:12:07 +02008855
8856Sample fetch methods return data which can be of the following types :
8857 - boolean
8858 - integer (signed or unsigned)
8859 - IPv4 or IPv6 address
8860 - string
8861 - data block
8862
Willy Tarreaue6b11e42013-11-26 19:02:32 +01008863Converters transform any of these data into any of these. For example, some
8864converters might convert a string to a lower-case string while other ones
8865would turn a string to an IPv4 address, or apply a netmask to an IP address.
8866The resulting sample is of the type of the last converter applied to the list,
8867which defaults to the type of the sample fetch method.
8868
Willy Tarreau74ca5042013-06-11 23:12:07 +02008869The ACL engine can match these types against patterns of the following types :
8870 - boolean
8871 - integer or integer range
8872 - IP address / network
8873 - string (exact, substring, suffix, prefix, subdir, domain)
8874 - regular expression
8875 - hex block
8876
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008877The following ACL flags are currently supported :
8878
Willy Tarreau2b5285d2010-05-09 23:45:24 +02008879 -i : ignore case during matching of all subsequent patterns.
8880 -f : load patterns from a file.
Willy Tarreau74ca5042013-06-11 23:12:07 +02008881 -m : use a specific pattern matching method
Willy Tarreau6a06a402007-07-15 20:15:28 +02008882 -- : force end of flags. Useful when a string looks like one of the flags.
8883
Willy Tarreau74ca5042013-06-11 23:12:07 +02008884The "-f" flag is followed by the name of a file from which all lines will be
8885read as individual values. It is even possible to pass multiple "-f" arguments
8886if the patterns are to be loaded from multiple files. Empty lines as well as
8887lines beginning with a sharp ('#') will be ignored. All leading spaces and tabs
8888will be stripped. If it is absolutely necessary to insert a valid pattern
8889beginning with a sharp, just prefix it with a space so that it is not taken for
8890a comment. Depending on the data type and match method, haproxy may load the
8891lines into a binary tree, allowing very fast lookups. This is true for IPv4 and
8892exact string matching. In this case, duplicates will automatically be removed.
8893
8894Also, note that the "-i" flag applies to subsequent entries and not to entries
8895loaded from files preceding it. For instance :
8896
8897 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
8898
8899In this example, each line of "exact-ua.lst" will be exactly matched against
8900the "user-agent" header of the request. Then each line of "generic-ua" will be
8901case-insensitively matched. Then the word "test" will be insensitively matched
8902as well.
8903
8904The "-m" flag is used to select a specific pattern matching method on the input
8905sample. All ACL-specific criteria imply a pattern matching method and generally
8906do not need this flag. However, this flag is useful with generic sample fetch
8907methods to describe how they're going to be matched against the patterns. This
8908is required for sample fetches which return data type for which there is no
8909obvious matching method (eg: string or binary). When "-m" is specified and
8910followed by a pattern matching method name, this method is used instead of the
8911default one for the criterion. This makes it possible to match contents in ways
8912that were not initially planned, or with sample fetch methods which return a
8913string. The matching method also affects the way the patterns are parsed.
8914
8915There are some restrictions however. Not all methods can be used with all
8916sample fetch methods. Also, if "-m" is used in conjunction with "-f", it must
8917be placed first. The pattern matching method must be one of the following :
Willy Tarreau5adeda12013-03-31 22:13:34 +02008918
8919 - "found" : only check if the requested sample could be found in the stream,
8920 but do not compare it against any pattern. It is recommended not
Willy Tarreau74ca5042013-06-11 23:12:07 +02008921 to pass any pattern to avoid confusion. This matching method is
8922 particularly useful to detect presence of certain contents such
8923 as headers, cookies, etc... even if they are empty and without
8924 comparing them to anything nor counting them.
Willy Tarreau5adeda12013-03-31 22:13:34 +02008925
8926 - "bool" : check the value as a boolean. It can only be applied to fetches
8927 which return a boolean or integer value, and takes no pattern.
Willy Tarreau74ca5042013-06-11 23:12:07 +02008928 Value zero or false does not match, all other values do match.
Willy Tarreau5adeda12013-03-31 22:13:34 +02008929
8930 - "int" : match the value as an integer. It can be used with integer and
Willy Tarreau74ca5042013-06-11 23:12:07 +02008931 boolean samples. Boolean false is integer 0, true is integer 1.
Willy Tarreau5adeda12013-03-31 22:13:34 +02008932
8933 - "ip" : match the value as an IPv4 or IPv6 address. It is compatible
Willy Tarreau74ca5042013-06-11 23:12:07 +02008934 with IP address samples only, so it is implied and never needed.
Willy Tarreau5adeda12013-03-31 22:13:34 +02008935
8936 - "bin" : match the contents against an hexadecimal string representing a
8937 binary sequence. This may be used with binary or string samples.
8938
8939 - "len" : match the sample's length as an integer. This may be used with
8940 binary or string samples.
8941
Willy Tarreau74ca5042013-06-11 23:12:07 +02008942 - "str" : exact match : match the contents against a string. This may be
8943 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +02008944
Willy Tarreau74ca5042013-06-11 23:12:07 +02008945 - "sub" : substring match : check that the contents contain at least one of
8946 the provided string patterns. This may be used with binary or
8947 string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +02008948
Willy Tarreau74ca5042013-06-11 23:12:07 +02008949 - "reg" : regex match : match the contents against a list of regular
8950 expressions. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +02008951
Willy Tarreau74ca5042013-06-11 23:12:07 +02008952 - "beg" : prefix match : check that the contents begin like the provided
8953 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +02008954
Willy Tarreau74ca5042013-06-11 23:12:07 +02008955 - "end" : suffix match : check that the contents end like the provided
8956 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +02008957
Willy Tarreau74ca5042013-06-11 23:12:07 +02008958 - "dir" : subdir match : check that a slash-delimited portion of the
8959 contents exactly matches one of the provided string patterns.
Willy Tarreau5adeda12013-03-31 22:13:34 +02008960 This may be used with binary or string samples.
8961
Willy Tarreau74ca5042013-06-11 23:12:07 +02008962 - "dom" : domain match : check that a dot-delimited portion of the contents
8963 exactly match one of the provided string patterns. This may be
8964 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +02008965
8966For example, to quickly detect the presence of cookie "JSESSIONID" in an HTTP
8967request, it is possible to do :
8968
8969 acl jsess_present cook(JSESSIONID) -m found
8970
8971In order to apply a regular expression on the 500 first bytes of data in the
8972buffer, one would use the following acl :
8973
8974 acl script_tag payload(0,500) -m reg -i <script>
8975
Willy Tarreaue6b11e42013-11-26 19:02:32 +01008976On systems where the regex library is much slower when using "-i", it is
8977possible to convert the sample to lowercase before matching, like this :
8978
8979 acl script_tag payload(0,500),lower -m reg <script>
8980
Willy Tarreau74ca5042013-06-11 23:12:07 +02008981All ACL-specific criteria imply a default matching method. Most often, these
8982criteria are composed by concatenating the name of the original sample fetch
8983method and the matching method. For example, "hdr_beg" applies the "beg" match
8984to samples retrieved using the "hdr" fetch method. Since all ACL-specific
8985criteria rely on a sample fetch method, it is always possible instead to use
8986the original sample fetch method and the explicit matching method using "-m".
Willy Tarreau2b5285d2010-05-09 23:45:24 +02008987
Willy Tarreau74ca5042013-06-11 23:12:07 +02008988If an alternate match is specified using "-m" on an ACL-specific criterion,
8989the mathing method is simply applied to the underlying sample fetch method. For
8990example, all ACLs below are exact equivalent :
Willy Tarreau2b5285d2010-05-09 23:45:24 +02008991
Willy Tarreau74ca5042013-06-11 23:12:07 +02008992 acl short_form hdr_beg(host) www.
8993 acl alternate1 hdr_beg(host) -m beg www.
8994 acl alternate2 hdr_dom(host) -m beg www.
8995 acl alternate3 hdr(host) -m beg www.
Willy Tarreau2b5285d2010-05-09 23:45:24 +02008996
Willy Tarreau2b5285d2010-05-09 23:45:24 +02008997
Willy Tarreaue6b11e42013-11-26 19:02:32 +01008998The table below summarizes the compatibility matrix between sample types
Willy Tarreau74ca5042013-06-11 23:12:07 +02008999and the pattern types to fetch against. It indicates for each compatible
9000combination the name of the matching method to be used, prefixed with "*" when
9001the method is implicit and will work by default without "-m".
Willy Tarreau0ba27502007-12-24 16:55:16 +01009002
Willy Tarreau74ca5042013-06-11 23:12:07 +02009003 +-------------------------------------------------+
9004 | Input sample type |
9005 +----------------------+---------+---------+---------+---------+---------+
9006 | pattern type | boolean | integer | IP | string | binary |
9007 +----------------------+---------+---------+---------+---------+---------+
9008 | none (presence only) | found | found | found | found | found |
9009 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +01009010 | none (boolean value) | *bool | bool | | bool | |
Willy Tarreau74ca5042013-06-11 23:12:07 +02009011 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +01009012 | integer (value) | int | *int | int | int | |
Willy Tarreau74ca5042013-06-11 23:12:07 +02009013 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +01009014 | integer (length) | len | len | len | len | len |
Willy Tarreau74ca5042013-06-11 23:12:07 +02009015 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +01009016 | IP address | | | *ip | ip | ip |
Willy Tarreau74ca5042013-06-11 23:12:07 +02009017 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +01009018 | exact string | str | str | str | str | str |
Willy Tarreau74ca5042013-06-11 23:12:07 +02009019 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +01009020 | prefix | beg | beg | beg | beg | beg |
Willy Tarreau74ca5042013-06-11 23:12:07 +02009021 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +01009022 | suffix | end | end | end | end | end |
Willy Tarreau74ca5042013-06-11 23:12:07 +02009023 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +01009024 | substring | sub | sub | sub | sub | sub |
Willy Tarreau74ca5042013-06-11 23:12:07 +02009025 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +01009026 | subdir | dir | dir | dir | dir | dir |
Willy Tarreau74ca5042013-06-11 23:12:07 +02009027 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +01009028 | domain | dom | dom | dom | dom | dom |
Willy Tarreau74ca5042013-06-11 23:12:07 +02009029 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +01009030 | regex | reg | reg | reg | reg | reg |
Willy Tarreau74ca5042013-06-11 23:12:07 +02009031 +----------------------+---------+---------+---------+---------+---------+
9032 | hex block | | | | bin | bin |
9033 +----------------------+---------+---------+---------+---------+---------+
Willy Tarreau6a06a402007-07-15 20:15:28 +02009034
9035
Willy Tarreau74ca5042013-06-11 23:12:07 +020090367.1.1. Matching booleans
9037------------------------
9038
9039In order to match a boolean, no value is needed and all values are ignored.
9040Boolean matching is used by default for all fetch methods of type "boolean".
9041When boolean matching is used, the fetched value is returned as-is, which means
9042that a boolean "true" will always match and a boolean "false" will never match.
9043
9044Boolean matching may also be enforced using "-m bool" on fetch methods which
9045return an integer value. Then, integer value 0 is converted to the boolean
9046"false" and all other values are converted to "true".
9047
Willy Tarreau6a06a402007-07-15 20:15:28 +02009048
Willy Tarreau74ca5042013-06-11 23:12:07 +020090497.1.2. Matching integers
9050------------------------
9051
9052Integer matching applies by default to integer fetch methods. It can also be
9053enforced on boolean fetches using "-m int". In this case, "false" is converted
9054to the integer 0, and "true" is converted to the integer 1.
9055
9056Integer matching also supports integer ranges and operators. Note that integer
9057matching only applies to positive values. A range is a value expressed with a
9058lower and an upper bound separated with a colon, both of which may be omitted.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009059
9060For instance, "1024:65535" is a valid range to represent a range of
9061unprivileged ports, and "1024:" would also work. "0:1023" is a valid
9062representation of privileged ports, and ":1023" would also work.
9063
Willy Tarreau62644772008-07-16 18:36:06 +02009064As a special case, some ACL functions support decimal numbers which are in fact
9065two integers separated by a dot. This is used with some version checks for
9066instance. All integer properties apply to those decimal numbers, including
9067ranges and operators.
9068
Willy Tarreau6a06a402007-07-15 20:15:28 +02009069For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +01009070operators with ranges does not make much sense and is strongly discouraged.
9071Similarly, it does not make much sense to perform order comparisons with a set
9072of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009073
Willy Tarreau0ba27502007-12-24 16:55:16 +01009074Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +02009075
9076 eq : true if the tested value equals at least one value
9077 ge : true if the tested value is greater than or equal to at least one value
9078 gt : true if the tested value is greater than at least one value
9079 le : true if the tested value is less than or equal to at least one value
9080 lt : true if the tested value is less than at least one value
9081
Willy Tarreau0ba27502007-12-24 16:55:16 +01009082For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +02009083
9084 acl negative-length hdr_val(content-length) lt 0
9085
Willy Tarreau62644772008-07-16 18:36:06 +02009086This one matches SSL versions between 3.0 and 3.1 (inclusive) :
9087
9088 acl sslv3 req_ssl_ver 3:3.1
9089
Willy Tarreau6a06a402007-07-15 20:15:28 +02009090
Willy Tarreau74ca5042013-06-11 23:12:07 +020090917.1.3. Matching strings
9092-----------------------
9093
9094String matching applies to string or binary fetch methods, and exists in 6
9095different forms :
9096
9097 - exact match (-m str) : the extracted string must exactly match the
9098 patterns ;
9099
9100 - substring match (-m sub) : the patterns are looked up inside the
9101 extracted string, and the ACL matches if any of them is found inside ;
9102
9103 - prefix match (-m beg) : the patterns are compared with the beginning of
9104 the extracted string, and the ACL matches if any of them matches.
9105
9106 - suffix match (-m end) : the patterns are compared with the end of the
9107 extracted string, and the ACL matches if any of them matches.
9108
9109 - subdir match (-m sub) : the patterns are looked up inside the extracted
9110 string, delimited with slashes ("/"), and the ACL matches if any of them
9111 matches.
9112
9113 - domain match (-m dom) : the patterns are looked up inside the extracted
9114 string, delimited with dots ("."), and the ACL matches if any of them
9115 matches.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009116
9117String matching applies to verbatim strings as they are passed, with the
9118exception of the backslash ("\") which makes it possible to escape some
9119characters such as the space. If the "-i" flag is passed before the first
9120string, then the matching will be performed ignoring the case. In order
9121to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +01009122before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02009123
9124
Willy Tarreau74ca5042013-06-11 23:12:07 +020091257.1.4. Matching regular expressions (regexes)
9126---------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02009127
9128Just like with string matching, regex matching applies to verbatim strings as
9129they are passed, with the exception of the backslash ("\") which makes it
9130possible to escape some characters such as the space. If the "-i" flag is
9131passed before the first regex, then the matching will be performed ignoring
9132the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +01009133the "--" flag before the first string. Same principle applies of course to
9134match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02009135
9136
Willy Tarreau74ca5042013-06-11 23:12:07 +020091377.1.5. Matching arbitrary data blocks
9138-------------------------------------
9139
9140It is possible to match some extracted samples against a binary block which may
9141not safely be represented as a string. For this, the patterns must be passed as
9142a series of hexadecimal digits in an even number, when the match method is set
9143to binary. Each sequence of two digits will represent a byte. The hexadecimal
9144digits may be used upper or lower case.
9145
9146Example :
9147 # match "Hello\n" in the input stream (\x48 \x65 \x6c \x6c \x6f \x0a)
9148 acl hello payload(0,6) -m bin 48656c6c6f0a
9149
9150
91517.1.6. Matching IPv4 and IPv6 addresses
9152---------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02009153
9154IPv4 addresses values can be specified either as plain addresses or with a
9155netmask appended, in which case the IPv4 address matches whenever it is
9156within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01009157host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +01009158difficult to read and debug configurations. If hostnames are used, you should
9159at least ensure that they are present in /etc/hosts so that the configuration
9160does not depend on any random DNS match at the moment the configuration is
9161parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009162
Willy Tarreauceb4ac92012-04-28 00:41:46 +02009163IPv6 may be entered in their usual form, with or without a netmask appended.
9164Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of
9165trouble with randomly resolved IP addresses, host names are never allowed in
9166IPv6 patterns.
9167
9168HAProxy is also able to match IPv4 addresses with IPv6 addresses in the
9169following situations :
9170 - tested address is IPv4, pattern address is IPv4, the match applies
9171 in IPv4 using the supplied mask if any.
9172 - tested address is IPv6, pattern address is IPv6, the match applies
9173 in IPv6 using the supplied mask if any.
9174 - tested address is IPv6, pattern address is IPv4, the match applies in IPv4
9175 using the pattern's mask if the IPv6 address matches with 2002:IPV4::,
9176 ::IPV4 or ::ffff:IPV4, otherwise it fails.
9177 - tested address is IPv4, pattern address is IPv6, the IPv4 address is first
9178 converted to IPv6 by prefixing ::ffff: in front of it, then the match is
9179 applied in IPv6 using the supplied IPv6 mask.
9180
Willy Tarreau74ca5042013-06-11 23:12:07 +02009181
91827.2. Using ACLs to form conditions
9183----------------------------------
9184
9185Some actions are only performed upon a valid condition. A condition is a
9186combination of ACLs with operators. 3 operators are supported :
9187
9188 - AND (implicit)
9189 - OR (explicit with the "or" keyword or the "||" operator)
9190 - Negation with the exclamation mark ("!")
Willy Tarreau6a06a402007-07-15 20:15:28 +02009191
Willy Tarreau74ca5042013-06-11 23:12:07 +02009192A condition is formed as a disjunctive form:
Willy Tarreau6a06a402007-07-15 20:15:28 +02009193
Willy Tarreau74ca5042013-06-11 23:12:07 +02009194 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreaubef91e72013-03-31 23:14:46 +02009195
Willy Tarreau74ca5042013-06-11 23:12:07 +02009196Such conditions are generally used after an "if" or "unless" statement,
9197indicating when the condition will trigger the action.
Willy Tarreaubef91e72013-03-31 23:14:46 +02009198
Willy Tarreau74ca5042013-06-11 23:12:07 +02009199For instance, to block HTTP requests to the "*" URL with methods other than
9200"OPTIONS", as well as POST requests without content-length, and GET or HEAD
9201requests with a content-length greater than 0, and finally every request which
9202is not either GET/HEAD/POST/OPTIONS !
9203
9204 acl missing_cl hdr_cnt(Content-length) eq 0
9205 block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
9206 block if METH_GET HTTP_CONTENT
9207 block unless METH_GET or METH_POST or METH_OPTIONS
9208
9209To select a different backend for requests to static contents on the "www" site
9210and to every request on the "img", "video", "download" and "ftp" hosts :
9211
9212 acl url_static path_beg /static /images /img /css
9213 acl url_static path_end .gif .png .jpg .css .js
9214 acl host_www hdr_beg(host) -i www
9215 acl host_static hdr_beg(host) -i img. video. download. ftp.
9216
9217 # now use backend "static" for all static-only hosts, and for static urls
9218 # of host "www". Use backend "www" for the rest.
9219 use_backend static if host_static or host_www url_static
9220 use_backend www if host_www
9221
9222It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
9223expressions that are built on the fly without needing to be declared. They must
9224be enclosed between braces, with a space before and after each brace (because
9225the braces must be seen as independent words). Example :
9226
9227 The following rule :
9228
9229 acl missing_cl hdr_cnt(Content-length) eq 0
9230 block if METH_POST missing_cl
9231
9232 Can also be written that way :
9233
9234 block if METH_POST { hdr_cnt(Content-length) eq 0 }
9235
9236It is generally not recommended to use this construct because it's a lot easier
9237to leave errors in the configuration when written that way. However, for very
9238simple rules matching only one source IP address for instance, it can make more
9239sense to use them than to declare ACLs with random names. Another example of
9240good use is the following :
9241
9242 With named ACLs :
9243
9244 acl site_dead nbsrv(dynamic) lt 2
9245 acl site_dead nbsrv(static) lt 2
9246 monitor fail if site_dead
9247
9248 With anonymous ACLs :
9249
9250 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
9251
9252See section 4.2 for detailed help on the "block" and "use_backend" keywords.
9253
9254
92557.3. Fetching samples
9256---------------------
9257
9258Historically, sample fetch methods were only used to retrieve data to match
9259against patterns using ACLs. With the arrival of stick-tables, a new class of
9260sample fetch methods was created, most often sharing the same syntax as their
9261ACL counterpart. These sample fetch methods are also known as "fetches". As
9262of now, ACLs and fetches have converged. All ACL fetch methods have been made
9263available as fetch methods, and ACLs may use any sample fetch method as well.
9264
9265This section details all available sample fetch methods and their output type.
9266Some sample fetch methods have deprecated aliases that are used to maintain
9267compatibility with existing configurations. They are then explicitly marked as
9268deprecated and should not be used in new setups.
9269
9270The ACL derivatives are also indicated when available, with their respective
9271matching methods. These ones all have a well defined default pattern matching
9272method, so it is never necessary (though allowed) to pass the "-m" option to
9273indicate how the sample will be matched using ACLs.
9274
9275As indicated in the sample type versus matching compatibility matrix above,
9276when using a generic sample fetch method in an ACL, the "-m" option is
9277mandatory unless the sample type is one of boolean, integer, IPv4 or IPv6. When
9278the same keyword exists as an ACL keyword and as a standard fetch method, the
9279ACL engine will automatically pick the ACL-only one by default.
9280
9281Some of these keywords support one or multiple mandatory arguments, and one or
9282multiple optional arguments. These arguments are strongly typed and are checked
9283when the configuration is parsed so that there is no risk of running with an
9284incorrect argument (eg: an unresolved backend name). Fetch function arguments
9285are passed between parenthesis and are delimited by commas. When an argument
9286is optional, it will be indicated below between square brackets ('[ ]'). When
9287all arguments are optional, the parenthesis may be omitted.
9288
9289Thus, the syntax of a standard sample fetch method is one of the following :
9290 - name
9291 - name(arg1)
9292 - name(arg1,arg2)
9293
Willy Tarreaue6b11e42013-11-26 19:02:32 +01009294Sample fetch methods may be combined with transformations to be applied on top
9295of the fetched sample (also called "converters"). These combinations form what
9296is called "sample expressions" and the result is a "sample". Initially this
9297was only supported by "stick on" and "stick store-request" directives but this
9298has now be extended to all places where samples may be used (acls, log-format,
9299unique-id-format, add-header, ...).
9300
9301These transformations are enumerated as a series of specific keywords after the
9302sample fetch method. These keywords may equally be appended immediately after
9303the fetch keyword's argument, delimited by a comma. These keywords can also
9304support some arguments (eg: a netmask) which must be passed in parenthesis.
Willy Tarreau0ba27502007-12-24 16:55:16 +01009305
Willy Tarreau74ca5042013-06-11 23:12:07 +02009306The currently available list of transformation keywords include :
Willy Tarreau0ba27502007-12-24 16:55:16 +01009307
Willy Tarreau74ca5042013-06-11 23:12:07 +02009308 lower Convert a string sample to lower case. This can only be placed
9309 after a string sample fetch function or after a transformation
9310 keyword returning a string type. The result is of type string.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009311
Willy Tarreau74ca5042013-06-11 23:12:07 +02009312 upper Convert a string sample to upper case. This can only be placed
9313 after a string sample fetch function or after a transformation
9314 keyword returning a string type. The result is of type string.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009315
Willy Tarreau74ca5042013-06-11 23:12:07 +02009316 ipmask(<mask>) Apply a mask to an IPv4 address, and use the result for
9317 lookups and storage. This can be used to make all hosts within
9318 a certain mask to share the same table entries and as such use
9319 the same server. The mask can be passed in dotted form (eg:
9320 255.255.255.0) or in CIDR form (eg: 24).
9321
Willy Tarreau276fae92013-07-25 14:36:01 +02009322 http_date([<offset>])
9323 Converts an integer supposed to contain a date since epoch to
9324 a string representing this date in a format suitable for use
9325 in HTTP header fields. If an offset value is specified, then
9326 it is a number of seconds that is added to the date before the
9327 conversion is operated. This is particularly useful to emit
9328 Date header fields, Expires values in responses when combined
9329 with a positive offset, or Last-Modified values when the
9330 offset is negative.
Willy Tarreau74ca5042013-06-11 23:12:07 +02009331
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +01009332 map(<map_file>[,<default_value>])
9333 map_<match_type>(<map_file>[,<default_value>])
9334 map_<match_type>_<output_type>(<map_file>[,<default_value>])
9335 Search the input value from <map_file> using the <match_type>
9336 matching method, and return the associated value converted to
9337 the type <output_type>. If the input value cannot be found in
9338 the <map_file>, the converter returns the <default_value>. If
9339 the <default_value> is not set, the converter fails and acts
9340 as if no input value could be fetched. If the <match_type> is
9341 not set, it defaults to "str". Likewise, if the <output_type>
9342 is not set, it defaults to "str". For convenience, the "map"
9343 keyword is an alias for "map_str" and maps a string to another
9344 string. The following array contains contains the list of all
9345 the map* converters.
9346
9347 It is important to avoid overlapping between the keys : IP
9348 addresses and strings are stored in trees, so the first of the
9349 finest match will be used. Other keys are stored in lists, so
9350 the first matching occurrence will be used.
9351
9352 +----+----------+---------+-------------+------------+
9353 | `-_ out | | | |
9354 | input `-_ | str | int | ip |
9355 | / match `-_ | | | |
9356 +---------------+---------+-------------+------------+
9357 | str / str | map_str | map_str_int | map_str_ip |
9358 | str / sub | map_sub | map_sub_int | map_sub_ip |
9359 | str / dir | map_dir | map_dir_int | map_dir_ip |
9360 | str / dom | map_dom | map_dom_int | map_dom_ip |
9361 | str / end | map_end | map_end_int | map_end_ip |
9362 | str / reg | map_reg | map_reg_int | map_reg_ip |
9363 | int / int | map_int | map_int_int | map_int_ip |
9364 | ip / ip | map_ip | map_ip_int | map_ip_ip |
9365 +---------------+---------+-------------+------------+
9366
9367 The file contains one key + value per line. Lines which start
9368 with '#' are ignored, just like empty lines. Leading tabs and
9369 spaces are stripped. The key is then the first "word" (series
9370 of non-space/tabs characters), and the value is what follows
9371 this series of space/tab till the end of the line excluding
9372 trailing spaces/tabs.
9373
9374 Example :
9375
9376 # this is a comment and is ignored
9377 2.22.246.0/23 United Kingdom \n
9378 <-><-----------><--><------------><---->
9379 | | | | `- trailing spaces ignored
9380 | | | `----------- value
9381 | | `--------------------- middle spaces ignored
9382 | `---------------------------- key
9383 `------------------------------------ leading spaces ignored
9384
Willy Tarreau74ca5042013-06-11 23:12:07 +020093857.3.1. Fetching samples from internal states
9386--------------------------------------------
9387
9388A first set of sample fetch methods applies to internal information which does
9389not even relate to any client information. These ones are sometimes used with
9390"monitor-fail" directives to report an internal status to external watchers.
9391The sample fetch methods described in this section are usable anywhere.
9392
9393always_false : boolean
9394 Always returns the boolean "false" value. It may be used with ACLs as a
9395 temporary replacement for another one when adjusting configurations.
9396
9397always_true : boolean
9398 Always returns the boolean "true" value. It may be used with ACLs as a
9399 temporary replacement for another one when adjusting configurations.
9400
9401avg_queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +01009402 Returns the total number of queued connections of the designated backend
Willy Tarreau74ca5042013-06-11 23:12:07 +02009403 divided by the number of active servers. The current backend is used if no
9404 backend is specified. This is very similar to "queue" except that the size of
9405 the farm is considered, in order to give a more accurate measurement of the
9406 time it may take for a new connection to be processed. The main usage is with
9407 ACL to return a sorry page to new users when it becomes certain they will get
9408 a degraded service, or to pass to the backend servers in a header so that
9409 they decide to work in degraded mode or to disable some functions to speed up
9410 the processing a bit. Note that in the event there would not be any active
9411 server anymore, twice the number of queued connections would be considered as
9412 the measured value. This is a fair estimate, as we expect one server to get
9413 back soon anyway, but we still prefer to send new traffic to another backend
9414 if in better shape. See also the "queue", "be_conn", and "be_sess_rate"
9415 sample fetches.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +01009416
Willy Tarreau74ca5042013-06-11 23:12:07 +02009417be_conn([<backend>]) : integer
Willy Tarreaua36af912009-10-10 12:02:45 +02009418 Applies to the number of currently established connections on the backend,
9419 possibly including the connection being evaluated. If no backend name is
9420 specified, the current one is used. But it is also possible to check another
9421 backend. It can be used to use a specific farm when the nominal one is full.
9422 See also the "fe_conn", "queue" and "be_sess_rate" criteria.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009423
Willy Tarreau74ca5042013-06-11 23:12:07 +02009424be_sess_rate([<backend>]) : integer
9425 Returns an integer value corresponding to the sessions creation rate on the
9426 backend, in number of new sessions per second. This is used with ACLs to
9427 switch to an alternate backend when an expensive or fragile one reaches too
9428 high a session rate, or to limit abuse of service (eg. prevent sucking of an
9429 online dictionary). It can also be useful to add this element to logs using a
9430 log-format directive.
Willy Tarreaud63335a2010-02-26 12:56:52 +01009431
9432 Example :
9433 # Redirect to an error page if the dictionary is requested too often
9434 backend dynamic
9435 mode http
9436 acl being_scanned be_sess_rate gt 100
9437 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +01009438
Willy Tarreau74ca5042013-06-11 23:12:07 +02009439connslots([<backend>]) : integer
9440 Returns an integer value corresponding to the number of connection slots
9441 still available in the backend, by totalizing the maximum amount of
9442 connections on all servers and the maximum queue size. This is probably only
9443 used with ACLs.
Tait Clarridge7896d522012-12-05 21:39:31 -05009444
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08009445 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +02009446 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08009447 usage; see "use_backend" keyword) can be redirected to a different backend.
9448
Willy Tarreau55165fe2009-05-10 12:02:55 +02009449 'connslots' = number of available server connection slots, + number of
9450 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08009451
Willy Tarreaua36af912009-10-10 12:02:45 +02009452 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +02009453 useful when you have a case of traffic going to one single ip, splitting into
Willy Tarreau74ca5042013-06-11 23:12:07 +02009454 multiple backends (perhaps using ACLs to do name-based load balancing) and
Willy Tarreau55165fe2009-05-10 12:02:55 +02009455 you want to be able to differentiate between different backends, and their
9456 available "connslots". Also, whereas "nbsrv" only measures servers that are
Willy Tarreau74ca5042013-06-11 23:12:07 +02009457 actually *down*, this fetch is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +02009458 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08009459
Willy Tarreau55165fe2009-05-10 12:02:55 +02009460 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
9461 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
Willy Tarreau74ca5042013-06-11 23:12:07 +02009462 then this fetch clearly does not make sense, in which case the value returned
Willy Tarreau55165fe2009-05-10 12:02:55 +02009463 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08009464
Willy Tarreau6236d3a2013-07-25 14:28:25 +02009465date([<offset>]) : integer
9466 Returns the current date as the epoch (number of seconds since 01/01/1970).
9467 If an offset value is specified, then it is a number of seconds that is added
9468 to the current date before returning the value. This is particularly useful
9469 to compute relative dates, as both positive and negative offsets are allowed.
Willy Tarreau276fae92013-07-25 14:36:01 +02009470 It is useful combined with the http_date converter.
9471
9472 Example :
9473
9474 # set an expires header to now+1 hour in every response
9475 http-response set-header Expires %[date(3600),http_date]
Willy Tarreau6236d3a2013-07-25 14:28:25 +02009476
Willy Tarreau595ec542013-06-12 21:34:28 +02009477env(<name>) : string
9478 Returns a string containing the value of environment variable <name>. As a
9479 reminder, environment variables are per-process and are sampled when the
9480 process starts. This can be useful to pass some information to a next hop
9481 server, or with ACLs to take specific action when the process is started a
9482 certain way.
9483
9484 Examples :
9485 # Pass the Via header to next hop with the local hostname in it
9486 http-request add-header Via 1.1\ %[env(HOSTNAME)]
9487
9488 # reject cookie-less requests when the STOP environment variable is set
9489 http-request deny if !{ cook(SESSIONID) -m found } { env(STOP) -m found }
9490
Willy Tarreau74ca5042013-06-11 23:12:07 +02009491fe_conn([<frontend>]) : integer
9492 Returns the number of currently established connections on the frontend,
Willy Tarreaud63335a2010-02-26 12:56:52 +01009493 possibly including the connection being evaluated. If no frontend name is
9494 specified, the current one is used. But it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +02009495 frontend. It can be used to return a sorry page before hard-blocking, or to
9496 use a specific backend to drain new requests when the farm is considered
9497 full. This is mostly used with ACLs but can also be used to pass some
9498 statistics to servers in HTTP headers. See also the "dst_conn", "be_conn",
9499 "fe_sess_rate" fetches.
Willy Tarreaua36af912009-10-10 12:02:45 +02009500
Willy Tarreau74ca5042013-06-11 23:12:07 +02009501fe_sess_rate([<frontend>]) : integer
9502 Returns an integer value corresponding to the sessions creation rate on the
9503 frontend, in number of new sessions per second. This is used with ACLs to
9504 limit the incoming session rate to an acceptable range in order to prevent
9505 abuse of service at the earliest moment, for example when combined with other
9506 layer 4 ACLs in order to force the clients to wait a bit for the rate to go
9507 down below the limit. It can also be useful to add this element to logs using
9508 a log-format directive. See also the "rate-limit sessions" directive for use
9509 in frontends.
Willy Tarreau079ff0a2009-03-05 21:34:28 +01009510
9511 Example :
9512 # This frontend limits incoming mails to 10/s with a max of 100
9513 # concurrent connections. We accept any connection below 10/s, and
9514 # force excess clients to wait for 100 ms. Since clients are limited to
9515 # 100 max, there cannot be more than 10 incoming mails per second.
9516 frontend mail
9517 bind :25
9518 mode tcp
9519 maxconn 100
9520 acl too_fast fe_sess_rate ge 10
9521 tcp-request inspect-delay 100ms
9522 tcp-request content accept if ! too_fast
9523 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +01009524
Willy Tarreau74ca5042013-06-11 23:12:07 +02009525nbsrv([<backend>]) : integer
9526 Returns an integer value corresponding to the number of usable servers of
9527 either the current backend or the named backend. This is mostly used with
9528 ACLs but can also be useful when added to logs. This is normally used to
Willy Tarreaud63335a2010-02-26 12:56:52 +01009529 switch to an alternate backend when the number of servers is too low to
9530 to handle some load. It is useful to report a failure when combined with
9531 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +01009532
Willy Tarreau74ca5042013-06-11 23:12:07 +02009533queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +01009534 Returns the total number of queued connections of the designated backend,
9535 including all the connections in server queues. If no backend name is
9536 specified, the current one is used, but it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +02009537 one. This is useful with ACLs or to pass statistics to backend servers. This
9538 can be used to take actions when queuing goes above a known level, generally
9539 indicating a surge of traffic or a massive slowdown on the servers. One
9540 possible action could be to reject new users but still accept old ones. See
9541 also the "avg_queue", "be_conn", and "be_sess_rate" fetches.
9542
9543srv_conn([<backend>/]<server>) : integer
9544 Returns an integer value corresponding to the number of currently established
9545 connections on the designated server, possibly including the connection being
9546 evaluated. If <backend> is omitted, then the server is looked up in the
9547 current backend. It can be used to use a specific farm when one server is
9548 full, or to inform the server about our view of the number of active
9549 connections with it. See also the "fe_conn", "be_conn" and "queue" fetch
9550 methods.
9551
9552srv_is_up([<backend>/]<server>) : boolean
9553 Returns true when the designated server is UP, and false when it is either
9554 DOWN or in maintenance mode. If <backend> is omitted, then the server is
9555 looked up in the current backend. It is mainly used to take action based on
9556 an external status reported via a health check (eg: a geographical site's
9557 availability). Another possible use which is more of a hack consists in
9558 using dummy servers as boolean variables that can be enabled or disabled from
9559 the CLI, so that rules depending on those ACLs can be tweaked in realtime.
9560
9561srv_sess_rate([<backend>/]<server>) : integer
9562 Returns an integer corresponding to the sessions creation rate on the
9563 designated server, in number of new sessions per second. If <backend> is
9564 omitted, then the server is looked up in the current backend. This is mosly
9565 used with ACLs but can make sense with logs too. This is used to switch to an
9566 alternate backend when an expensive or fragile one reaches too high a session
9567 rate, or to limit abuse of service (eg. prevent latent requests from
9568 overloading servers).
9569
9570 Example :
9571 # Redirect to a separate back
9572 acl srv1_full srv_sess_rate(be1/srv1) gt 50
9573 acl srv2_full srv_sess_rate(be1/srv2) gt 50
9574 use_backend be2 if srv1_full or srv2_full
9575
9576table_avl([<table>]) : integer
9577 Returns the total number of available entries in the current proxy's
9578 stick-table or in the designated stick-table. See also table_cnt.
9579
9580table_cnt([<table>]) : integer
9581 Returns the total number of entries currently in use in the current proxy's
9582 stick-table or in the designated stick-table. See also src_conn_cnt and
9583 table_avl for other entry counting methods.
9584
9585
95867.3.2. Fetching samples at Layer 4
9587----------------------------------
9588
9589The layer 4 usually describes just the transport layer which in haproxy is
9590closest to the connection, where no content is yet made available. The fetch
9591methods described here are usable as low as the "tcp-request connection" rule
9592sets unless they require some future information. Those generally include
9593TCP/IP addresses and ports, as well as elements from stick-tables related to
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009594the incoming connection. For retrieving a value from a sticky counters, the
9595counter number can be explicitly set as 0, 1, or 2 using the pre-defined
9596"sc0_", "sc1_", or "sc2_" prefix, or it can be specified as the first integer
Willy Tarreau0f791d42013-07-23 19:56:43 +02009597argument when using the "sc_" prefix. An optional table may be specified with
9598the "sc*" form, in which case the currently tracked key will be looked up into
9599this alternate table instead of the table currently being tracked.
Willy Tarreau74ca5042013-06-11 23:12:07 +02009600
9601be_id : integer
9602 Returns an integer containing the current backend's id. It can be used in
9603 frontends with responses to check which backend processed the request.
9604
9605dst : ip
9606 This is the destination IPv4 address of the connection on the client side,
9607 which is the address the client connected to. It can be useful when running
9608 in transparent mode. It is of type IP and works on both IPv4 and IPv6 tables.
9609 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent, according to
9610 RFC 4291.
9611
9612dst_conn : integer
9613 Returns an integer value corresponding to the number of currently established
9614 connections on the same socket including the one being evaluated. It is
9615 normally used with ACLs but can as well be used to pass the information to
9616 servers in an HTTP header or in logs. It can be used to either return a sorry
9617 page before hard-blocking, or to use a specific backend to drain new requests
9618 when the socket is considered saturated. This offers the ability to assign
9619 different limits to different listening ports or addresses. See also the
9620 "fe_conn" and "be_conn" fetches.
Willy Tarreaud63335a2010-02-26 12:56:52 +01009621
Willy Tarreau74ca5042013-06-11 23:12:07 +02009622dst_port : integer
9623 Returns an integer value corresponding to the destination TCP port of the
9624 connection on the client side, which is the port the client connected to.
9625 This might be used when running in transparent mode, when assigning dynamic
9626 ports to some clients for a whole application session, to stick all users to
9627 a same server, or to pass the destination port information to a server using
9628 an HTTP header.
9629
9630fe_id : integer
9631 Returns an integer containing the current frontend's id. It can be used in
9632 backends to check from which backend it was called, or to stick all users
9633 coming via a same frontend to the same server.
9634
Willy Tarreau0f791d42013-07-23 19:56:43 +02009635sc_bytes_in_rate(<ctr>,[<table>]) : integer
9636sc0_bytes_in_rate([<table>]) : integer
9637sc1_bytes_in_rate([<table>]) : integer
9638sc2_bytes_in_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009639 Returns the average client-to-server bytes rate from the currently tracked
9640 counters, measured in amount of bytes over the period configured in the
9641 table. See also src_bytes_in_rate.
9642
Willy Tarreau0f791d42013-07-23 19:56:43 +02009643sc_bytes_out_rate(<ctr>,[<table>]) : integer
9644sc0_bytes_out_rate([<table>]) : integer
9645sc1_bytes_out_rate([<table>]) : integer
9646sc2_bytes_out_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009647 Returns the average server-to-client bytes rate from the currently tracked
9648 counters, measured in amount of bytes over the period configured in the
9649 table. See also src_bytes_out_rate.
9650
Willy Tarreau0f791d42013-07-23 19:56:43 +02009651sc_clr_gpc0(<ctr>,[<table>]) : integer
9652sc0_clr_gpc0([<table>]) : integer
9653sc1_clr_gpc0([<table>]) : integer
9654sc2_clr_gpc0([<table>]) : integer
Willy Tarreauf73cd112011-08-13 01:45:16 +02009655 Clears the first General Purpose Counter associated to the currently tracked
9656 counters, and returns its previous value. Before the first invocation, the
Willy Tarreau869948b2013-01-04 14:14:57 +01009657 stored value is zero, so first invocation will always return zero. This is
9658 typically used as a second ACL in an expression in order to mark a connection
9659 when a first ACL was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +02009660
9661 # block if 5 consecutive requests continue to come faster than 10 sess
9662 # per second, and reset the counter as soon as the traffic slows down.
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009663 acl abuse sc0_http_req_rate gt 10
9664 acl kill sc0_inc_gpc0 gt 5
9665 acl save sc0_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +02009666 tcp-request connection accept if !abuse save
9667 tcp-request connection reject if abuse kill
9668
Willy Tarreau0f791d42013-07-23 19:56:43 +02009669sc_conn_cnt(<ctr>,[<table>]) : integer
9670sc0_conn_cnt([<table>]) : integer
9671sc1_conn_cnt([<table>]) : integer
9672sc2_conn_cnt([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009673 Returns the cumulated number of incoming connections from currently tracked
9674 counters. See also src_conn_cnt.
9675
Willy Tarreau0f791d42013-07-23 19:56:43 +02009676sc_conn_cur(<ctr>,[<table>]) : integer
9677sc0_conn_cur([<table>]) : integer
9678sc1_conn_cur([<table>]) : integer
9679sc2_conn_cur([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009680 Returns the current amount of concurrent connections tracking the same
9681 tracked counters. This number is automatically incremented when tracking
9682 begins and decremented when tracking stops. See also src_conn_cur.
9683
Willy Tarreau0f791d42013-07-23 19:56:43 +02009684sc_conn_rate(<ctr>,[<table>]) : integer
9685sc0_conn_rate([<table>]) : integer
9686sc1_conn_rate([<table>]) : integer
9687sc2_conn_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009688 Returns the average connection rate from the currently tracked counters,
9689 measured in amount of connections over the period configured in the table.
9690 See also src_conn_rate.
9691
Willy Tarreau0f791d42013-07-23 19:56:43 +02009692sc_get_gpc0(<ctr>,[<table>]) : integer
9693sc0_get_gpc0([<table>]) : integer
9694sc1_get_gpc0([<table>]) : integer
9695sc2_get_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009696 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009697 currently tracked counters. See also src_get_gpc0 and sc/sc0/sc1/sc2_inc_gpc0.
Willy Tarreauba2ffd12013-05-29 15:54:14 +02009698
Willy Tarreau0f791d42013-07-23 19:56:43 +02009699sc_gpc0_rate(<ctr>,[<table>]) : integer
9700sc0_gpc0_rate([<table>]) : integer
9701sc1_gpc0_rate([<table>]) : integer
9702sc2_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +02009703 Returns the average increment rate of the first General Purpose Counter
9704 associated to the currently tracked counters. It reports the frequency
9705 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009706 src_gpc0_rate, sc/sc0/sc1/sc2_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
9707 that the "gpc0_rate" counter must be stored in the stick-table for a value to
9708 be returned, as "gpc0" only holds the event count.
Willy Tarreaue9656522010-08-17 15:40:09 +02009709
Willy Tarreau0f791d42013-07-23 19:56:43 +02009710sc_http_err_cnt(<ctr>,[<table>]) : integer
9711sc0_http_err_cnt([<table>]) : integer
9712sc1_http_err_cnt([<table>]) : integer
9713sc2_http_err_cnt([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009714 Returns the cumulated number of HTTP errors from the currently tracked
9715 counters. This includes the both request errors and 4xx error responses.
9716 See also src_http_err_cnt.
9717
Willy Tarreau0f791d42013-07-23 19:56:43 +02009718sc_http_err_rate(<ctr>,[<table>]) : integer
9719sc0_http_err_rate([<table>]) : integer
9720sc1_http_err_rate([<table>]) : integer
9721sc2_http_err_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009722 Returns the average rate of HTTP errors from the currently tracked counters,
9723 measured in amount of errors over the period configured in the table. This
9724 includes the both request errors and 4xx error responses. See also
9725 src_http_err_rate.
9726
Willy Tarreau0f791d42013-07-23 19:56:43 +02009727sc_http_req_cnt(<ctr>,[<table>]) : integer
9728sc0_http_req_cnt([<table>]) : integer
9729sc1_http_req_cnt([<table>]) : integer
9730sc2_http_req_cnt([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009731 Returns the cumulated number of HTTP requests from the currently tracked
9732 counters. This includes every started request, valid or not. See also
9733 src_http_req_cnt.
9734
Willy Tarreau0f791d42013-07-23 19:56:43 +02009735sc_http_req_rate(<ctr>,[<table>]) : integer
9736sc0_http_req_rate([<table>]) : integer
9737sc1_http_req_rate([<table>]) : integer
9738sc2_http_req_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009739 Returns the average rate of HTTP requests from the currently tracked
9740 counters, measured in amount of requests over the period configured in
9741 the table. This includes every started request, valid or not. See also
9742 src_http_req_rate.
9743
Willy Tarreau0f791d42013-07-23 19:56:43 +02009744sc_inc_gpc0(<ctr>,[<table>]) : integer
9745sc0_inc_gpc0([<table>]) : integer
9746sc1_inc_gpc0([<table>]) : integer
9747sc2_inc_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009748 Increments the first General Purpose Counter associated to the currently
Willy Tarreau869948b2013-01-04 14:14:57 +01009749 tracked counters, and returns its new value. Before the first invocation,
9750 the stored value is zero, so first invocation will increase it to 1 and will
9751 return 1. This is typically used as a second ACL in an expression in order
9752 to mark a connection when a first ACL was verified :
Willy Tarreaue9656522010-08-17 15:40:09 +02009753
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009754 acl abuse sc0_http_req_rate gt 10
9755 acl kill sc0_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +02009756 tcp-request connection reject if abuse kill
9757
Willy Tarreau0f791d42013-07-23 19:56:43 +02009758sc_kbytes_in(<ctr>,[<table>]) : integer
9759sc0_kbytes_in([<table>]) : integer
9760sc1_kbytes_in([<table>]) : integer
9761sc2_kbytes_in([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009762 Returns the amount of client-to-server data from the currently tracked
9763 counters, measured in kilobytes over the period configured in the table. The
9764 test is currently performed on 32-bit integers, which limits values to 4
9765 terabytes. See also src_kbytes_in.
9766
Willy Tarreau0f791d42013-07-23 19:56:43 +02009767sc_kbytes_out(<ctr>,[<table>]) : integer
9768sc0_kbytes_out([<table>]) : integer
9769sc1_kbytes_out([<table>]) : integer
9770sc2_kbytes_out([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009771 Returns the amount of server-to-client data from the currently tracked
9772 counters, measured in kilobytes over the period configured in the table. The
9773 test is currently performed on 32-bit integers, which limits values to 4
9774 terabytes. See also src_kbytes_out.
9775
Willy Tarreau0f791d42013-07-23 19:56:43 +02009776sc_sess_cnt(<ctr>,[<table>]) : integer
9777sc0_sess_cnt([<table>]) : integer
9778sc1_sess_cnt([<table>]) : integer
9779sc2_sess_cnt([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009780 Returns the cumulated number of incoming connections that were transformed
9781 into sessions, which means that they were accepted by a "tcp-request
9782 connection" rule, from the currently tracked counters. A backend may count
9783 more sessions than connections because each connection could result in many
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009784 backend sessions if some HTTP keep-alive is performed over the connection
Willy Tarreaue9656522010-08-17 15:40:09 +02009785 with the client. See also src_sess_cnt.
9786
Willy Tarreau0f791d42013-07-23 19:56:43 +02009787sc_sess_rate(<ctr>,[<table>]) : integer
9788sc0_sess_rate([<table>]) : integer
9789sc1_sess_rate([<table>]) : integer
9790sc2_sess_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +02009791 Returns the average session rate from the currently tracked counters,
9792 measured in amount of sessions over the period configured in the table. A
9793 session is a connection that got past the early "tcp-request connection"
9794 rules. A backend may count more sessions than connections because each
9795 connection could result in many backend sessions if some HTTP keep-alive is
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009796 performed over the connection with the client. See also src_sess_rate.
Willy Tarreaue9656522010-08-17 15:40:09 +02009797
Willy Tarreau0f791d42013-07-23 19:56:43 +02009798sc_tracked(<ctr>,[<table>]) : boolean
9799sc0_tracked([<table>]) : boolean
9800sc1_tracked([<table>]) : boolean
9801sc2_tracked([<table>]) : boolean
Willy Tarreau6f1615f2013-06-03 15:15:22 +02009802 Returns true if the designated session counter is currently being tracked by
9803 the current session. This can be useful when deciding whether or not we want
9804 to set some values in a header passed to the server.
9805
Willy Tarreau0f791d42013-07-23 19:56:43 +02009806sc_trackers(<ctr>,[<table>]) : integer
9807sc0_trackers([<table>]) : integer
9808sc1_trackers([<table>]) : integer
9809sc2_trackers([<table>]) : integer
Willy Tarreau2406db42012-12-09 12:16:43 +01009810 Returns the current amount of concurrent connections tracking the same
9811 tracked counters. This number is automatically incremented when tracking
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009812 begins and decremented when tracking stops. It differs from sc0_conn_cur in
Willy Tarreau2406db42012-12-09 12:16:43 +01009813 that it does not rely on any stored information but on the table's reference
9814 count (the "use" value which is returned by "show table" on the CLI). This
Willy Tarreau74ca5042013-06-11 23:12:07 +02009815 may sometimes be more suited for layer7 tracking. It can be used to tell a
9816 server how many concurrent connections there are from a given address for
9817 example.
Willy Tarreau2406db42012-12-09 12:16:43 +01009818
Willy Tarreau74ca5042013-06-11 23:12:07 +02009819so_id : integer
9820 Returns an integer containing the current listening socket's id. It is useful
9821 in frontends involving many "bind" lines, or to stick all users coming via a
9822 same socket to the same server.
Willy Tarreaud63335a2010-02-26 12:56:52 +01009823
Willy Tarreau74ca5042013-06-11 23:12:07 +02009824src : ip
9825 This is the source IPv4 address of the client of the session. It is of type
9826 IP and works on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are
9827 mapped to their IPv6 equivalent, according to RFC 4291. Note that it is the
9828 TCP-level source address which is used, and not the address of a client
9829 behind a proxy. However if the "accept-proxy" bind directive is used, it can
9830 be the address of a client behind another PROXY-protocol compatible component
9831 for all rule sets except "tcp-request connection" which sees the real address.
Willy Tarreaud63335a2010-02-26 12:56:52 +01009832
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +01009833 Example:
9834 # add an HTTP header in requests with the originating address' country
9835 http-request set-header X-Country %[src,map_ip(geoip.lst)]
9836
Willy Tarreau74ca5042013-06-11 23:12:07 +02009837src_bytes_in_rate([<table>]) : integer
9838 Returns the average bytes rate from the incoming connection's source address
9839 in the current proxy's stick-table or in the designated stick-table, measured
9840 in amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009841 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009842
Willy Tarreau74ca5042013-06-11 23:12:07 +02009843src_bytes_out_rate([<table>]) : integer
9844 Returns the average bytes rate to the incoming connection's source address in
9845 the current proxy's stick-table or in the designated stick-table, measured in
Willy Tarreauc9705a12010-07-27 20:05:50 +02009846 amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009847 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009848
Willy Tarreau74ca5042013-06-11 23:12:07 +02009849src_clr_gpc0([<table>]) : integer
9850 Clears the first General Purpose Counter associated to the incoming
9851 connection's source address in the current proxy's stick-table or in the
9852 designated stick-table, and returns its previous value. If the address is not
9853 found, an entry is created and 0 is returned. This is typically used as a
9854 second ACL in an expression in order to mark a connection when a first ACL
9855 was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +02009856
9857 # block if 5 consecutive requests continue to come faster than 10 sess
9858 # per second, and reset the counter as soon as the traffic slows down.
9859 acl abuse src_http_req_rate gt 10
9860 acl kill src_inc_gpc0 gt 5
Willy Tarreau869948b2013-01-04 14:14:57 +01009861 acl save src_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +02009862 tcp-request connection accept if !abuse save
9863 tcp-request connection reject if abuse kill
9864
Willy Tarreau74ca5042013-06-11 23:12:07 +02009865src_conn_cnt([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +02009866 Returns the cumulated number of connections initiated from the current
Willy Tarreau74ca5042013-06-11 23:12:07 +02009867 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +02009868 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009869 See also sc/sc0/sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009870
Willy Tarreau74ca5042013-06-11 23:12:07 +02009871src_conn_cur([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +02009872 Returns the current amount of concurrent connections initiated from the
Willy Tarreau74ca5042013-06-11 23:12:07 +02009873 current incoming connection's source address in the current proxy's
9874 stick-table or in the designated stick-table. If the address is not found,
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009875 zero is returned. See also sc/sc0/sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009876
Willy Tarreau74ca5042013-06-11 23:12:07 +02009877src_conn_rate([<table>]) : integer
9878 Returns the average connection rate from the incoming connection's source
9879 address in the current proxy's stick-table or in the designated stick-table,
9880 measured in amount of connections over the period configured in the table. If
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009881 the address is not found, zero is returned. See also sc/sc0/sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009882
Willy Tarreau74ca5042013-06-11 23:12:07 +02009883src_get_gpc0([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +02009884 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau74ca5042013-06-11 23:12:07 +02009885 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +02009886 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009887 See also sc/sc0/sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009888
Willy Tarreau74ca5042013-06-11 23:12:07 +02009889src_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +02009890 Returns the average increment rate of the first General Purpose Counter
Willy Tarreau74ca5042013-06-11 23:12:07 +02009891 associated to the incoming connection's source address in the current proxy's
Willy Tarreauba2ffd12013-05-29 15:54:14 +02009892 stick-table or in the designated stick-table. It reports the frequency
9893 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009894 sc/sc0/sc1/sc2_gpc0_rate, src_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
9895 that the "gpc0_rate" counter must be stored in the stick-table for a value to
9896 be returned, as "gpc0" only holds the event count.
Willy Tarreauba2ffd12013-05-29 15:54:14 +02009897
Willy Tarreau74ca5042013-06-11 23:12:07 +02009898src_http_err_cnt([<table>]) : integer
9899 Returns the cumulated number of HTTP errors from the incoming connection's
9900 source address in the current proxy's stick-table or in the designated
Willy Tarreauc9705a12010-07-27 20:05:50 +02009901 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009902 See also sc/sc0/sc1/sc2_http_err_cnt. If the address is not found, zero is
Willy Tarreau74ca5042013-06-11 23:12:07 +02009903 returned.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009904
Willy Tarreau74ca5042013-06-11 23:12:07 +02009905src_http_err_rate([<table>]) : integer
9906 Returns the average rate of HTTP errors from the incoming connection's source
9907 address in the current proxy's stick-table or in the designated stick-table,
9908 measured in amount of errors over the period configured in the table. This
9909 includes the both request errors and 4xx error responses. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009910 not found, zero is returned. See also sc/sc0/sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009911
Willy Tarreau74ca5042013-06-11 23:12:07 +02009912src_http_req_cnt([<table>]) : integer
9913 Returns the cumulated number of HTTP requests from the incoming connection's
9914 source address in the current proxy's stick-table or in the designated stick-
9915 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009916 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009917
Willy Tarreau74ca5042013-06-11 23:12:07 +02009918src_http_req_rate([<table>]) : integer
9919 Returns the average rate of HTTP requests from the incoming connection's
9920 source address in the current proxy's stick-table or in the designated stick-
9921 table, measured in amount of requests over the period configured in the
Willy Tarreauc9705a12010-07-27 20:05:50 +02009922 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009923 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009924
Willy Tarreau74ca5042013-06-11 23:12:07 +02009925src_inc_gpc0([<table>]) : integer
9926 Increments the first General Purpose Counter associated to the incoming
9927 connection's source address in the current proxy's stick-table or in the
9928 designated stick-table, and returns its new value. If the address is not
Willy Tarreaube4a3ef2013-06-17 15:04:07 +02009929 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc0.
Willy Tarreau74ca5042013-06-11 23:12:07 +02009930 This is typically used as a second ACL in an expression in order to mark a
9931 connection when a first ACL was verified :
Willy Tarreauc9705a12010-07-27 20:05:50 +02009932
9933 acl abuse src_http_req_rate gt 10
Willy Tarreau869948b2013-01-04 14:14:57 +01009934 acl kill src_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +02009935 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +02009936
Willy Tarreau74ca5042013-06-11 23:12:07 +02009937src_kbytes_in([<table>]) : integer
9938 Returns the amount of data received from the incoming connection's source
9939 address in the current proxy's stick-table or in the designated stick-table,
9940 measured in kilobytes over the period configured in the table. If the address
9941 is not found, zero is returned. The test is currently performed on 32-bit
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009942 integers, which limits values to 4 terabytes. See also
9943 sc/sc0/sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009944
Willy Tarreau74ca5042013-06-11 23:12:07 +02009945src_kbytes_out([<table>]) : integer
9946 Returns the amount of data sent to the incoming connection's source address
9947 in the current proxy's stick-table or in the designated stick-table, measured
Willy Tarreauc9705a12010-07-27 20:05:50 +02009948 in kilobytes over the period configured in the table. If the address is not
9949 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009950 which limits values to 4 terabytes. See also sc/sc0/sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02009951
Willy Tarreau74ca5042013-06-11 23:12:07 +02009952src_port : integer
9953 Returns an integer value corresponding to the TCP source port of the
9954 connection on the client side, which is the port the client connected from.
9955 Usage of this function is very limited as modern protocols do not care much
9956 about source ports nowadays.
Willy Tarreau079ff0a2009-03-05 21:34:28 +01009957
Willy Tarreau74ca5042013-06-11 23:12:07 +02009958src_sess_cnt([<table>]) : integer
9959 Returns the cumulated number of connections initiated from the incoming
Willy Tarreauc9705a12010-07-27 20:05:50 +02009960 connection's source IPv4 address in the current proxy's stick-table or in the
9961 designated stick-table, that were transformed into sessions, which means that
9962 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009963 is returned. See also sc/sc0/sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009964
Willy Tarreau74ca5042013-06-11 23:12:07 +02009965src_sess_rate([<table>]) : integer
9966 Returns the average session rate from the incoming connection's source
9967 address in the current proxy's stick-table or in the designated stick-table,
9968 measured in amount of sessions over the period configured in the table. A
9969 session is a connection that went past the early "tcp-request" rules. If the
Willy Tarreau4d4149c2013-07-23 19:33:46 +02009970 address is not found, zero is returned. See also sc/sc0/sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009971
Willy Tarreau74ca5042013-06-11 23:12:07 +02009972src_updt_conn_cnt([<table>]) : integer
9973 Creates or updates the entry associated to the incoming connection's source
9974 address in the current proxy's stick-table or in the designated stick-table.
9975 This table must be configured to store the "conn_cnt" data type, otherwise
9976 the match will be ignored. The current count is incremented by one, and the
9977 expiration timer refreshed. The updated count is returned, so this match
9978 can't return zero. This was used to reject service abusers based on their
9979 source address. Note: it is recommended to use the more complete "track-sc*"
9980 actions in "tcp-request" rules instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02009981
9982 Example :
9983 # This frontend limits incoming SSH connections to 3 per 10 second for
9984 # each source address, and rejects excess connections until a 10 second
9985 # silence is observed. At most 20 addresses are tracked.
9986 listen ssh
9987 bind :22
9988 mode tcp
9989 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +02009990 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreau74ca5042013-06-11 23:12:07 +02009991 tcp-request content reject if { src_updt_conn_cnt gt 3 }
Willy Tarreaua975b8f2010-06-05 19:13:27 +02009992 server local 127.0.0.1:22
9993
Willy Tarreau74ca5042013-06-11 23:12:07 +02009994srv_id : integer
9995 Returns an integer containing the server's id when processing the response.
9996 While it's almost only used with ACLs, it may be used for logging or
9997 debugging.
Hervé COMMOWICKdaa824e2011-08-05 12:09:44 +02009998
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01009999
Willy Tarreau74ca5042013-06-11 23:12:07 +0200100007.3.3. Fetching samples at Layer 5
10001----------------------------------
Willy Tarreau0b1cd942010-05-16 22:18:27 +020010002
Willy Tarreau74ca5042013-06-11 23:12:07 +020010003The layer 5 usually describes just the session layer which in haproxy is
10004closest to the session once all the connection handshakes are finished, but
10005when no content is yet made available. The fetch methods described here are
10006usable as low as the "tcp-request content" rule sets unless they require some
10007future information. Those generally include the results of SSL negociations.
Willy Tarreauc735a072011-03-29 00:57:02 +020010008
Willy Tarreau74ca5042013-06-11 23:12:07 +020010009ssl_c_ca_err : integer
10010 When the incoming connection was made over an SSL/TLS transport layer,
10011 returns the ID of the first error detected during verification of the client
10012 certificate at depth > 0, or 0 if no error was encountered during this
10013 verification process. Please refer to your SSL library's documentation to
10014 find the exhaustive list of error codes.
Willy Tarreauc735a072011-03-29 00:57:02 +020010015
Willy Tarreau74ca5042013-06-11 23:12:07 +020010016ssl_c_ca_err_depth : integer
10017 When the incoming connection was made over an SSL/TLS transport layer,
10018 returns the depth in the CA chain of the first error detected during the
10019 verification of the client certificate. If no error is encountered, 0 is
10020 returned.
Willy Tarreau0ba27502007-12-24 16:55:16 +010010021
Willy Tarreau74ca5042013-06-11 23:12:07 +020010022ssl_c_err : integer
10023 When the incoming connection was made over an SSL/TLS transport layer,
10024 returns the ID of the first error detected during verification at depth 0, or
10025 0 if no error was encountered during this verification process. Please refer
10026 to your SSL library's documentation to find the exhaustive list of error
10027 codes.
Willy Tarreau62644772008-07-16 18:36:06 +020010028
Willy Tarreau74ca5042013-06-11 23:12:07 +020010029ssl_c_i_dn([<entry>[,<occ>]]) : string
10030 When the incoming connection was made over an SSL/TLS transport layer,
10031 returns the full distinguished name of the issuer of the certificate
10032 presented by the client when no <entry> is specified, or the value of the
10033 first given entry found from the beginning of the DN. If a positive/negative
10034 occurrence number is specified as the optional second argument, it returns
10035 the value of the nth given entry value from the beginning/end of the DN.
10036 For instance, "ssl_c_i_dn(OU,2)" the second organization unit, and
10037 "ssl_c_i_dn(CN)" retrieves the common name.
Willy Tarreau62644772008-07-16 18:36:06 +020010038
Willy Tarreau74ca5042013-06-11 23:12:07 +020010039 ACL derivatives :
10040 ssl_c_i_dn([<entry>[,<occ>]]) : exact string match
Willy Tarreaub6672b52011-12-12 17:23:41 +010010041
Willy Tarreau74ca5042013-06-11 23:12:07 +020010042ssl_c_key_alg : string
10043 Returns the name of the algorithm used to generate the key of the certificate
10044 presented by the client when the incoming connection was made over an SSL/TLS
10045 transport layer.
Willy Tarreau62644772008-07-16 18:36:06 +020010046
Willy Tarreau74ca5042013-06-11 23:12:07 +020010047 ACL derivatives :
10048 ssl_c_key_alg : exact string match
Willy Tarreau2492d5b2009-07-11 00:06:00 +020010049
Willy Tarreau74ca5042013-06-11 23:12:07 +020010050ssl_c_notafter : string
10051 Returns the end date presented by the client as a formatted string
10052 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
10053 transport layer.
Emeric Brunbede3d02009-06-30 17:54:00 +020010054
Willy Tarreau74ca5042013-06-11 23:12:07 +020010055 ACL derivatives :
10056 ssl_c_notafter : exact string match
Emeric Brunbede3d02009-06-30 17:54:00 +020010057
Willy Tarreau74ca5042013-06-11 23:12:07 +020010058ssl_c_notbefore : string
10059 Returns the start date presented by the client as a formatted string
10060 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
10061 transport layer.
Willy Tarreaub6672b52011-12-12 17:23:41 +010010062
Willy Tarreau74ca5042013-06-11 23:12:07 +020010063 ACL derivatives :
10064 ssl_c_notbefore : exact string match
Willy Tarreaub6672b52011-12-12 17:23:41 +010010065
Willy Tarreau74ca5042013-06-11 23:12:07 +020010066ssl_c_s_dn([<entry>[,<occ>]]) : string
10067 When the incoming connection was made over an SSL/TLS transport layer,
10068 returns the full distinguished name of the subject of the certificate
10069 presented by the client when no <entry> is specified, or the value of the
10070 first given entry found from the beginning of the DN. If a positive/negative
10071 occurrence number is specified as the optional second argument, it returns
10072 the value of the nth given entry value from the beginning/end of the DN.
10073 For instance, "ssl_c_s_dn(OU,2)" the second organization unit, and
10074 "ssl_c_s_dn(CN)" retrieves the common name.
Willy Tarreaub6672b52011-12-12 17:23:41 +010010075
Willy Tarreau74ca5042013-06-11 23:12:07 +020010076 ACL derivatives :
10077 ssl_c_s_dn([<entry>[,<occ>]]) : exact string match
Willy Tarreau7875d092012-09-10 08:20:03 +020010078
Willy Tarreau74ca5042013-06-11 23:12:07 +020010079ssl_c_serial : binary
10080 Returns the serial of the certificate presented by the client when the
10081 incoming connection was made over an SSL/TLS transport layer. When used for
10082 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun2525b6b2012-10-18 15:59:43 +020010083
Willy Tarreau74ca5042013-06-11 23:12:07 +020010084 ACL derivatives :
10085 ssl_c_serial : hex block match
Emeric Brun2525b6b2012-10-18 15:59:43 +020010086
Willy Tarreau74ca5042013-06-11 23:12:07 +020010087ssl_c_sha1 : binary
10088 Returns the SHA-1 fingerprint of the certificate presented by the client when
10089 the incoming connection was made over an SSL/TLS transport layer. This can be
10090 used to stick a client to a server, or to pass this information to a server.
Emeric Brun2525b6b2012-10-18 15:59:43 +020010091
Willy Tarreau74ca5042013-06-11 23:12:07 +020010092ssl_c_sig_alg : string
10093 Returns the name of the algorithm used to sign the certificate presented by
10094 the client when the incoming connection was made over an SSL/TLS transport
10095 layer.
Emeric Brun87855892012-10-17 17:39:35 +020010096
Willy Tarreau74ca5042013-06-11 23:12:07 +020010097 ACL derivatives :
10098 ssl_c_sig_alg : exact string match
10099
10100ssl_c_used : boolean
10101 Returns true if current SSL session uses a client certificate even if current
10102 connection uses SSL session resumption. See also "ssl_fc_has_crt".
Emeric Brun7f56e742012-10-19 18:15:40 +020010103
Willy Tarreau74ca5042013-06-11 23:12:07 +020010104ssl_c_verify : integer
10105 Returns the verify result error ID when the incoming connection was made over
10106 an SSL/TLS transport layer, otherwise zero if no error is encountered. Please
10107 refer to your SSL library's documentation for an exhaustive list of error
10108 codes.
Emeric Brunce5ad802012-10-22 14:11:22 +020010109
Willy Tarreau74ca5042013-06-11 23:12:07 +020010110ssl_c_version : integer
10111 Returns the version of the certificate presented by the client when the
10112 incoming connection was made over an SSL/TLS transport layer.
Emeric Brunce5ad802012-10-22 14:11:22 +020010113
Willy Tarreau74ca5042013-06-11 23:12:07 +020010114ssl_f_i_dn([<entry>[,<occ>]]) : string
10115 When the incoming connection was made over an SSL/TLS transport layer,
10116 returns the full distinguished name of the issuer of the certificate
10117 presented by the frontend when no <entry> is specified, or the value of the
10118 first given entry found from the beginning of the DN. If a positive/negative
Emeric Brun87855892012-10-17 17:39:35 +020010119 occurrence number is specified as the optional second argument, it returns
Willy Tarreau74ca5042013-06-11 23:12:07 +020010120 the value of the nth given entry value from the beginning/end of the DN.
10121 For instance, "ssl_f_i_dn(OU,2)" the second organization unit, and
10122 "ssl_f_i_dn(CN)" retrieves the common name.
Emeric Brun87855892012-10-17 17:39:35 +020010123
Willy Tarreau74ca5042013-06-11 23:12:07 +020010124 ACL derivatives :
10125 ssl_f_i_dn([<entry>[,<occ>]]) : exact string match
Willy Tarreau8d598402012-10-22 17:58:39 +020010126
Willy Tarreau74ca5042013-06-11 23:12:07 +020010127ssl_f_key_alg : string
10128 Returns the name of the algorithm used to generate the key of the certificate
10129 presented by the frontend when the incoming connection was made over an
10130 SSL/TLS transport layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020010131
Willy Tarreau74ca5042013-06-11 23:12:07 +020010132 ACL derivatives :
10133 ssl_f_key_alg : exact string match
Emeric Brun9143d372012-12-20 15:44:16 +010010134
Willy Tarreau74ca5042013-06-11 23:12:07 +020010135ssl_f_notafter : string
10136 Returns the end date presented by the frontend as a formatted string
10137 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
10138 transport layer.
Emeric Brun2525b6b2012-10-18 15:59:43 +020010139
Willy Tarreau74ca5042013-06-11 23:12:07 +020010140 ACL derivatives :
10141 ssl_f_notafter : exact string match
Emeric Bruna7359fd2012-10-17 15:03:11 +020010142
Willy Tarreau74ca5042013-06-11 23:12:07 +020010143ssl_f_notbefore : string
10144 Returns the start date presented by the frontend as a formatted string
10145 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
10146 transport layer.
Emeric Brun87855892012-10-17 17:39:35 +020010147
Willy Tarreau74ca5042013-06-11 23:12:07 +020010148 ACL derivatives :
10149 ssl_f_notbefore : exact string match
Emeric Brun7f56e742012-10-19 18:15:40 +020010150
Willy Tarreau74ca5042013-06-11 23:12:07 +020010151ssl_f_s_dn([<entry>[,<occ>]]) : string
10152 When the incoming connection was made over an SSL/TLS transport layer,
10153 returns the full distinguished name of the subject of the certificate
10154 presented by the frontend when no <entry> is specified, or the value of the
10155 first given entry found from the beginning of the DN. If a positive/negative
10156 occurrence number is specified as the optional second argument, it returns
10157 the value of the nth given entry value from the beginning/end of the DN.
10158 For instance, "ssl_f_s_dn(OU,2)" the second organization unit, and
10159 "ssl_f_s_dn(CN)" retrieves the common name.
Emeric Brunce5ad802012-10-22 14:11:22 +020010160
Willy Tarreau74ca5042013-06-11 23:12:07 +020010161 ACL derivatives :
10162 ssl_f_s_dn([<entry>[,<occ>]]) : exact string match
Emeric Brunce5ad802012-10-22 14:11:22 +020010163
Willy Tarreau74ca5042013-06-11 23:12:07 +020010164ssl_f_serial : binary
10165 Returns the serial of the certificate presented by the frontend when the
10166 incoming connection was made over an SSL/TLS transport layer. When used for
10167 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun87855892012-10-17 17:39:35 +020010168
Willy Tarreau74ca5042013-06-11 23:12:07 +020010169 ACL derivatives :
10170 ssl_f_serial : hex block match
Willy Tarreau8d598402012-10-22 17:58:39 +020010171
Willy Tarreau74ca5042013-06-11 23:12:07 +020010172ssl_f_sig_alg : string
10173 Returns the name of the algorithm used to sign the certificate presented by
10174 the frontend when the incoming connection was made over an SSL/TLS transport
10175 layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020010176
Willy Tarreau74ca5042013-06-11 23:12:07 +020010177 ACL derivatives :
10178 ssl_f_sig_alg : exact string match
Emeric Bruna7359fd2012-10-17 15:03:11 +020010179
Willy Tarreau74ca5042013-06-11 23:12:07 +020010180ssl_f_version : integer
10181 Returns the version of the certificate presented by the frontend when the
10182 incoming connection was made over an SSL/TLS transport layer.
10183
10184ssl_fc : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020010185 Returns true when the front connection was made via an SSL/TLS transport
10186 layer and is locally deciphered. This means it has matched a socket declared
10187 with a "bind" line having the "ssl" option.
10188
Willy Tarreau74ca5042013-06-11 23:12:07 +020010189 Example :
10190 # This passes "X-Proto: https" to servers when client connects over SSL
10191 listen http-https
10192 bind :80
10193 bind :443 ssl crt /etc/haproxy.pem
10194 http-request add-header X-Proto https if { ssl_fc }
10195
10196ssl_fc_alg_keysize : integer
10197 Returns the symmetric cipher key size supported in bits when the incoming
10198 connection was made over an SSL/TLS transport layer.
10199
10200ssl_fc_alpn : string
10201 This extracts the Application Layer Protocol Negociation field from an
10202 incoming connection made via a TLS transport layer and locally deciphered by
10203 haproxy. The result is a string containing the protocol name advertised by
10204 the client. The SSL library must have been built with support for TLS
10205 extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
10206 not advertised unless the "alpn" keyword on the "bind" line specifies a
10207 protocol list. Also, nothing forces the client to pick a protocol from this
10208 list, any other one may be requested. The TLS ALPN extension is meant to
10209 replace the TLS NPN extension. See also "ssl_fc_npn".
10210
10211 ACL derivatives :
10212 ssl_fc_alpn : exact string match
Emeric Brun589fcad2012-10-16 14:13:26 +020010213
Willy Tarreau74ca5042013-06-11 23:12:07 +020010214ssl_fc_cipher : string
10215 Returns the name of the used cipher when the incoming connection was made
10216 over an SSL/TLS transport layer.
Willy Tarreauab861d32013-04-02 02:30:41 +020010217
Willy Tarreau74ca5042013-06-11 23:12:07 +020010218 ACL derivatives :
10219 ssl_fc_cipher : exact string match
Emeric Brun589fcad2012-10-16 14:13:26 +020010220
Willy Tarreau74ca5042013-06-11 23:12:07 +020010221ssl_fc_has_crt : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020010222 Returns true if a client certificate is present in an incoming connection over
10223 SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
Emeric Brun9143d372012-12-20 15:44:16 +010010224 Note: on SSL session resumption with Session ID or TLS ticket, client
10225 certificate is not present in the current connection but may be retrieved
10226 from the cache or the ticket. So prefer "ssl_c_used" if you want to check if
10227 current SSL session uses a client certificate.
Emeric Brun2525b6b2012-10-18 15:59:43 +020010228
Willy Tarreau74ca5042013-06-11 23:12:07 +020010229ssl_fc_has_sni : boolean
10230 This checks for the presence of a Server Name Indication TLS extension (SNI)
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020010231 in an incoming connection was made over an SSL/TLS transport layer. Returns
10232 true when the incoming connection presents a TLS SNI field. This requires
10233 that the SSL library is build with support for TLS extensions enabled (check
10234 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +020010235
Willy Tarreau74ca5042013-06-11 23:12:07 +020010236ssl_fc_npn : string
10237 This extracts the Next Protocol Negociation field from an incoming connection
10238 made via a TLS transport layer and locally deciphered by haproxy. The result
10239 is a string containing the protocol name advertised by the client. The SSL
10240 library must have been built with support for TLS extensions enabled (check
10241 haproxy -vv). Note that the TLS NPN extension is not advertised unless the
10242 "npn" keyword on the "bind" line specifies a protocol list. Also, nothing
10243 forces the client to pick a protocol from this list, any other one may be
10244 requested. Please note that the TLS NPN extension was replaced with ALPN.
Willy Tarreaua33c6542012-10-15 13:19:06 +020010245
Willy Tarreau74ca5042013-06-11 23:12:07 +020010246 ACL derivatives :
10247 ssl_fc_npn : exact string match
Emeric Brun589fcad2012-10-16 14:13:26 +020010248
Willy Tarreau74ca5042013-06-11 23:12:07 +020010249ssl_fc_protocol : string
10250 Returns the name of the used protocol when the incoming connection was made
10251 over an SSL/TLS transport layer.
Willy Tarreau7875d092012-09-10 08:20:03 +020010252
Willy Tarreau74ca5042013-06-11 23:12:07 +020010253 ACL derivatives :
10254 ssl_fc_protocol : exact string match
10255
10256ssl_fc_session_id : binary
10257 Returns the SSL ID of the front connection when the incoming connection was
10258 made over an SSL/TLS transport layer. It is useful to stick a given client to
10259 a server. It is important to note that some browsers refresh their session ID
10260 every few minutes.
Willy Tarreau7875d092012-09-10 08:20:03 +020010261
Willy Tarreau74ca5042013-06-11 23:12:07 +020010262ssl_fc_sni : string
10263 This extracts the Server Name Indication TLS extension (SNI) field from an
10264 incoming connection made via an SSL/TLS transport layer and locally
10265 deciphered by haproxy. The result (when present) typically is a string
10266 matching the HTTPS host name (253 chars or less). The SSL library must have
10267 been built with support for TLS extensions enabled (check haproxy -vv).
10268
10269 This fetch is different from "req_ssl_sni" above in that it applies to the
10270 connection being deciphered by haproxy and not to SSL contents being blindly
10271 forwarded. See also "ssl_fc_sni_end" and "ssl_fc_sni_reg" below. This
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +020010272 requires that the SSL library is build with support for TLS extensions
10273 enabled (check haproxy -vv).
Willy Tarreau62644772008-07-16 18:36:06 +020010274
Willy Tarreau74ca5042013-06-11 23:12:07 +020010275 ACL derivatives :
10276 ssl_fc_sni : exact string match
10277 ssl_fc_sni_end : suffix match
10278 ssl_fc_sni_reg : regex match
Emeric Brun589fcad2012-10-16 14:13:26 +020010279
Willy Tarreau74ca5042013-06-11 23:12:07 +020010280ssl_fc_use_keysize : integer
10281 Returns the symmetric cipher key size used in bits when the incoming
10282 connection was made over an SSL/TLS transport layer.
Willy Tarreaub6fb4202008-07-20 11:18:28 +020010283
Willy Tarreaub6fb4202008-07-20 11:18:28 +020010284
Willy Tarreau74ca5042013-06-11 23:12:07 +0200102857.3.4. Fetching samples from buffer contents (Layer 6)
10286------------------------------------------------------
Willy Tarreaub6fb4202008-07-20 11:18:28 +020010287
Willy Tarreau74ca5042013-06-11 23:12:07 +020010288Fetching samples from buffer contents is a bit different from the previous
10289sample fetches above because the sampled data are ephemeral. These data can
10290only be used when they're available and will be lost when they're forwarded.
10291For this reason, samples fetched from buffer contents during a request cannot
10292be used in a response for example. Even while the data are being fetched, they
10293can change. Sometimes it is necessary to set some delays or combine multiple
10294sample fetch methods to ensure that the expected data are complete and usable,
10295for example through TCP request content inspection. Please see the "tcp-request
10296content" keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +020010297
Willy Tarreau74ca5042013-06-11 23:12:07 +020010298payload(<offset>,<length>) : binary (deprecated)
10299 This is an alias for "req.payload" when used in the context of a request (eg:
10300 "stick on", "stick match"), and for "res.payload" when used in the context of
10301 a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010010302
Willy Tarreau74ca5042013-06-11 23:12:07 +020010303payload_lv(<offset1>,<length>[,<offset2>]) : binary (deprecated)
10304 This is an alias for "req.payload_lv" when used in the context of a request
10305 (eg: "stick on", "stick match"), and for "res.payload_lv" when used in the
10306 context of a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010010307
Willy Tarreau74ca5042013-06-11 23:12:07 +020010308req.len : integer
10309req_len : integer (deprecated)
10310 Returns an integer value corresponding to the number of bytes present in the
10311 request buffer. This is mostly used in ACL. It is important to understand
10312 that this test does not return false as long as the buffer is changing. This
10313 means that a check with equality to zero will almost always immediately match
10314 at the beginning of the session, while a test for more data will wait for
10315 that data to come in and return false only when haproxy is certain that no
10316 more data will come in. This test was designed to be used with TCP request
10317 content inspection.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020010318
Willy Tarreau74ca5042013-06-11 23:12:07 +020010319req.payload(<offset>,<length>) : binary
10320 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020010321 in the request buffer. As a special case, if the <length> argument is zero,
10322 the the whole buffer from <offset> to the end is extracted. This can be used
10323 with ACLs in order to check for the presence of some content in a buffer at
10324 any location.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020010325
Willy Tarreau74ca5042013-06-11 23:12:07 +020010326 ACL alternatives :
10327 payload(<offset>,<length>) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020010328
Willy Tarreau74ca5042013-06-11 23:12:07 +020010329req.payload_lv(<offset1>,<length>[,<offset2>]) : binary
10330 This extracts a binary block whose size is specified at <offset1> for <length>
10331 bytes, and which starts at <offset2> if specified or just after the length in
10332 the request buffer. The <offset2> parameter also supports relative offsets if
10333 prepended with a '+' or '-' sign.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020010334
Willy Tarreau74ca5042013-06-11 23:12:07 +020010335 ACL alternatives :
10336 payload_lv(<offset1>,<length>[,<offset2>]) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020010337
Willy Tarreau74ca5042013-06-11 23:12:07 +020010338 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020010339
Willy Tarreau74ca5042013-06-11 23:12:07 +020010340req.proto_http : boolean
10341req_proto_http : boolean (deprecated)
10342 Returns true when data in the request buffer look like HTTP and correctly
10343 parses as such. It is the same parser as the common HTTP request parser which
10344 is used so there should be no surprises. The test does not match until the
10345 request is complete, failed or timed out. This test may be used to report the
10346 protocol in TCP logs, but the biggest use is to block TCP request analysis
10347 until a complete HTTP request is present in the buffer, for example to track
10348 a header.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020010349
Willy Tarreau74ca5042013-06-11 23:12:07 +020010350 Example:
10351 # track request counts per "base" (concatenation of Host+URL)
10352 tcp-request inspect-delay 10s
10353 tcp-request content reject if !HTTP
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020010354 tcp-request content track-sc0 base table req-rate
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020010355
Willy Tarreau74ca5042013-06-11 23:12:07 +020010356req.rdp_cookie([<name>]) : string
10357rdp_cookie([<name>]) : string (deprecated)
10358 When the request buffer looks like the RDP protocol, extracts the RDP cookie
10359 <name>, or any cookie if unspecified. The parser only checks for the first
10360 cookie, as illustrated in the RDP protocol specification. The cookie name is
10361 case insensitive. Generally the "MSTS" cookie name will be used, as it can
10362 contain the user name of the client connecting to the server if properly
10363 configured on the client. The "MSTSHASH" cookie is often used as well for
10364 session stickiness to servers.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020010365
Willy Tarreau74ca5042013-06-11 23:12:07 +020010366 This differs from "balance rdp-cookie" in that any balancing algorithm may be
10367 used and thus the distribution of clients to backend servers is not linked to
10368 a hash of the RDP cookie. It is envisaged that using a balancing algorithm
10369 such as "balance roundrobin" or "balance leastconn" will lead to a more even
10370 distribution of clients to backend servers than the hash used by "balance
10371 rdp-cookie".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020010372
Willy Tarreau74ca5042013-06-11 23:12:07 +020010373 ACL derivatives :
10374 req_rdp_cookie([<name>]) : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020010375
Willy Tarreau74ca5042013-06-11 23:12:07 +020010376 Example :
10377 listen tse-farm
10378 bind 0.0.0.0:3389
10379 # wait up to 5s for an RDP cookie in the request
10380 tcp-request inspect-delay 5s
10381 tcp-request content accept if RDP_COOKIE
10382 # apply RDP cookie persistence
10383 persist rdp-cookie
10384 # Persist based on the mstshash cookie
10385 # This is only useful makes sense if
10386 # balance rdp-cookie is not used
10387 stick-table type string size 204800
10388 stick on req.rdp_cookie(mstshash)
10389 server srv1 1.1.1.1:3389
10390 server srv1 1.1.1.2:3389
Willy Tarreau04aa6a92012-04-06 18:57:55 +020010391
Willy Tarreau74ca5042013-06-11 23:12:07 +020010392 See also : "balance rdp-cookie", "persist rdp-cookie", "tcp-request" and the
10393 "req_rdp_cookie" ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020010394
Willy Tarreau74ca5042013-06-11 23:12:07 +020010395req.rdp_cookie_cnt([name]) : integer
10396rdp_cookie_cnt([name]) : integer (deprecated)
10397 Tries to parse the request buffer as RDP protocol, then returns an integer
10398 corresponding to the number of RDP cookies found. If an optional cookie name
10399 is passed, only cookies matching this name are considered. This is mostly
10400 used in ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020010401
Willy Tarreau74ca5042013-06-11 23:12:07 +020010402 ACL derivatives :
10403 req_rdp_cookie_cnt([<name>]) : integer match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020010404
Willy Tarreau74ca5042013-06-11 23:12:07 +020010405req.ssl_hello_type : integer
10406req_ssl_hello_type : integer (deprecated)
10407 Returns an integer value containing the type of the SSL hello message found
10408 in the request buffer if the buffer contains data that parse as a complete
10409 SSL (v3 or superior) client hello message. Note that this only applies to raw
10410 contents found in the request buffer and not to contents deciphered via an
10411 SSL data layer, so this will not work with "bind" lines having the "ssl"
10412 option. This is mostly used in ACL to detect presence of an SSL hello message
10413 that is supposed to contain an SSL session ID usable for stickiness.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020010414
Willy Tarreau74ca5042013-06-11 23:12:07 +020010415req.ssl_sni : string
10416req_ssl_sni : string (deprecated)
10417 Returns a string containing the value of the Server Name TLS extension sent
10418 by a client in a TLS stream passing through the request buffer if the buffer
10419 contains data that parse as a complete SSL (v3 or superior) client hello
10420 message. Note that this only applies to raw contents found in the request
10421 buffer and not to contents deciphered via an SSL data layer, so this will not
10422 work with "bind" lines having the "ssl" option. SNI normally contains the
10423 name of the host the client tries to connect to (for recent browsers). SNI is
10424 useful for allowing or denying access to certain hosts when SSL/TLS is used
10425 by the client. This test was designed to be used with TCP request content
10426 inspection. If content switching is needed, it is recommended to first wait
10427 for a complete client hello (type 1), like in the example below. See also
10428 "ssl_fc_sni".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020010429
Willy Tarreau74ca5042013-06-11 23:12:07 +020010430 ACL derivatives :
10431 req_ssl_sni : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020010432
Willy Tarreau74ca5042013-06-11 23:12:07 +020010433 Examples :
10434 # Wait for a client hello for at most 5 seconds
10435 tcp-request inspect-delay 5s
10436 tcp-request content accept if { req_ssl_hello_type 1 }
10437 use_backend bk_allow if { req_ssl_sni -f allowed_sites }
10438 default_backend bk_sorry_page
Willy Tarreau04aa6a92012-04-06 18:57:55 +020010439
Willy Tarreau74ca5042013-06-11 23:12:07 +020010440res.ssl_hello_type : integer
10441rep_ssl_hello_type : integer (deprecated)
10442 Returns an integer value containing the type of the SSL hello message found
10443 in the response buffer if the buffer contains data that parses as a complete
10444 SSL (v3 or superior) hello message. Note that this only applies to raw
10445 contents found in the response buffer and not to contents deciphered via an
10446 SSL data layer, so this will not work with "server" lines having the "ssl"
10447 option. This is mostly used in ACL to detect presence of an SSL hello message
10448 that is supposed to contain an SSL session ID usable for stickiness.
Willy Tarreau51539362012-05-08 12:46:28 +020010449
Willy Tarreau74ca5042013-06-11 23:12:07 +020010450req.ssl_ver : integer
10451req_ssl_ver : integer (deprecated)
10452 Returns an integer value containing the version of the SSL/TLS protocol of a
10453 stream present in the request buffer. Both SSLv2 hello messages and SSLv3
10454 messages are supported. TLSv1 is announced as SSL version 3.1. The value is
10455 composed of the major version multiplied by 65536, added to the minor
10456 version. Note that this only applies to raw contents found in the request
10457 buffer and not to contents deciphered via an SSL data layer, so this will not
10458 work with "bind" lines having the "ssl" option. The ACL version of the test
10459 matches against a decimal notation in the form MAJOR.MINOR (eg: 3.1). This
10460 fetch is mostly used in ACL.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010461
Willy Tarreau74ca5042013-06-11 23:12:07 +020010462 ACL derivatives :
10463 req_ssl_ver : decimal match
Willy Tarreaud63335a2010-02-26 12:56:52 +010010464
Willy Tarreau47e8eba2013-09-11 23:28:46 +020010465res.len : integer
10466 Returns an integer value corresponding to the number of bytes present in the
10467 response buffer. This is mostly used in ACL. It is important to understand
10468 that this test does not return false as long as the buffer is changing. This
10469 means that a check with equality to zero will almost always immediately match
10470 at the beginning of the session, while a test for more data will wait for
10471 that data to come in and return false only when haproxy is certain that no
10472 more data will come in. This test was designed to be used with TCP response
10473 content inspection.
10474
Willy Tarreau74ca5042013-06-11 23:12:07 +020010475res.payload(<offset>,<length>) : binary
10476 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020010477 in the response buffer. As a special case, if the <length> argument is zero,
10478 the the whole buffer from <offset> to the end is extracted. This can be used
10479 with ACLs in order to check for the presence of some content in a buffer at
10480 any location.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010481
Willy Tarreau74ca5042013-06-11 23:12:07 +020010482res.payload_lv(<offset1>,<length>[,<offset2>]) : binary
10483 This extracts a binary block whose size is specified at <offset1> for <length>
10484 bytes, and which starts at <offset2> if specified or just after the length in
10485 the response buffer. The <offset2> parameter also supports relative offsets
10486 if prepended with a '+' or '-' sign.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010487
Willy Tarreau74ca5042013-06-11 23:12:07 +020010488 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010489
Willy Tarreau74ca5042013-06-11 23:12:07 +020010490wait_end : boolean
10491 This fetch either returns true when the inspection period is over, or does
10492 not fetch. It is only used in ACLs, in conjunction with content analysis to
10493 avoid returning a wrong verdict early. It may also be used to delay some
10494 actions, such as a delayed reject for some special addresses. Since it either
10495 stops the rules evaluation or immediately returns true, it is recommended to
10496 use this acl as the last one in a rule. Please note that the default ACL
10497 "WAIT_END" is always usable without prior declaration. This test was designed
10498 to be used with TCP request content inspection.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010499
Willy Tarreau74ca5042013-06-11 23:12:07 +020010500 Examples :
10501 # delay every incoming request by 2 seconds
10502 tcp-request inspect-delay 2s
10503 tcp-request content accept if WAIT_END
Willy Tarreaud63335a2010-02-26 12:56:52 +010010504
Willy Tarreau74ca5042013-06-11 23:12:07 +020010505 # don't immediately tell bad guys they are rejected
10506 tcp-request inspect-delay 10s
10507 acl goodguys src 10.0.0.0/24
10508 acl badguys src 10.0.1.0/24
10509 tcp-request content accept if goodguys
10510 tcp-request content reject if badguys WAIT_END
10511 tcp-request content reject
10512
10513
105147.3.5. Fetching HTTP samples (Layer 7)
10515--------------------------------------
10516
10517It is possible to fetch samples from HTTP contents, requests and responses.
10518This application layer is also called layer 7. It is only possible to fetch the
10519data in this section when a full HTTP request or response has been parsed from
10520its respective request or response buffer. This is always the case with all
10521HTTP specific rules and for sections running with "mode http". When using TCP
10522content inspection, it may be necessary to support an inspection delay in order
10523to let the request or response come in first. These fetches may require a bit
10524more CPU resources than the layer 4 ones, but not much since the request and
10525response are indexed.
10526
10527base : string
10528 This returns the concatenation of the first Host header and the path part of
10529 the request, which starts at the first slash and ends before the question
10530 mark. It can be useful in virtual hosted environments to detect URL abuses as
10531 well as to improve shared caches efficiency. Using this with a limited size
10532 stick table also allows one to collect statistics about most commonly
10533 requested objects by host/path. With ACLs it can allow simple content
10534 switching rules involving the host and the path at the same time, such as
10535 "www.example.com/favicon.ico". See also "path" and "uri".
10536
10537 ACL derivatives :
10538 base : exact string match
10539 base_beg : prefix match
10540 base_dir : subdir match
10541 base_dom : domain match
10542 base_end : suffix match
10543 base_len : length match
10544 base_reg : regex match
10545 base_sub : substring match
10546
10547base32 : integer
10548 This returns a 32-bit hash of the value returned by the "base" fetch method
10549 above. This is useful to track per-URL activity on high traffic sites without
10550 having to store all URLs. Instead a shorter hash is stored, saving a lot of
10551 memory. The output type is an unsigned integer.
10552
10553base32+src : binary
10554 This returns the concatenation of the base32 fetch above and the src fetch
10555 below. The resulting type is of type binary, with a size of 8 or 20 bytes
10556 depending on the source address family. This can be used to track per-IP,
10557 per-URL counters.
10558
William Lallemand65ad6e12014-01-31 15:08:02 +010010559capture.req.hdr(<idx>) : string
10560 This extracts the content of the header captured by the "capture request
10561 header", idx is the position of the capture keyword in the configuration.
10562 The first entry is an index of 0. See also: "capture request header".
10563
10564capture.req.method : string
10565 This extracts the METHOD of an HTTP request. It can be used in both request
10566 and response. Unlike "method", it can be used in both request and response
10567 because it's allocated.
10568
10569capture.req.uri : string
10570 This extracts the request's URI, which starts at the first slash and ends
10571 before the first space in the request (without the host part). Unlike "path"
10572 and "url", it can be used in both request and response because it's
10573 allocated.
10574
10575capture.res.hdr(<idx>) : string
10576 This extracts the content of the header captured by the "capture response
10577 header", idx is the position of the capture keyword in the configuration.
10578 The first entry is an index of 0.
10579 See also: "capture response header"
10580
Willy Tarreau74ca5042013-06-11 23:12:07 +020010581req.cook([<name>]) : string
10582cook([<name>]) : string (deprecated)
10583 This extracts the last occurrence of the cookie name <name> on a "Cookie"
10584 header line from the request, and returns its value as string. If no name is
10585 specified, the first cookie value is returned. When used with ACLs, all
10586 matching cookies are evaluated. Spaces around the name and the value are
10587 ignored as requested by the Cookie header specification (RFC6265). The cookie
10588 name is case-sensitive. Empty cookies are valid, so an empty cookie may very
10589 well return an empty value if it is present. Use the "found" match to detect
10590 presence. Use the res.cook() variant for response cookies sent by the server.
10591
10592 ACL derivatives :
10593 cook([<name>]) : exact string match
10594 cook_beg([<name>]) : prefix match
10595 cook_dir([<name>]) : subdir match
10596 cook_dom([<name>]) : domain match
10597 cook_end([<name>]) : suffix match
10598 cook_len([<name>]) : length match
10599 cook_reg([<name>]) : regex match
10600 cook_sub([<name>]) : substring match
Willy Tarreaud63335a2010-02-26 12:56:52 +010010601
Willy Tarreau74ca5042013-06-11 23:12:07 +020010602req.cook_cnt([<name>]) : integer
10603cook_cnt([<name>]) : integer (deprecated)
10604 Returns an integer value representing the number of occurrences of the cookie
10605 <name> in the request, or all cookies if <name> is not specified.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010606
Willy Tarreau74ca5042013-06-11 23:12:07 +020010607req.cook_val([<name>]) : integer
10608cook_val([<name>]) : integer (deprecated)
10609 This extracts the last occurrence of the cookie name <name> on a "Cookie"
10610 header line from the request, and converts its value to an integer which is
10611 returned. If no name is specified, the first cookie value is returned. When
10612 used in ACLs, all matching names are iterated over until a value matches.
Willy Tarreau0e698542011-09-16 08:32:32 +020010613
Willy Tarreau74ca5042013-06-11 23:12:07 +020010614cookie([<name>]) : string (deprecated)
10615 This extracts the last occurrence of the cookie name <name> on a "Cookie"
10616 header line from the request, or a "Set-Cookie" header from the response, and
10617 returns its value as a string. A typical use is to get multiple clients
10618 sharing a same profile use the same server. This can be similar to what
10619 "appsession" does with the "request-learn" statement, but with support for
10620 multi-peer synchronization and state keeping across restarts. If no name is
10621 specified, the first cookie value is returned. This fetch should not be used
10622 anymore and should be replaced by req.cook() or res.cook() instead as it
10623 ambiguously uses the direction based on the context where it is used.
10624 See also : "appsession".
Willy Tarreaud63335a2010-02-26 12:56:52 +010010625
Willy Tarreau74ca5042013-06-11 23:12:07 +020010626hdr([<name>[,<occ>]]) : string
10627 This is equivalent to req.hdr() when used on requests, and to res.hdr() when
10628 used on responses. Please refer to these respective fetches for more details.
10629 In case of doubt about the fetch direction, please use the explicit ones.
10630 Note that contrary to the hdr() sample fetch method, the hdr_* ACL keywords
10631 unambiguouslly apply to the request headers.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010632
Willy Tarreau74ca5042013-06-11 23:12:07 +020010633req.fhdr(<name>[,<occ>]) : string
10634 This extracts the last occurrence of header <name> in an HTTP request. When
10635 used from an ACL, all occurrences are iterated over until a match is found.
10636 Optionally, a specific occurrence might be specified as a position number.
10637 Positive values indicate a position from the first occurrence, with 1 being
10638 the first one. Negative values indicate positions relative to the last one,
10639 with -1 being the last one. It differs from req.hdr() in that any commas
10640 present in the value are returned and are not used as delimiters. This is
10641 sometimes useful with headers such as User-Agent.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010642
Willy Tarreau74ca5042013-06-11 23:12:07 +020010643req.fhdr_cnt([<name>]) : integer
10644 Returns an integer value representing the number of occurrences of request
10645 header field name <name>, or the total number of header fields if <name> is
10646 not specified. Contrary to its req.hdr_cnt() cousin, this function returns
10647 the number of full line headers and does not stop on commas.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010648
Willy Tarreau74ca5042013-06-11 23:12:07 +020010649req.hdr([<name>[,<occ>]]) : string
10650 This extracts the last occurrence of header <name> in an HTTP request. When
10651 used from an ACL, all occurrences are iterated over until a match is found.
10652 Optionally, a specific occurrence might be specified as a position number.
10653 Positive values indicate a position from the first occurrence, with 1 being
10654 the first one. Negative values indicate positions relative to the last one,
10655 with -1 being the last one. A typical use is with the X-Forwarded-For header
10656 once converted to IP, associated with an IP stick-table. The function
10657 considers any comma as a delimiter for distinct values. If full-line headers
10658 are desired instead, use req.fhdr(). Please carefully check RFC2616 to know
10659 how certain headers are supposed to be parsed. Also, some of them are case
10660 insensitive (eg: Connection).
Willy Tarreaud63335a2010-02-26 12:56:52 +010010661
Willy Tarreau74ca5042013-06-11 23:12:07 +020010662 ACL derivatives :
10663 hdr([<name>[,<occ>]]) : exact string match
10664 hdr_beg([<name>[,<occ>]]) : prefix match
10665 hdr_dir([<name>[,<occ>]]) : subdir match
10666 hdr_dom([<name>[,<occ>]]) : domain match
10667 hdr_end([<name>[,<occ>]]) : suffix match
10668 hdr_len([<name>[,<occ>]]) : length match
10669 hdr_reg([<name>[,<occ>]]) : regex match
10670 hdr_sub([<name>[,<occ>]]) : substring match
10671
10672req.hdr_cnt([<name>]) : integer
10673hdr_cnt([<header>]) : integer (deprecated)
10674 Returns an integer value representing the number of occurrences of request
10675 header field name <name>, or the total number of header field values if
10676 <name> is not specified. It is important to remember that one header line may
10677 count as several headers if it has several values. The function considers any
10678 comma as a delimiter for distinct values. If full-line headers are desired
10679 instead, req.fhdr_cnt() should be used instead. With ACLs, it can be used to
10680 detect presence, absence or abuse of a specific header, as well as to block
10681 request smuggling attacks by rejecting requests which contain more than one
10682 of certain headers. See "req.hdr" for more information on header matching.
10683
10684req.hdr_ip([<name>[,<occ>]]) : ip
10685hdr_ip([<name>[,<occ>]]) : ip (deprecated)
10686 This extracts the last occurrence of header <name> in an HTTP request,
10687 converts it to an IPv4 or IPv6 address and returns this address. When used
10688 with ACLs, all occurrences are checked, and if <name> is omitted, every value
10689 of every header is checked. Optionally, a specific occurrence might be
10690 specified as a position number. Positive values indicate a position from the
10691 first occurrence, with 1 being the first one. Negative values indicate
10692 positions relative to the last one, with -1 being the last one. A typical use
10693 is with the X-Forwarded-For and X-Client-IP headers.
10694
10695req.hdr_val([<name>[,<occ>]]) : integer
10696hdr_val([<name>[,<occ>]]) : integer (deprecated)
10697 This extracts the last occurrence of header <name> in an HTTP request, and
10698 converts it to an integer value. When used with ACLs, all occurrences are
10699 checked, and if <name> is omitted, every value of every header is checked.
10700 Optionally, a specific occurrence might be specified as a position number.
10701 Positive values indicate a position from the first occurrence, with 1 being
10702 the first one. Negative values indicate positions relative to the last one,
10703 with -1 being the last one. A typical use is with the X-Forwarded-For header.
10704
10705http_auth(<userlist>) : boolean
10706 Returns a boolean indicating whether the authentication data received from
10707 the client match a username & password stored in the specified userlist. This
10708 fetch function is not really useful outside of ACLs. Currently only http
10709 basic auth is supported.
10710
10711http_auth_group(<userlist>) : group
10712 Returns a boolean indicating whether the authentication data received from
10713 the client match a username & password stored in the specified userlist, and
10714 whether that username belongs to one of the groups supplied in ACL patterns.
10715 This fetch function is not really useful outside of ACLs. Currently only http
10716 basic auth is supported.
10717
10718 ACL derivatives :
10719 http_auth_group(<userlist>) : user group match
10720
10721http_first_req : boolean
Willy Tarreau7f18e522010-10-22 20:04:13 +020010722 Returns true when the request being processed is the first one of the
10723 connection. This can be used to add or remove headers that may be missing
Willy Tarreau74ca5042013-06-11 23:12:07 +020010724 from some requests when a request is not the first one, or to help grouping
10725 requests in the logs.
Willy Tarreau7f18e522010-10-22 20:04:13 +020010726
Willy Tarreau74ca5042013-06-11 23:12:07 +020010727method : integer + string
10728 Returns an integer value corresponding to the method in the HTTP request. For
10729 example, "GET" equals 1 (check sources to establish the matching). Value 9
10730 means "other method" and may be converted to a string extracted from the
10731 stream. This should not be used directly as a sample, this is only meant to
10732 be used from ACLs, which transparently convert methods from patterns to these
10733 integer + string values. Some predefined ACL already check for most common
10734 methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020010735
Willy Tarreau74ca5042013-06-11 23:12:07 +020010736 ACL derivatives :
10737 method : case insensitive method match
Willy Tarreau6a06a402007-07-15 20:15:28 +020010738
Willy Tarreau74ca5042013-06-11 23:12:07 +020010739 Example :
10740 # only accept GET and HEAD requests
10741 acl valid_method method GET HEAD
10742 http-request deny if ! valid_method
Willy Tarreau6a06a402007-07-15 20:15:28 +020010743
Willy Tarreau74ca5042013-06-11 23:12:07 +020010744path : string
10745 This extracts the request's URL path, which starts at the first slash and
10746 ends before the question mark (without the host part). A typical use is with
10747 prefetch-capable caches, and with portals which need to aggregate multiple
10748 information from databases and keep them in caches. Note that with outgoing
10749 caches, it would be wiser to use "url" instead. With ACLs, it's typically
10750 used to match exact file names (eg: "/login.php"), or directory parts using
10751 the derivative forms. See also the "url" and "base" fetch methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020010752
Willy Tarreau74ca5042013-06-11 23:12:07 +020010753 ACL derivatives :
10754 path : exact string match
10755 path_beg : prefix match
10756 path_dir : subdir match
10757 path_dom : domain match
10758 path_end : suffix match
10759 path_len : length match
10760 path_reg : regex match
10761 path_sub : substring match
Willy Tarreau6a06a402007-07-15 20:15:28 +020010762
Willy Tarreau74ca5042013-06-11 23:12:07 +020010763req.ver : string
10764req_ver : string (deprecated)
10765 Returns the version string from the HTTP request, for example "1.1". This can
10766 be useful for logs, but is mostly there for ACL. Some predefined ACL already
10767 check for versions 1.0 and 1.1.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010768
Willy Tarreau74ca5042013-06-11 23:12:07 +020010769 ACL derivatives :
10770 req_ver : exact string match
Willy Tarreau0e698542011-09-16 08:32:32 +020010771
Willy Tarreau74ca5042013-06-11 23:12:07 +020010772res.comp : boolean
10773 Returns the boolean "true" value if the response has been compressed by
10774 HAProxy, otherwise returns boolean "false". This may be used to add
10775 information in the logs.
Willy Tarreau6a06a402007-07-15 20:15:28 +020010776
Willy Tarreau74ca5042013-06-11 23:12:07 +020010777res.comp_algo : string
10778 Returns a string containing the name of the algorithm used if the response
10779 was compressed by HAProxy, for example : "deflate". This may be used to add
10780 some information in the logs.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010781
Willy Tarreau74ca5042013-06-11 23:12:07 +020010782res.cook([<name>]) : string
10783scook([<name>]) : string (deprecated)
10784 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
10785 header line from the response, and returns its value as string. If no name is
10786 specified, the first cookie value is returned.
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020010787
Willy Tarreau74ca5042013-06-11 23:12:07 +020010788 ACL derivatives :
10789 scook([<name>] : exact string match
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020010790
Willy Tarreau74ca5042013-06-11 23:12:07 +020010791res.cook_cnt([<name>]) : integer
10792scook_cnt([<name>]) : integer (deprecated)
10793 Returns an integer value representing the number of occurrences of the cookie
10794 <name> in the response, or all cookies if <name> is not specified. This is
10795 mostly useful when combined with ACLs to detect suspicious responses.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010796
Willy Tarreau74ca5042013-06-11 23:12:07 +020010797res.cook_val([<name>]) : integer
10798scook_val([<name>]) : integer (deprecated)
10799 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
10800 header line from the response, and converts its value to an integer which is
10801 returned. If no name is specified, the first cookie value is returned.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010802
Willy Tarreau74ca5042013-06-11 23:12:07 +020010803res.fhdr([<name>[,<occ>]]) : string
10804 This extracts the last occurrence of header <name> in an HTTP response, or of
10805 the last header if no <name> is specified. Optionally, a specific occurrence
10806 might be specified as a position number. Positive values indicate a position
10807 from the first occurrence, with 1 being the first one. Negative values
10808 indicate positions relative to the last one, with -1 being the last one. It
10809 differs from res.hdr() in that any commas present in the value are returned
10810 and are not used as delimiters. If this is not desired, the res.hdr() fetch
10811 should be used instead. This is sometimes useful with headers such as Date or
10812 Expires.
Willy Tarreau6a06a402007-07-15 20:15:28 +020010813
Willy Tarreau74ca5042013-06-11 23:12:07 +020010814res.fhdr_cnt([<name>]) : integer
10815 Returns an integer value representing the number of occurrences of response
10816 header field name <name>, or the total number of header fields if <name> is
10817 not specified. Contrary to its res.hdr_cnt() cousin, this function returns
10818 the number of full line headers and does not stop on commas. If this is not
10819 desired, the res.hdr_cnt() fetch should be used instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020010820
Willy Tarreau74ca5042013-06-11 23:12:07 +020010821res.hdr([<name>[,<occ>]]) : string
10822shdr([<name>[,<occ>]]) : string (deprecated)
10823 This extracts the last occurrence of header <name> in an HTTP response, or of
10824 the last header if no <name> is specified. Optionally, a specific occurrence
10825 might be specified as a position number. Positive values indicate a position
10826 from the first occurrence, with 1 being the first one. Negative values
10827 indicate positions relative to the last one, with -1 being the last one. This
10828 can be useful to learn some data into a stick-table. The function considers
10829 any comma as a delimiter for distinct values. If this is not desired, the
10830 res.fhdr() fetch should be used instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020010831
Willy Tarreau74ca5042013-06-11 23:12:07 +020010832 ACL derivatives :
10833 shdr([<name>[,<occ>]]) : exact string match
10834 shdr_beg([<name>[,<occ>]]) : prefix match
10835 shdr_dir([<name>[,<occ>]]) : subdir match
10836 shdr_dom([<name>[,<occ>]]) : domain match
10837 shdr_end([<name>[,<occ>]]) : suffix match
10838 shdr_len([<name>[,<occ>]]) : length match
10839 shdr_reg([<name>[,<occ>]]) : regex match
10840 shdr_sub([<name>[,<occ>]]) : substring match
10841
10842res.hdr_cnt([<name>]) : integer
10843shdr_cnt([<name>]) : integer (deprecated)
10844 Returns an integer value representing the number of occurrences of response
10845 header field name <name>, or the total number of header fields if <name> is
10846 not specified. The function considers any comma as a delimiter for distinct
10847 values. If this is not desired, the res.fhdr_cnt() fetch should be used
10848 instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020010849
Willy Tarreau74ca5042013-06-11 23:12:07 +020010850res.hdr_ip([<name>[,<occ>]]) : ip
10851shdr_ip([<name>[,<occ>]]) : ip (deprecated)
10852 This extracts the last occurrence of header <name> in an HTTP response,
10853 convert it to an IPv4 or IPv6 address and returns this address. Optionally, a
10854 specific occurrence might be specified as a position number. Positive values
10855 indicate a position from the first occurrence, with 1 being the first one.
10856 Negative values indicate positions relative to the last one, with -1 being
10857 the last one. This can be useful to learn some data into a stick table.
Willy Tarreau6a06a402007-07-15 20:15:28 +020010858
Willy Tarreau74ca5042013-06-11 23:12:07 +020010859res.hdr_val([<name>[,<occ>]]) : integer
10860shdr_val([<name>[,<occ>]]) : integer (deprecated)
10861 This extracts the last occurrence of header <name> in an HTTP response, and
10862 converts it to an integer value. Optionally, a specific occurrence might be
10863 specified as a position number. Positive values indicate a position from the
10864 first occurrence, with 1 being the first one. Negative values indicate
10865 positions relative to the last one, with -1 being the last one. This can be
10866 useful to learn some data into a stick table.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010010867
Willy Tarreau74ca5042013-06-11 23:12:07 +020010868res.ver : string
10869resp_ver : string (deprecated)
10870 Returns the version string from the HTTP response, for example "1.1". This
10871 can be useful for logs, but is mostly there for ACL.
Willy Tarreau0e698542011-09-16 08:32:32 +020010872
Willy Tarreau74ca5042013-06-11 23:12:07 +020010873 ACL derivatives :
10874 resp_ver : exact string match
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010010875
Willy Tarreau74ca5042013-06-11 23:12:07 +020010876set-cookie([<name>]) : string (deprecated)
10877 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
10878 header line from the response and uses the corresponding value to match. This
10879 can be comparable to what "appsession" does with default options, but with
10880 support for multi-peer synchronization and state keeping across restarts.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010010881
Willy Tarreau74ca5042013-06-11 23:12:07 +020010882 This fetch function is deprecated and has been superseded by the "res.cook"
10883 fetch. This keyword will disappear soon.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010010884
Willy Tarreau74ca5042013-06-11 23:12:07 +020010885 See also : "appsession"
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020010886
Willy Tarreau74ca5042013-06-11 23:12:07 +020010887status : integer
10888 Returns an integer containing the HTTP status code in the HTTP response, for
10889 example, 302. It is mostly used within ACLs and integer ranges, for example,
10890 to remove any Location header if the response is not a 3xx.
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020010891
Willy Tarreau74ca5042013-06-11 23:12:07 +020010892url : string
10893 This extracts the request's URL as presented in the request. A typical use is
10894 with prefetch-capable caches, and with portals which need to aggregate
10895 multiple information from databases and keep them in caches. With ACLs, using
10896 "path" is preferred over using "url", because clients may send a full URL as
10897 is normally done with proxies. The only real use is to match "*" which does
10898 not match in "path", and for which there is already a predefined ACL. See
10899 also "path" and "base".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020010900
Willy Tarreau74ca5042013-06-11 23:12:07 +020010901 ACL derivatives :
10902 url : exact string match
10903 url_beg : prefix match
10904 url_dir : subdir match
10905 url_dom : domain match
10906 url_end : suffix match
10907 url_len : length match
10908 url_reg : regex match
10909 url_sub : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020010910
Willy Tarreau74ca5042013-06-11 23:12:07 +020010911url_ip : ip
10912 This extracts the IP address from the request's URL when the host part is
10913 presented as an IP address. Its use is very limited. For instance, a
10914 monitoring system might use this field as an alternative for the source IP in
10915 order to test what path a given source address would follow, or to force an
10916 entry in a table for a given source address. With ACLs it can be used to
10917 restrict access to certain systems through a proxy, for example when combined
10918 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020010919
Willy Tarreau74ca5042013-06-11 23:12:07 +020010920url_port : integer
10921 This extracts the port part from the request's URL. Note that if the port is
10922 not specified in the request, port 80 is assumed. With ACLs it can be used to
10923 restrict access to certain systems through a proxy, for example when combined
10924 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020010925
Willy Tarreau74ca5042013-06-11 23:12:07 +020010926urlp(<name>[,<delim>]) : string
10927url_param(<name>[,<delim>]) : string
10928 This extracts the first occurrence of the parameter <name> in the query
10929 string, which begins after either '?' or <delim>, and which ends before '&',
10930 ';' or <delim>. The parameter name is case-sensitive. The result is a string
10931 corresponding to the value of the parameter <name> as presented in the
10932 request (no URL decoding is performed). This can be used for session
10933 stickiness based on a client ID, to extract an application cookie passed as a
10934 URL parameter, or in ACLs to apply some checks. Note that the ACL version of
10935 this fetch do not iterate over multiple parameters and stop at the first one
10936 as well.
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020010937
Willy Tarreau74ca5042013-06-11 23:12:07 +020010938 ACL derivatives :
10939 urlp(<name>[,<delim>]) : exact string match
10940 urlp_beg(<name>[,<delim>]) : prefix match
10941 urlp_dir(<name>[,<delim>]) : subdir match
10942 urlp_dom(<name>[,<delim>]) : domain match
10943 urlp_end(<name>[,<delim>]) : suffix match
10944 urlp_len(<name>[,<delim>]) : length match
10945 urlp_reg(<name>[,<delim>]) : regex match
10946 urlp_sub(<name>[,<delim>]) : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020010947
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020010948
Willy Tarreau74ca5042013-06-11 23:12:07 +020010949 Example :
10950 # match http://example.com/foo?PHPSESSIONID=some_id
10951 stick on urlp(PHPSESSIONID)
10952 # match http://example.com/foo;JSESSIONID=some_id
10953 stick on urlp(JSESSIONID,;)
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020010954
Willy Tarreau74ca5042013-06-11 23:12:07 +020010955urlp_val(<name>[,<delim>]) : integer
10956 See "urlp" above. This one extracts the URL parameter <name> in the request
10957 and converts it to an integer value. This can be used for session stickiness
10958 based on a user ID for example, or with ACLs to match a page number or price.
Willy Tarreaua9fddca2012-07-31 07:51:48 +020010959
Willy Tarreau198a7442008-01-17 12:05:32 +010010960
Willy Tarreau74ca5042013-06-11 23:12:07 +0200109617.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010962---------------------
Willy Tarreauced27012008-01-17 20:35:34 +010010963
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010964Some predefined ACLs are hard-coded so that they do not have to be declared in
10965every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +020010966order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +010010967
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010968ACL name Equivalent to Usage
10969---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010970FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +020010971HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010972HTTP_1.0 req_ver 1.0 match HTTP version 1.0
10973HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +010010974HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
10975HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
10976HTTP_URL_SLASH url_beg / match URL beginning with "/"
10977HTTP_URL_STAR url * match URL equal to "*"
10978LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010979METH_CONNECT method CONNECT match HTTP CONNECT method
10980METH_GET method GET HEAD match HTTP GET or HEAD method
10981METH_HEAD method HEAD match HTTP HEAD method
10982METH_OPTIONS method OPTIONS match HTTP OPTIONS method
10983METH_POST method POST match HTTP POST method
10984METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +020010985RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010986REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +010010987TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010988WAIT_END wait_end wait for end of content analysis
10989---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +010010990
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010991
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200109928. Logging
10993----------
Willy Tarreau844e3c52008-01-11 16:28:18 +010010994
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010995One of HAProxy's strong points certainly lies is its precise logs. It probably
10996provides the finest level of information available for such a product, which is
10997very important for troubleshooting complex environments. Standard information
10998provided in logs include client ports, TCP/HTTP state timers, precise session
10999state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011000to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011001headers.
11002
11003In order to improve administrators reactivity, it offers a great transparency
11004about encountered problems, both internal and external, and it is possible to
11005send logs to different sources at the same time with different level filters :
11006
11007 - global process-level logs (system errors, start/stop, etc..)
11008 - per-instance system and internal errors (lack of resource, bugs, ...)
11009 - per-instance external troubles (servers up/down, max connections)
11010 - per-instance activity (client connections), either at the establishment or
11011 at the termination.
11012
11013The ability to distribute different levels of logs to different log servers
11014allow several production teams to interact and to fix their problems as soon
11015as possible. For example, the system team might monitor system-wide errors,
11016while the application team might be monitoring the up/down for their servers in
11017real time, and the security team might analyze the activity logs with one hour
11018delay.
11019
11020
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200110218.1. Log levels
11022---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011023
Simon Hormandf791f52011-05-29 15:01:10 +090011024TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011025source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +090011026HTTP request, HTTP return code, number of bytes transmitted, conditions
11027in which the session ended, and even exchanged cookies values. For example
11028track a particular user's problems. All messages may be sent to up to two
11029syslog servers. Check the "log" keyword in section 4.2 for more information
11030about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011031
11032
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200110338.2. Log formats
11034----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011035
William Lallemand48940402012-01-30 16:47:22 +010011036HAProxy supports 5 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +090011037and will be detailed in the following sections. A few of them may vary
11038slightly with the configuration, due to indicators specific to certain
11039options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011040
11041 - the default format, which is very basic and very rarely used. It only
11042 provides very basic information about the incoming connection at the moment
11043 it is accepted : source IP:port, destination IP:port, and frontend-name.
11044 This mode will eventually disappear so it will not be described to great
11045 extents.
11046
11047 - the TCP format, which is more advanced. This format is enabled when "option
11048 tcplog" is set on the frontend. HAProxy will then usually wait for the
11049 connection to terminate before logging. This format provides much richer
11050 information, such as timers, connection counts, queue size, etc... This
11051 format is recommended for pure TCP proxies.
11052
11053 - the HTTP format, which is the most advanced for HTTP proxying. This format
11054 is enabled when "option httplog" is set on the frontend. It provides the
11055 same information as the TCP format with some HTTP-specific fields such as
11056 the request, the status code, and captures of headers and cookies. This
11057 format is recommended for HTTP proxies.
11058
Emeric Brun3a058f32009-06-30 18:26:00 +020011059 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
11060 fields arranged in the same order as the CLF format. In this mode, all
11061 timers, captures, flags, etc... appear one per field after the end of the
11062 common fields, in the same order they appear in the standard HTTP format.
11063
William Lallemand48940402012-01-30 16:47:22 +010011064 - the custom log format, allows you to make your own log line.
11065
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011066Next sections will go deeper into details for each of these formats. Format
11067specification will be performed on a "field" basis. Unless stated otherwise, a
11068field is a portion of text delimited by any number of spaces. Since syslog
11069servers are susceptible of inserting fields at the beginning of a line, it is
11070always assumed that the first field is the one containing the process name and
11071identifier.
11072
11073Note : Since log lines may be quite long, the log examples in sections below
11074 might be broken into multiple lines. The example log lines will be
11075 prefixed with 3 closing angle brackets ('>>>') and each time a log is
11076 broken into multiple lines, each non-final line will end with a
11077 backslash ('\') and the next line will start indented by two characters.
11078
11079
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200110808.2.1. Default log format
11081-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011082
11083This format is used when no specific option is set. The log is emitted as soon
11084as the connection is accepted. One should note that this currently is the only
11085format which logs the request's destination IP and ports.
11086
11087 Example :
11088 listen www
11089 mode http
11090 log global
11091 server srv1 127.0.0.1:8000
11092
11093 >>> Feb 6 12:12:09 localhost \
11094 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
11095 (www/HTTP)
11096
11097 Field Format Extract from the example above
11098 1 process_name '[' pid ']:' haproxy[14385]:
11099 2 'Connect from' Connect from
11100 3 source_ip ':' source_port 10.0.1.2:33312
11101 4 'to' to
11102 5 destination_ip ':' destination_port 10.0.3.31:8012
11103 6 '(' frontend_name '/' mode ')' (www/HTTP)
11104
11105Detailed fields description :
11106 - "source_ip" is the IP address of the client which initiated the connection.
11107 - "source_port" is the TCP port of the client which initiated the connection.
11108 - "destination_ip" is the IP address the client connected to.
11109 - "destination_port" is the TCP port the client connected to.
11110 - "frontend_name" is the name of the frontend (or listener) which received
11111 and processed the connection.
11112 - "mode is the mode the frontend is operating (TCP or HTTP).
11113
Willy Tarreauceb24bc2010-11-09 12:46:41 +010011114In case of a UNIX socket, the source and destination addresses are marked as
11115"unix:" and the ports reflect the internal ID of the socket which accepted the
11116connection (the same ID as reported in the stats).
11117
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011118It is advised not to use this deprecated format for newer installations as it
11119will eventually disappear.
11120
11121
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200111228.2.2. TCP log format
11123---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011124
11125The TCP format is used when "option tcplog" is specified in the frontend, and
11126is the recommended format for pure TCP proxies. It provides a lot of precious
11127information for troubleshooting. Since this format includes timers and byte
11128counts, the log is normally emitted at the end of the session. It can be
11129emitted earlier if "option logasap" is specified, which makes sense in most
11130environments with long sessions such as remote terminals. Sessions which match
11131the "monitor" rules are never logged. It is also possible not to emit logs for
11132sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020011133specifying "option dontlognull" in the frontend. Successful connections will
11134not be logged if "option dontlog-normal" is specified in the frontend. A few
11135fields may slightly vary depending on some configuration options, those are
11136marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011137
11138 Example :
11139 frontend fnt
11140 mode tcp
11141 option tcplog
11142 log global
11143 default_backend bck
11144
11145 backend bck
11146 server srv1 127.0.0.1:8000
11147
11148 >>> Feb 6 12:12:56 localhost \
11149 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
11150 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
11151
11152 Field Format Extract from the example above
11153 1 process_name '[' pid ']:' haproxy[14387]:
11154 2 client_ip ':' client_port 10.0.1.2:33313
11155 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
11156 4 frontend_name fnt
11157 5 backend_name '/' server_name bck/srv1
11158 6 Tw '/' Tc '/' Tt* 0/0/5007
11159 7 bytes_read* 212
11160 8 termination_state --
11161 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
11162 10 srv_queue '/' backend_queue 0/0
11163
11164Detailed fields description :
11165 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010011166 connection to haproxy. If the connection was accepted on a UNIX socket
11167 instead, the IP address would be replaced with the word "unix". Note that
11168 when the connection is accepted on a socket configured with "accept-proxy"
11169 and the PROXY protocol is correctly used, then the logs will reflect the
11170 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011171
11172 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010011173 If the connection was accepted on a UNIX socket instead, the port would be
11174 replaced with the ID of the accepting socket, which is also reported in the
11175 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011176
11177 - "accept_date" is the exact date when the connection was received by haproxy
11178 (which might be very slightly different from the date observed on the
11179 network if there was some queuing in the system's backlog). This is usually
11180 the same date which may appear in any upstream firewall's log.
11181
11182 - "frontend_name" is the name of the frontend (or listener) which received
11183 and processed the connection.
11184
11185 - "backend_name" is the name of the backend (or listener) which was selected
11186 to manage the connection to the server. This will be the same as the
11187 frontend if no switching rule has been applied, which is common for TCP
11188 applications.
11189
11190 - "server_name" is the name of the last server to which the connection was
11191 sent, which might differ from the first one if there were connection errors
11192 and a redispatch occurred. Note that this server belongs to the backend
11193 which processed the request. If the connection was aborted before reaching
11194 a server, "<NOSRV>" is indicated instead of a server name.
11195
11196 - "Tw" is the total time in milliseconds spent waiting in the various queues.
11197 It can be "-1" if the connection was aborted before reaching the queue.
11198 See "Timers" below for more details.
11199
11200 - "Tc" is the total time in milliseconds spent waiting for the connection to
11201 establish to the final server, including retries. It can be "-1" if the
11202 connection was aborted before a connection could be established. See
11203 "Timers" below for more details.
11204
11205 - "Tt" is the total time in milliseconds elapsed between the accept and the
11206 last close. It covers all possible processings. There is one exception, if
11207 "option logasap" was specified, then the time counting stops at the moment
11208 the log is emitted. In this case, a '+' sign is prepended before the value,
11209 indicating that the final one will be larger. See "Timers" below for more
11210 details.
11211
11212 - "bytes_read" is the total number of bytes transmitted from the server to
11213 the client when the log is emitted. If "option logasap" is specified, the
11214 this value will be prefixed with a '+' sign indicating that the final one
11215 may be larger. Please note that this value is a 64-bit counter, so log
11216 analysis tools must be able to handle it without overflowing.
11217
11218 - "termination_state" is the condition the session was in when the session
11219 ended. This indicates the session state, which side caused the end of
11220 session to happen, and for what reason (timeout, error, ...). The normal
11221 flags should be "--", indicating the session was closed by either end with
11222 no data remaining in buffers. See below "Session state at disconnection"
11223 for more details.
11224
11225 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040011226 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011227 limits have been reached. For instance, if actconn is close to 512 when
11228 multiple connection errors occur, chances are high that the system limits
11229 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011230 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011231
11232 - "feconn" is the total number of concurrent connections on the frontend when
11233 the session was logged. It is useful to estimate the amount of resource
11234 required to sustain high loads, and to detect when the frontend's "maxconn"
11235 has been reached. Most often when this value increases by huge jumps, it is
11236 because there is congestion on the backend servers, but sometimes it can be
11237 caused by a denial of service attack.
11238
11239 - "beconn" is the total number of concurrent connections handled by the
11240 backend when the session was logged. It includes the total number of
11241 concurrent connections active on servers as well as the number of
11242 connections pending in queues. It is useful to estimate the amount of
11243 additional servers needed to support high loads for a given application.
11244 Most often when this value increases by huge jumps, it is because there is
11245 congestion on the backend servers, but sometimes it can be caused by a
11246 denial of service attack.
11247
11248 - "srv_conn" is the total number of concurrent connections still active on
11249 the server when the session was logged. It can never exceed the server's
11250 configured "maxconn" parameter. If this value is very often close or equal
11251 to the server's "maxconn", it means that traffic regulation is involved a
11252 lot, meaning that either the server's maxconn value is too low, or that
11253 there aren't enough servers to process the load with an optimal response
11254 time. When only one of the server's "srv_conn" is high, it usually means
11255 that this server has some trouble causing the connections to take longer to
11256 be processed than on other servers.
11257
11258 - "retries" is the number of connection retries experienced by this session
11259 when trying to connect to the server. It must normally be zero, unless a
11260 server is being stopped at the same moment the connection was attempted.
11261 Frequent retries generally indicate either a network problem between
11262 haproxy and the server, or a misconfigured system backlog on the server
11263 preventing new connections from being queued. This field may optionally be
11264 prefixed with a '+' sign, indicating that the session has experienced a
11265 redispatch after the maximal retry count has been reached on the initial
11266 server. In this case, the server name appearing in the log is the one the
11267 connection was redispatched to, and not the first one, though both may
11268 sometimes be the same in case of hashing for instance. So as a general rule
11269 of thumb, when a '+' is present in front of the retry count, this count
11270 should not be attributed to the logged server.
11271
11272 - "srv_queue" is the total number of requests which were processed before
11273 this one in the server queue. It is zero when the request has not gone
11274 through the server queue. It makes it possible to estimate the approximate
11275 server's response time by dividing the time spent in queue by the number of
11276 requests in the queue. It is worth noting that if a session experiences a
11277 redispatch and passes through two server queues, their positions will be
11278 cumulated. A request should not pass through both the server queue and the
11279 backend queue unless a redispatch occurs.
11280
11281 - "backend_queue" is the total number of requests which were processed before
11282 this one in the backend's global queue. It is zero when the request has not
11283 gone through the global queue. It makes it possible to estimate the average
11284 queue length, which easily translates into a number of missing servers when
11285 divided by a server's "maxconn" parameter. It is worth noting that if a
11286 session experiences a redispatch, it may pass twice in the backend's queue,
11287 and then both positions will be cumulated. A request should not pass
11288 through both the server queue and the backend queue unless a redispatch
11289 occurs.
11290
11291
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200112928.2.3. HTTP log format
11293----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011294
11295The HTTP format is the most complete and the best suited for HTTP proxies. It
11296is enabled by when "option httplog" is specified in the frontend. It provides
11297the same level of information as the TCP format with additional features which
11298are specific to the HTTP protocol. Just like the TCP format, the log is usually
11299emitted at the end of the session, unless "option logasap" is specified, which
11300generally only makes sense for download sites. A session which matches the
11301"monitor" rules will never logged. It is also possible not to log sessions for
11302which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020011303frontend. Successful connections will not be logged if "option dontlog-normal"
11304is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011305
11306Most fields are shared with the TCP log, some being different. A few fields may
11307slightly vary depending on some configuration options. Those ones are marked
11308with a star ('*') after the field name below.
11309
11310 Example :
11311 frontend http-in
11312 mode http
11313 option httplog
11314 log global
11315 default_backend bck
11316
11317 backend static
11318 server srv1 127.0.0.1:8000
11319
11320 >>> Feb 6 12:14:14 localhost \
11321 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
11322 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 +010011323 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011324
11325 Field Format Extract from the example above
11326 1 process_name '[' pid ']:' haproxy[14389]:
11327 2 client_ip ':' client_port 10.0.1.2:33317
11328 3 '[' accept_date ']' [06/Feb/2009:12:14:14.655]
11329 4 frontend_name http-in
11330 5 backend_name '/' server_name static/srv1
11331 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt* 10/0/30/69/109
11332 7 status_code 200
11333 8 bytes_read* 2750
11334 9 captured_request_cookie -
11335 10 captured_response_cookie -
11336 11 termination_state ----
11337 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
11338 13 srv_queue '/' backend_queue 0/0
11339 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
11340 15 '{' captured_response_headers* '}' {}
11341 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +010011342
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011343
11344Detailed fields description :
11345 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010011346 connection to haproxy. If the connection was accepted on a UNIX socket
11347 instead, the IP address would be replaced with the word "unix". Note that
11348 when the connection is accepted on a socket configured with "accept-proxy"
11349 and the PROXY protocol is correctly used, then the logs will reflect the
11350 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011351
11352 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010011353 If the connection was accepted on a UNIX socket instead, the port would be
11354 replaced with the ID of the accepting socket, which is also reported in the
11355 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011356
11357 - "accept_date" is the exact date when the TCP connection was received by
11358 haproxy (which might be very slightly different from the date observed on
11359 the network if there was some queuing in the system's backlog). This is
11360 usually the same date which may appear in any upstream firewall's log. This
11361 does not depend on the fact that the client has sent the request or not.
11362
11363 - "frontend_name" is the name of the frontend (or listener) which received
11364 and processed the connection.
11365
11366 - "backend_name" is the name of the backend (or listener) which was selected
11367 to manage the connection to the server. This will be the same as the
11368 frontend if no switching rule has been applied.
11369
11370 - "server_name" is the name of the last server to which the connection was
11371 sent, which might differ from the first one if there were connection errors
11372 and a redispatch occurred. Note that this server belongs to the backend
11373 which processed the request. If the request was aborted before reaching a
11374 server, "<NOSRV>" is indicated instead of a server name. If the request was
11375 intercepted by the stats subsystem, "<STATS>" is indicated instead.
11376
11377 - "Tq" is the total time in milliseconds spent waiting for the client to send
11378 a full HTTP request, not counting data. It can be "-1" if the connection
11379 was aborted before a complete request could be received. It should always
11380 be very small because a request generally fits in one single packet. Large
11381 times here generally indicate network trouble between the client and
11382 haproxy. See "Timers" below for more details.
11383
11384 - "Tw" is the total time in milliseconds spent waiting in the various queues.
11385 It can be "-1" if the connection was aborted before reaching the queue.
11386 See "Timers" below for more details.
11387
11388 - "Tc" is the total time in milliseconds spent waiting for the connection to
11389 establish to the final server, including retries. It can be "-1" if the
11390 request was aborted before a connection could be established. See "Timers"
11391 below for more details.
11392
11393 - "Tr" is the total time in milliseconds spent waiting for the server to send
11394 a full HTTP response, not counting data. It can be "-1" if the request was
11395 aborted before a complete response could be received. It generally matches
11396 the server's processing time for the request, though it may be altered by
11397 the amount of data sent by the client to the server. Large times here on
11398 "GET" requests generally indicate an overloaded server. See "Timers" below
11399 for more details.
11400
11401 - "Tt" is the total time in milliseconds elapsed between the accept and the
11402 last close. It covers all possible processings. There is one exception, if
11403 "option logasap" was specified, then the time counting stops at the moment
11404 the log is emitted. In this case, a '+' sign is prepended before the value,
11405 indicating that the final one will be larger. See "Timers" below for more
11406 details.
11407
11408 - "status_code" is the HTTP status code returned to the client. This status
11409 is generally set by the server, but it might also be set by haproxy when
11410 the server cannot be reached or when its response is blocked by haproxy.
11411
11412 - "bytes_read" is the total number of bytes transmitted to the client when
11413 the log is emitted. This does include HTTP headers. If "option logasap" is
11414 specified, the this value will be prefixed with a '+' sign indicating that
11415 the final one may be larger. Please note that this value is a 64-bit
11416 counter, so log analysis tools must be able to handle it without
11417 overflowing.
11418
11419 - "captured_request_cookie" is an optional "name=value" entry indicating that
11420 the client had this cookie in the request. The cookie name and its maximum
11421 length are defined by the "capture cookie" statement in the frontend
11422 configuration. The field is a single dash ('-') when the option is not
11423 set. Only one cookie may be captured, it is generally used to track session
11424 ID exchanges between a client and a server to detect session crossing
11425 between clients due to application bugs. For more details, please consult
11426 the section "Capturing HTTP headers and cookies" below.
11427
11428 - "captured_response_cookie" is an optional "name=value" entry indicating
11429 that the server has returned a cookie with its response. The cookie name
11430 and its maximum length are defined by the "capture cookie" statement in the
11431 frontend configuration. The field is a single dash ('-') when the option is
11432 not set. Only one cookie may be captured, it is generally used to track
11433 session ID exchanges between a client and a server to detect session
11434 crossing between clients due to application bugs. For more details, please
11435 consult the section "Capturing HTTP headers and cookies" below.
11436
11437 - "termination_state" is the condition the session was in when the session
11438 ended. This indicates the session state, which side caused the end of
11439 session to happen, for what reason (timeout, error, ...), just like in TCP
11440 logs, and information about persistence operations on cookies in the last
11441 two characters. The normal flags should begin with "--", indicating the
11442 session was closed by either end with no data remaining in buffers. See
11443 below "Session state at disconnection" for more details.
11444
11445 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040011446 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011447 limits have been reached. For instance, if actconn is close to 512 or 1024
11448 when multiple connection errors occur, chances are high that the system
11449 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011450 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011451 system.
11452
11453 - "feconn" is the total number of concurrent connections on the frontend when
11454 the session was logged. It is useful to estimate the amount of resource
11455 required to sustain high loads, and to detect when the frontend's "maxconn"
11456 has been reached. Most often when this value increases by huge jumps, it is
11457 because there is congestion on the backend servers, but sometimes it can be
11458 caused by a denial of service attack.
11459
11460 - "beconn" is the total number of concurrent connections handled by the
11461 backend when the session was logged. It includes the total number of
11462 concurrent connections active on servers as well as the number of
11463 connections pending in queues. It is useful to estimate the amount of
11464 additional servers needed to support high loads for a given application.
11465 Most often when this value increases by huge jumps, it is because there is
11466 congestion on the backend servers, but sometimes it can be caused by a
11467 denial of service attack.
11468
11469 - "srv_conn" is the total number of concurrent connections still active on
11470 the server when the session was logged. It can never exceed the server's
11471 configured "maxconn" parameter. If this value is very often close or equal
11472 to the server's "maxconn", it means that traffic regulation is involved a
11473 lot, meaning that either the server's maxconn value is too low, or that
11474 there aren't enough servers to process the load with an optimal response
11475 time. When only one of the server's "srv_conn" is high, it usually means
11476 that this server has some trouble causing the requests to take longer to be
11477 processed than on other servers.
11478
11479 - "retries" is the number of connection retries experienced by this session
11480 when trying to connect to the server. It must normally be zero, unless a
11481 server is being stopped at the same moment the connection was attempted.
11482 Frequent retries generally indicate either a network problem between
11483 haproxy and the server, or a misconfigured system backlog on the server
11484 preventing new connections from being queued. This field may optionally be
11485 prefixed with a '+' sign, indicating that the session has experienced a
11486 redispatch after the maximal retry count has been reached on the initial
11487 server. In this case, the server name appearing in the log is the one the
11488 connection was redispatched to, and not the first one, though both may
11489 sometimes be the same in case of hashing for instance. So as a general rule
11490 of thumb, when a '+' is present in front of the retry count, this count
11491 should not be attributed to the logged server.
11492
11493 - "srv_queue" is the total number of requests which were processed before
11494 this one in the server queue. It is zero when the request has not gone
11495 through the server queue. It makes it possible to estimate the approximate
11496 server's response time by dividing the time spent in queue by the number of
11497 requests in the queue. It is worth noting that if a session experiences a
11498 redispatch and passes through two server queues, their positions will be
11499 cumulated. A request should not pass through both the server queue and the
11500 backend queue unless a redispatch occurs.
11501
11502 - "backend_queue" is the total number of requests which were processed before
11503 this one in the backend's global queue. It is zero when the request has not
11504 gone through the global queue. It makes it possible to estimate the average
11505 queue length, which easily translates into a number of missing servers when
11506 divided by a server's "maxconn" parameter. It is worth noting that if a
11507 session experiences a redispatch, it may pass twice in the backend's queue,
11508 and then both positions will be cumulated. A request should not pass
11509 through both the server queue and the backend queue unless a redispatch
11510 occurs.
11511
11512 - "captured_request_headers" is a list of headers captured in the request due
11513 to the presence of the "capture request header" statement in the frontend.
11514 Multiple headers can be captured, they will be delimited by a vertical bar
11515 ('|'). When no capture is enabled, the braces do not appear, causing a
11516 shift of remaining fields. It is important to note that this field may
11517 contain spaces, and that using it requires a smarter log parser than when
11518 it's not used. Please consult the section "Capturing HTTP headers and
11519 cookies" below for more details.
11520
11521 - "captured_response_headers" is a list of headers captured in the response
11522 due to the presence of the "capture response header" statement in the
11523 frontend. Multiple headers can be captured, they will be delimited by a
11524 vertical bar ('|'). When no capture is enabled, the braces do not appear,
11525 causing a shift of remaining fields. It is important to note that this
11526 field may contain spaces, and that using it requires a smarter log parser
11527 than when it's not used. Please consult the section "Capturing HTTP headers
11528 and cookies" below for more details.
11529
11530 - "http_request" is the complete HTTP request line, including the method,
11531 request and HTTP version string. Non-printable characters are encoded (see
11532 below the section "Non-printable characters"). This is always the last
11533 field, and it is always delimited by quotes and is the only one which can
11534 contain quotes. If new fields are added to the log format, they will be
11535 added before this field. This field might be truncated if the request is
11536 huge and does not fit in the standard syslog buffer (1024 characters). This
11537 is the reason why this field must always remain the last one.
11538
11539
Cyril Bontédc4d9032012-04-08 21:57:39 +0200115408.2.4. Custom log format
11541------------------------
William Lallemand48940402012-01-30 16:47:22 +010011542
Willy Tarreau2beef582012-12-20 17:22:52 +010011543The directive log-format allows you to customize the logs in http mode and tcp
William Lallemandbddd4fd2012-02-27 11:23:10 +010011544mode. It takes a string as argument.
William Lallemand48940402012-01-30 16:47:22 +010011545
11546HAproxy understands some log format variables. % precedes log format variables.
11547Variables can take arguments using braces ('{}'), and multiple arguments are
11548separated by commas within the braces. Flags may be added or removed by
11549prefixing them with a '+' or '-' sign.
11550
11551Special variable "%o" may be used to propagate its flags to all other
11552variables on the same format string. This is particularly handy with quoted
11553string formats ("Q").
11554
Willy Tarreauc8368452012-12-21 00:09:23 +010011555If a variable is named between square brackets ('[' .. ']') then it is used
Willy Tarreau74ca5042013-06-11 23:12:07 +020011556as a pattern extraction rule (see section 7.3). This it useful to add some
Willy Tarreauc8368452012-12-21 00:09:23 +010011557less common information such as the client's SSL certificate's DN, or to log
11558the key that would be used to store an entry into a stick table.
11559
William Lallemand48940402012-01-30 16:47:22 +010011560Note: spaces must be escaped. A space character is considered as a separator.
Willy Tarreau06d97f92013-12-02 17:45:48 +010011561In order to emit a verbatim '%', it must be preceeded by another '%' resulting
11562in '%%'. HAProxy will automatically merge consecutive separators.
William Lallemand48940402012-01-30 16:47:22 +010011563
11564Flags are :
11565 * Q: quote a string
Jamie Gloudonaaa21002012-08-25 00:18:33 -040011566 * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid)
William Lallemand48940402012-01-30 16:47:22 +010011567
11568 Example:
11569
11570 log-format %T\ %t\ Some\ Text
11571 log-format %{+Q}o\ %t\ %s\ %{-Q}r
11572
11573At the moment, the default HTTP format is defined this way :
11574
Willy Tarreau2beef582012-12-20 17:22:52 +010011575 log-format %ci:%cp\ [%t]\ %ft\ %b/%s\ %Tq/%Tw/%Tc/%Tr/%Tt\ %ST\ %B\ %CC\ \
11576 %CS\ %tsc\ %ac/%fc/%bc/%sc/%rc\ %sq/%bq\ %hr\ %hs\ %{+Q}r
William Lallemand48940402012-01-30 16:47:22 +010011577
William Lallemandbddd4fd2012-02-27 11:23:10 +010011578the default CLF format is defined this way :
William Lallemand48940402012-01-30 16:47:22 +010011579
Willy Tarreau2beef582012-12-20 17:22:52 +010011580 log-format %{+Q}o\ %{-Q}ci\ -\ -\ [%T]\ %r\ %ST\ %B\ \"\"\ \"\"\ %cp\ \
Willy Tarreau773d65f2012-10-12 14:56:11 +020011581 %ms\ %ft\ %b\ %s\ \%Tq\ %Tw\ %Tc\ %Tr\ %Tt\ %tsc\ %ac\ %fc\ \
Willy Tarreau2beef582012-12-20 17:22:52 +010011582 %bc\ %sc\ %rc\ %sq\ %bq\ %CC\ %CS\ \%hrl\ %hsl
William Lallemand48940402012-01-30 16:47:22 +010011583
William Lallemandbddd4fd2012-02-27 11:23:10 +010011584and the default TCP format is defined this way :
11585
Willy Tarreau2beef582012-12-20 17:22:52 +010011586 log-format %ci:%cp\ [%t]\ %ft\ %b/%s\ %Tw/%Tc/%Tt\ %B\ %ts\ \
William Lallemandbddd4fd2012-02-27 11:23:10 +010011587 %ac/%fc/%bc/%sc/%rc\ %sq/%bq
11588
William Lallemand48940402012-01-30 16:47:22 +010011589Please refer to the table below for currently defined variables :
11590
William Lallemandbddd4fd2012-02-27 11:23:10 +010011591 +---+------+-----------------------------------------------+-------------+
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011592 | R | var | field name (8.2.2 and 8.2.3 for description) | type |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011593 +---+------+-----------------------------------------------+-------------+
11594 | | %o | special variable, apply flags on all next var | |
11595 +---+------+-----------------------------------------------+-------------+
Willy Tarreau2beef582012-12-20 17:22:52 +010011596 | | %B | bytes_read (from server to client) | numeric |
11597 | H | %CC | captured_request_cookie | string |
11598 | H | %CS | captured_response_cookie | string |
William Lallemand5f232402012-04-05 18:02:55 +020011599 | | %H | hostname | string |
William Lallemanda73203e2012-03-12 12:48:57 +010011600 | | %ID | unique-id | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010011601 | H | %ST | status_code | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020011602 | | %T | gmt_date_time | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011603 | | %Tc | Tc | numeric |
Yuxans Yao4e25b012012-10-19 10:36:09 +080011604 | | %Tl | local_date_time | date |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011605 | H | %Tq | Tq | numeric |
11606 | H | %Tr | Tr | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020011607 | | %Ts | timestamp | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011608 | | %Tt | Tt | numeric |
11609 | | %Tw | Tw | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010011610 | | %U | bytes_uploaded (from client to server) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011611 | | %ac | actconn | numeric |
11612 | | %b | backend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010011613 | | %bc | beconn (backend concurrent connections) | numeric |
11614 | | %bi | backend_source_ip (connecting address) | IP |
11615 | | %bp | backend_source_port (connecting address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011616 | | %bq | backend_queue | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010011617 | | %ci | client_ip (accepted address) | IP |
11618 | | %cp | client_port (accepted address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011619 | | %f | frontend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010011620 | | %fc | feconn (frontend concurrent connections) | numeric |
11621 | | %fi | frontend_ip (accepting address) | IP |
11622 | | %fp | frontend_port (accepting address) | numeric |
Willy Tarreau773d65f2012-10-12 14:56:11 +020011623 | | %ft | frontend_name_transport ('~' suffix for SSL) | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011624 | H | %hr | captured_request_headers default style | string |
11625 | H | %hrl | captured_request_headers CLF style | string list |
11626 | H | %hs | captured_response_headers default style | string |
11627 | H | %hsl | captured_response_headers CLF style | string list |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011628 | | %ms | accept date milliseconds | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020011629 | | %pid | PID | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011630 | H | %r | http_request | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011631 | | %rc | retries | numeric |
Willy Tarreau1f0da242014-01-25 11:01:50 +010011632 | | %rt | request_counter (HTTP req or TCP session) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011633 | | %s | server_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010011634 | | %sc | srv_conn (server concurrent connections) | numeric |
11635 | | %si | server_IP (target address) | IP |
11636 | | %sp | server_port (target address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011637 | | %sq | srv_queue | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011638 | S | %sslc| ssl_ciphers (ex: AES-SHA) | string |
11639 | S | %sslv| ssl_version (ex: TLSv1) | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010011640 | | %t | date_time (with millisecond resolution) | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011641 | | %ts | termination_state | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011642 | H | %tsc | termination_state with cookie status | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011643 +---+------+-----------------------------------------------+-------------+
William Lallemand48940402012-01-30 16:47:22 +010011644
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011645 R = Restrictions : H = mode http only ; S = SSL only
William Lallemand48940402012-01-30 16:47:22 +010011646
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010011647
116488.2.5. Error log format
11649-----------------------
11650
11651When an incoming connection fails due to an SSL handshake or an invalid PROXY
11652protocol header, haproxy will log the event using a shorter, fixed line format.
11653By default, logs are emitted at the LOG_INFO level, unless the option
11654"log-separate-errors" is set in the backend, in which case the LOG_ERR level
11655will be used. Connections on which no data are exchanged (eg: probes) are not
11656logged if the "dontlognull" option is set.
11657
11658The format looks like this :
11659
11660 >>> Dec 3 18:27:14 localhost \
11661 haproxy[6103]: 127.0.0.1:56059 [03/Dec/2012:17:35:10.380] frt/f1: \
11662 Connection error during SSL handshake
11663
11664 Field Format Extract from the example above
11665 1 process_name '[' pid ']:' haproxy[6103]:
11666 2 client_ip ':' client_port 127.0.0.1:56059
11667 3 '[' accept_date ']' [03/Dec/2012:17:35:10.380]
11668 4 frontend_name "/" bind_name ":" frt/f1:
11669 5 message Connection error during SSL handshake
11670
11671These fields just provide minimal information to help debugging connection
11672failures.
11673
11674
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200116758.3. Advanced logging options
11676-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011677
11678Some advanced logging options are often looked for but are not easy to find out
11679just by looking at the various options. Here is an entry point for the few
11680options which can enable better logging. Please refer to the keywords reference
11681for more information about their usage.
11682
11683
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200116848.3.1. Disabling logging of external tests
11685------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011686
11687It is quite common to have some monitoring tools perform health checks on
11688haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
11689commercial load-balancer, and sometimes it will simply be a more complete
11690monitoring system such as Nagios. When the tests are very frequent, users often
11691ask how to disable logging for those checks. There are three possibilities :
11692
11693 - if connections come from everywhere and are just TCP probes, it is often
11694 desired to simply disable logging of connections without data exchange, by
11695 setting "option dontlognull" in the frontend. It also disables logging of
11696 port scans, which may or may not be desired.
11697
11698 - if the connection come from a known source network, use "monitor-net" to
11699 declare this network as monitoring only. Any host in this network will then
11700 only be able to perform health checks, and their requests will not be
11701 logged. This is generally appropriate to designate a list of equipments
11702 such as other load-balancers.
11703
11704 - if the tests are performed on a known URI, use "monitor-uri" to declare
11705 this URI as dedicated to monitoring. Any host sending this request will
11706 only get the result of a health-check, and the request will not be logged.
11707
11708
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200117098.3.2. Logging before waiting for the session to terminate
11710----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011711
11712The problem with logging at end of connection is that you have no clue about
11713what is happening during very long sessions, such as remote terminal sessions
11714or large file downloads. This problem can be worked around by specifying
11715"option logasap" in the frontend. Haproxy will then log as soon as possible,
11716just before data transfer begins. This means that in case of TCP, it will still
11717log the connection status to the server, and in case of HTTP, it will log just
11718after processing the server headers. In this case, the number of bytes reported
11719is the number of header bytes sent to the client. In order to avoid confusion
11720with normal logs, the total time field and the number of bytes are prefixed
11721with a '+' sign which means that real numbers are certainly larger.
11722
11723
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200117248.3.3. Raising log level upon errors
11725------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020011726
11727Sometimes it is more convenient to separate normal traffic from errors logs,
11728for instance in order to ease error monitoring from log files. When the option
11729"log-separate-errors" is used, connections which experience errors, timeouts,
11730retries, redispatches or HTTP status codes 5xx will see their syslog level
11731raised from "info" to "err". This will help a syslog daemon store the log in
11732a separate file. It is very important to keep the errors in the normal traffic
11733file too, so that log ordering is not altered. You should also be careful if
11734you already have configured your syslog daemon to store all logs higher than
11735"notice" in an "admin" file, because the "err" level is higher than "notice".
11736
11737
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200117388.3.4. Disabling logging of successful connections
11739--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020011740
11741Although this may sound strange at first, some large sites have to deal with
11742multiple thousands of logs per second and are experiencing difficulties keeping
11743them intact for a long time or detecting errors within them. If the option
11744"dontlog-normal" is set on the frontend, all normal connections will not be
11745logged. In this regard, a normal connection is defined as one without any
11746error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
11747and a response with a status 5xx is not considered normal and will be logged
11748too. Of course, doing is is really discouraged as it will remove most of the
11749useful information from the logs. Do this only if you have no other
11750alternative.
11751
11752
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200117538.4. Timing events
11754------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011755
11756Timers provide a great help in troubleshooting network problems. All values are
11757reported in milliseconds (ms). These timers should be used in conjunction with
11758the session termination flags. In TCP mode with "option tcplog" set on the
11759frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
11760mode, 5 control points are reported under the form "Tq/Tw/Tc/Tr/Tt" :
11761
11762 - Tq: total time to get the client request (HTTP mode only). It's the time
11763 elapsed between the moment the client connection was accepted and the
11764 moment the proxy received the last HTTP header. The value "-1" indicates
11765 that the end of headers (empty line) has never been seen. This happens when
11766 the client closes prematurely or times out.
11767
11768 - Tw: total time spent in the queues waiting for a connection slot. It
11769 accounts for backend queue as well as the server queues, and depends on the
11770 queue size, and the time needed for the server to complete previous
11771 requests. The value "-1" means that the request was killed before reaching
11772 the queue, which is generally what happens with invalid or denied requests.
11773
11774 - Tc: total time to establish the TCP connection to the server. It's the time
11775 elapsed between the moment the proxy sent the connection request, and the
11776 moment it was acknowledged by the server, or between the TCP SYN packet and
11777 the matching SYN/ACK packet in return. The value "-1" means that the
11778 connection never established.
11779
11780 - Tr: server response time (HTTP mode only). It's the time elapsed between
11781 the moment the TCP connection was established to the server and the moment
11782 the server sent its complete response headers. It purely shows its request
11783 processing time, without the network overhead due to the data transmission.
11784 It is worth noting that when the client has data to send to the server, for
11785 instance during a POST request, the time already runs, and this can distort
11786 apparent response time. For this reason, it's generally wise not to trust
11787 too much this field for POST requests initiated from clients behind an
11788 untrusted network. A value of "-1" here means that the last the response
11789 header (empty line) was never seen, most likely because the server timeout
11790 stroke before the server managed to process the request.
11791
11792 - Tt: total session duration time, between the moment the proxy accepted it
11793 and the moment both ends were closed. The exception is when the "logasap"
11794 option is specified. In this case, it only equals (Tq+Tw+Tc+Tr), and is
11795 prefixed with a '+' sign. From this field, we can deduce "Td", the data
11796 transmission time, by substracting other timers when valid :
11797
11798 Td = Tt - (Tq + Tw + Tc + Tr)
11799
11800 Timers with "-1" values have to be excluded from this equation. In TCP
11801 mode, "Tq" and "Tr" have to be excluded too. Note that "Tt" can never be
11802 negative.
11803
11804These timers provide precious indications on trouble causes. Since the TCP
11805protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
11806that timers close to multiples of 3s are nearly always related to lost packets
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011807due to network problems (wires, negotiation, congestion). Moreover, if "Tt" is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011808close to a timeout value specified in the configuration, it often means that a
11809session has been aborted on timeout.
11810
11811Most common cases :
11812
11813 - If "Tq" is close to 3000, a packet has probably been lost between the
11814 client and the proxy. This is very rare on local networks but might happen
11815 when clients are on far remote networks and send large requests. It may
11816 happen that values larger than usual appear here without any network cause.
11817 Sometimes, during an attack or just after a resource starvation has ended,
11818 haproxy may accept thousands of connections in a few milliseconds. The time
11819 spent accepting these connections will inevitably slightly delay processing
11820 of other connections, and it can happen that request times in the order of
11821 a few tens of milliseconds are measured after a few thousands of new
Patrick Mezard105faca2010-06-12 17:02:46 +020011822 connections have been accepted at once. Setting "option http-server-close"
11823 may display larger request times since "Tq" also measures the time spent
11824 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011825
11826 - If "Tc" is close to 3000, a packet has probably been lost between the
11827 server and the proxy during the server connection phase. This value should
11828 always be very low, such as 1 ms on local networks and less than a few tens
11829 of ms on remote networks.
11830
Willy Tarreau55165fe2009-05-10 12:02:55 +020011831 - If "Tr" is nearly always lower than 3000 except some rare values which seem
11832 to be the average majored by 3000, there are probably some packets lost
11833 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011834
11835 - If "Tt" is large even for small byte counts, it generally is because
11836 neither the client nor the server decides to close the connection, for
11837 instance because both have agreed on a keep-alive connection mode. In order
11838 to solve this issue, it will be needed to specify "option httpclose" on
11839 either the frontend or the backend. If the problem persists, it means that
11840 the server ignores the "close" connection mode and expects the client to
11841 close. Then it will be required to use "option forceclose". Having the
11842 smallest possible 'Tt' is important when connection regulation is used with
11843 the "maxconn" option on the servers, since no new connection will be sent
11844 to the server until another one is released.
11845
11846Other noticeable HTTP log cases ('xx' means any value to be ignored) :
11847
11848 Tq/Tw/Tc/Tr/+Tt The "option logasap" is present on the frontend and the log
11849 was emitted before the data phase. All the timers are valid
11850 except "Tt" which is shorter than reality.
11851
11852 -1/xx/xx/xx/Tt The client was not able to send a complete request in time
11853 or it aborted too early. Check the session termination flags
11854 then "timeout http-request" and "timeout client" settings.
11855
11856 Tq/-1/xx/xx/Tt It was not possible to process the request, maybe because
11857 servers were out of order, because the request was invalid
11858 or forbidden by ACL rules. Check the session termination
11859 flags.
11860
11861 Tq/Tw/-1/xx/Tt The connection could not establish on the server. Either it
11862 actively refused it or it timed out after Tt-(Tq+Tw) ms.
11863 Check the session termination flags, then check the
11864 "timeout connect" setting. Note that the tarpit action might
11865 return similar-looking patterns, with "Tw" equal to the time
11866 the client connection was maintained open.
11867
11868 Tq/Tw/Tc/-1/Tt The server has accepted the connection but did not return
11869 a complete response in time, or it closed its connexion
11870 unexpectedly after Tt-(Tq+Tw+Tc) ms. Check the session
11871 termination flags, then check the "timeout server" setting.
11872
11873
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200118748.5. Session state at disconnection
11875-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011876
11877TCP and HTTP logs provide a session termination indicator in the
11878"termination_state" field, just before the number of active connections. It is
118792-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
11880each of which has a special meaning :
11881
11882 - On the first character, a code reporting the first event which caused the
11883 session to terminate :
11884
11885 C : the TCP session was unexpectedly aborted by the client.
11886
11887 S : the TCP session was unexpectedly aborted by the server, or the
11888 server explicitly refused it.
11889
11890 P : the session was prematurely aborted by the proxy, because of a
11891 connection limit enforcement, because a DENY filter was matched,
11892 because of a security check which detected and blocked a dangerous
11893 error in server response which might have caused information leak
Willy Tarreau570f2212013-06-10 16:42:09 +020011894 (eg: cacheable cookie).
11895
11896 L : the session was locally processed by haproxy and was not passed to
11897 a server. This is what happens for stats and redirects.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011898
11899 R : a resource on the proxy has been exhausted (memory, sockets, source
11900 ports, ...). Usually, this appears during the connection phase, and
11901 system logs should contain a copy of the precise error. If this
11902 happens, it must be considered as a very serious anomaly which
11903 should be fixed as soon as possible by any means.
11904
11905 I : an internal error was identified by the proxy during a self-check.
11906 This should NEVER happen, and you are encouraged to report any log
11907 containing this, because this would almost certainly be a bug. It
11908 would be wise to preventively restart the process after such an
11909 event too, in case it would be caused by memory corruption.
11910
Simon Horman752dc4a2011-06-21 14:34:59 +090011911 D : the session was killed by haproxy because the server was detected
11912 as down and was configured to kill all connections when going down.
11913
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070011914 U : the session was killed by haproxy on this backup server because an
11915 active server was detected as up and was configured to kill all
11916 backup connections when going up.
11917
Willy Tarreaua2a64e92011-09-07 23:01:56 +020011918 K : the session was actively killed by an admin operating on haproxy.
11919
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011920 c : the client-side timeout expired while waiting for the client to
11921 send or receive data.
11922
11923 s : the server-side timeout expired while waiting for the server to
11924 send or receive data.
11925
11926 - : normal session completion, both the client and the server closed
11927 with nothing left in the buffers.
11928
11929 - on the second character, the TCP or HTTP session state when it was closed :
11930
Willy Tarreauf7b30a92010-12-06 22:59:17 +010011931 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011932 (HTTP mode only). Nothing was sent to any server.
11933
11934 Q : the proxy was waiting in the QUEUE for a connection slot. This can
11935 only happen when servers have a 'maxconn' parameter set. It can
11936 also happen in the global queue after a redispatch consecutive to
11937 a failed attempt to connect to a dying server. If no redispatch is
11938 reported, then no connection attempt was made to any server.
11939
11940 C : the proxy was waiting for the CONNECTION to establish on the
11941 server. The server might at most have noticed a connection attempt.
11942
11943 H : the proxy was waiting for complete, valid response HEADERS from the
11944 server (HTTP only).
11945
11946 D : the session was in the DATA phase.
11947
11948 L : the proxy was still transmitting LAST data to the client while the
11949 server had already finished. This one is very rare as it can only
11950 happen when the client dies while receiving the last packets.
11951
11952 T : the request was tarpitted. It has been held open with the client
11953 during the whole "timeout tarpit" duration or until the client
11954 closed, both of which will be reported in the "Tw" timer.
11955
11956 - : normal session completion after end of data transfer.
11957
11958 - the third character tells whether the persistence cookie was provided by
11959 the client (only in HTTP mode) :
11960
11961 N : the client provided NO cookie. This is usually the case for new
11962 visitors, so counting the number of occurrences of this flag in the
11963 logs generally indicate a valid trend for the site frequentation.
11964
11965 I : the client provided an INVALID cookie matching no known server.
11966 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +020011967 cookies between HTTP/HTTPS sites, persistence conditionally
11968 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011969
11970 D : the client provided a cookie designating a server which was DOWN,
11971 so either "option persist" was used and the client was sent to
11972 this server, or it was not set and the client was redispatched to
11973 another server.
11974
Willy Tarreau996a92c2010-10-13 19:30:47 +020011975 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011976 server.
11977
Willy Tarreau996a92c2010-10-13 19:30:47 +020011978 E : the client provided a valid cookie, but with a last date which was
11979 older than what is allowed by the "maxidle" cookie parameter, so
11980 the cookie is consider EXPIRED and is ignored. The request will be
11981 redispatched just as if there was no cookie.
11982
11983 O : the client provided a valid cookie, but with a first date which was
11984 older than what is allowed by the "maxlife" cookie parameter, so
11985 the cookie is consider too OLD and is ignored. The request will be
11986 redispatched just as if there was no cookie.
11987
Willy Tarreauc89ccb62012-04-05 21:18:22 +020011988 U : a cookie was present but was not used to select the server because
11989 some other server selection mechanism was used instead (typically a
11990 "use-server" rule).
11991
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011992 - : does not apply (no cookie set in configuration).
11993
11994 - the last character reports what operations were performed on the persistence
11995 cookie returned by the server (only in HTTP mode) :
11996
11997 N : NO cookie was provided by the server, and none was inserted either.
11998
11999 I : no cookie was provided by the server, and the proxy INSERTED one.
12000 Note that in "cookie insert" mode, if the server provides a cookie,
12001 it will still be overwritten and reported as "I" here.
12002
Willy Tarreau996a92c2010-10-13 19:30:47 +020012003 U : the proxy UPDATED the last date in the cookie that was presented by
12004 the client. This can only happen in insert mode with "maxidle". It
12005 happens everytime there is activity at a different date than the
12006 date indicated in the cookie. If any other change happens, such as
12007 a redispatch, then the cookie will be marked as inserted instead.
12008
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012009 P : a cookie was PROVIDED by the server and transmitted as-is.
12010
12011 R : the cookie provided by the server was REWRITTEN by the proxy, which
12012 happens in "cookie rewrite" or "cookie prefix" modes.
12013
12014 D : the cookie provided by the server was DELETED by the proxy.
12015
12016 - : does not apply (no cookie set in configuration).
12017
Willy Tarreau996a92c2010-10-13 19:30:47 +020012018The combination of the two first flags gives a lot of information about what
12019was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012020helpful to detect server saturation, network troubles, local system resource
12021starvation, attacks, etc...
12022
12023The most common termination flags combinations are indicated below. They are
12024alphabetically sorted, with the lowercase set just after the upper case for
12025easier finding and understanding.
12026
12027 Flags Reason
12028
12029 -- Normal termination.
12030
12031 CC The client aborted before the connection could be established to the
12032 server. This can happen when haproxy tries to connect to a recently
12033 dead (or unchecked) server, and the client aborts while haproxy is
12034 waiting for the server to respond or for "timeout connect" to expire.
12035
12036 CD The client unexpectedly aborted during data transfer. This can be
12037 caused by a browser crash, by an intermediate equipment between the
12038 client and haproxy which decided to actively break the connection,
12039 by network routing issues between the client and haproxy, or by a
12040 keep-alive session between the server and the client terminated first
12041 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +010012042
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012043 cD The client did not send nor acknowledge any data for as long as the
12044 "timeout client" delay. This is often caused by network failures on
Cyril Bontédc4d9032012-04-08 21:57:39 +020012045 the client side, or the client simply leaving the net uncleanly.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012046
12047 CH The client aborted while waiting for the server to start responding.
12048 It might be the server taking too long to respond or the client
12049 clicking the 'Stop' button too fast.
12050
12051 cH The "timeout client" stroke while waiting for client data during a
12052 POST request. This is sometimes caused by too large TCP MSS values
12053 for PPPoE networks which cannot transport full-sized packets. It can
12054 also happen when client timeout is smaller than server timeout and
12055 the server takes too long to respond.
12056
12057 CQ The client aborted while its session was queued, waiting for a server
12058 with enough empty slots to accept it. It might be that either all the
12059 servers were saturated or that the assigned server was taking too
12060 long a time to respond.
12061
12062 CR The client aborted before sending a full HTTP request. Most likely
12063 the request was typed by hand using a telnet client, and aborted
12064 too early. The HTTP status code is likely a 400 here. Sometimes this
12065 might also be caused by an IDS killing the connection between haproxy
12066 and the client.
12067
12068 cR The "timeout http-request" stroke before the client sent a full HTTP
12069 request. This is sometimes caused by too large TCP MSS values on the
12070 client side for PPPoE networks which cannot transport full-sized
12071 packets, or by clients sending requests by hand and not typing fast
12072 enough, or forgetting to enter the empty line at the end of the
12073 request. The HTTP status code is likely a 408 here.
12074
12075 CT The client aborted while its session was tarpitted. It is important to
12076 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +020012077 wrong tarpit rules have been written. If a lot of them happen, it
12078 might make sense to lower the "timeout tarpit" value to something
12079 closer to the average reported "Tw" timer, in order not to consume
12080 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012081
Willy Tarreau570f2212013-06-10 16:42:09 +020012082 LR The request was intercepted and locally handled by haproxy. Generally
12083 it means that this was a redirect or a stats request.
12084
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012085 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012086 the TCP connection (the proxy received a TCP RST or an ICMP message
12087 in return). Under some circumstances, it can also be the network
12088 stack telling the proxy that the server is unreachable (eg: no route,
12089 or no ARP response on local network). When this happens in HTTP mode,
12090 the status code is likely a 502 or 503 here.
12091
12092 sC The "timeout connect" stroke before a connection to the server could
12093 complete. When this happens in HTTP mode, the status code is likely a
12094 503 or 504 here.
12095
12096 SD The connection to the server died with an error during the data
12097 transfer. This usually means that haproxy has received an RST from
12098 the server or an ICMP message from an intermediate equipment while
12099 exchanging data with the server. This can be caused by a server crash
12100 or by a network issue on an intermediate equipment.
12101
12102 sD The server did not send nor acknowledge any data for as long as the
12103 "timeout server" setting during the data phase. This is often caused
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012104 by too short timeouts on L4 equipments before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012105 load-balancers, ...), as well as keep-alive sessions maintained
12106 between the client and the server expiring first on haproxy.
12107
12108 SH The server aborted before sending its full HTTP response headers, or
12109 it crashed while processing the request. Since a server aborting at
12110 this moment is very rare, it would be wise to inspect its logs to
12111 control whether it crashed and why. The logged request may indicate a
12112 small set of faulty requests, demonstrating bugs in the application.
12113 Sometimes this might also be caused by an IDS killing the connection
12114 between haproxy and the server.
12115
12116 sH The "timeout server" stroke before the server could return its
12117 response headers. This is the most common anomaly, indicating too
12118 long transactions, probably caused by server or database saturation.
12119 The immediate workaround consists in increasing the "timeout server"
12120 setting, but it is important to keep in mind that the user experience
12121 will suffer from these long response times. The only long term
12122 solution is to fix the application.
12123
12124 sQ The session spent too much time in queue and has been expired. See
12125 the "timeout queue" and "timeout connect" settings to find out how to
12126 fix this if it happens too often. If it often happens massively in
12127 short periods, it may indicate general problems on the affected
12128 servers due to I/O or database congestion, or saturation caused by
12129 external attacks.
12130
12131 PC The proxy refused to establish a connection to the server because the
12132 process' socket limit has been reached while attempting to connect.
Cyril Bontédc4d9032012-04-08 21:57:39 +020012133 The global "maxconn" parameter may be increased in the configuration
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012134 so that it does not happen anymore. This status is very rare and
12135 might happen when the global "ulimit-n" parameter is forced by hand.
12136
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010012137 PD The proxy blocked an incorrectly formatted chunked encoded message in
12138 a request or a response, after the server has emitted its headers. In
12139 most cases, this will indicate an invalid message from the server to
Willy Tarreauf3a3e132013-08-31 08:16:26 +020012140 the client. Haproxy supports chunk sizes of up to 2GB - 1 (2147483647
12141 bytes). Any larger size will be considered as an error.
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010012142
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012143 PH The proxy blocked the server's response, because it was invalid,
12144 incomplete, dangerous (cache control), or matched a security filter.
12145 In any case, an HTTP 502 error is sent to the client. One possible
12146 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010012147 containing unauthorized characters. It is also possible but quite
12148 rare, that the proxy blocked a chunked-encoding request from the
12149 client due to an invalid syntax, before the server responded. In this
12150 case, an HTTP 400 error is sent to the client and reported in the
12151 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012152
12153 PR The proxy blocked the client's HTTP request, either because of an
12154 invalid HTTP syntax, in which case it returned an HTTP 400 error to
12155 the client, or because a deny filter matched, in which case it
12156 returned an HTTP 403 error.
12157
12158 PT The proxy blocked the client's request and has tarpitted its
12159 connection before returning it a 500 server error. Nothing was sent
12160 to the server. The connection was maintained open for as long as
12161 reported by the "Tw" timer field.
12162
12163 RC A local resource has been exhausted (memory, sockets, source ports)
12164 preventing the connection to the server from establishing. The error
12165 logs will tell precisely what was missing. This is very rare and can
12166 only be solved by proper system tuning.
12167
Willy Tarreau996a92c2010-10-13 19:30:47 +020012168The combination of the two last flags gives a lot of information about how
12169persistence was handled by the client, the server and by haproxy. This is very
12170important to troubleshoot disconnections, when users complain they have to
12171re-authenticate. The commonly encountered flags are :
12172
12173 -- Persistence cookie is not enabled.
12174
12175 NN No cookie was provided by the client, none was inserted in the
12176 response. For instance, this can be in insert mode with "postonly"
12177 set on a GET request.
12178
12179 II A cookie designating an invalid server was provided by the client,
12180 a valid one was inserted in the response. This typically happens when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040012181 a "server" entry is removed from the configuration, since its cookie
Willy Tarreau996a92c2010-10-13 19:30:47 +020012182 value can be presented by a client when no other server knows it.
12183
12184 NI No cookie was provided by the client, one was inserted in the
12185 response. This typically happens for first requests from every user
12186 in "insert" mode, which makes it an easy way to count real users.
12187
12188 VN A cookie was provided by the client, none was inserted in the
12189 response. This happens for most responses for which the client has
12190 already got a cookie.
12191
12192 VU A cookie was provided by the client, with a last visit date which is
12193 not completely up-to-date, so an updated cookie was provided in
12194 response. This can also happen if there was no date at all, or if
12195 there was a date but the "maxidle" parameter was not set, so that the
12196 cookie can be switched to unlimited time.
12197
12198 EI A cookie was provided by the client, with a last visit date which is
12199 too old for the "maxidle" parameter, so the cookie was ignored and a
12200 new cookie was inserted in the response.
12201
12202 OI A cookie was provided by the client, with a first visit date which is
12203 too old for the "maxlife" parameter, so the cookie was ignored and a
12204 new cookie was inserted in the response.
12205
12206 DI The server designated by the cookie was down, a new server was
12207 selected and a new cookie was emitted in the response.
12208
12209 VI The server designated by the cookie was not marked dead but could not
12210 be reached. A redispatch happened and selected another one, which was
12211 then advertised in the response.
12212
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012213
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200122148.6. Non-printable characters
12215-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012216
12217In order not to cause trouble to log analysis tools or terminals during log
12218consulting, non-printable characters are not sent as-is into log files, but are
12219converted to the two-digits hexadecimal representation of their ASCII code,
12220prefixed by the character '#'. The only characters that can be logged without
12221being escaped are comprised between 32 and 126 (inclusive). Obviously, the
12222escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
12223is the same for the character '"' which becomes "#22", as well as '{', '|' and
12224'}' when logging headers.
12225
12226Note that the space character (' ') is not encoded in headers, which can cause
12227issues for tools relying on space count to locate fields. A typical header
12228containing spaces is "User-Agent".
12229
12230Last, it has been observed that some syslog daemons such as syslog-ng escape
12231the quote ('"') with a backslash ('\'). The reverse operation can safely be
12232performed since no quote may appear anywhere else in the logs.
12233
12234
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200122358.7. Capturing HTTP cookies
12236---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012237
12238Cookie capture simplifies the tracking a complete user session. This can be
12239achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012240section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012241cookie will simultaneously be checked in the request ("Cookie:" header) and in
12242the response ("Set-Cookie:" header). The respective values will be reported in
12243the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012244locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012245not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
12246user switches to a new session for example, because the server will reassign it
12247a new cookie. It is also possible to detect if a server unexpectedly sets a
12248wrong cookie to a client, leading to session crossing.
12249
12250 Examples :
12251 # capture the first cookie whose name starts with "ASPSESSION"
12252 capture cookie ASPSESSION len 32
12253
12254 # capture the first cookie whose name is exactly "vgnvisitor"
12255 capture cookie vgnvisitor= len 32
12256
12257
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200122588.8. Capturing HTTP headers
12259---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012260
12261Header captures are useful to track unique request identifiers set by an upper
12262proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
12263the response, one can search for information about the response length, how the
12264server asked the cache to behave, or an object location during a redirection.
12265
12266Header captures are performed using the "capture request header" and "capture
12267response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012268section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012269
12270It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012271time. Non-existent headers are logged as empty strings, and if one header
12272appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012273are grouped within braces '{' and '}' in the same order as they were declared,
12274and delimited with a vertical bar '|' without any space. Response headers
12275follow the same representation, but are displayed after a space following the
12276request headers block. These blocks are displayed just before the HTTP request
12277in the logs.
12278
12279 Example :
12280 # This instance chains to the outgoing proxy
12281 listen proxy-out
12282 mode http
12283 option httplog
12284 option logasap
12285 log global
12286 server cache1 192.168.1.1:3128
12287
12288 # log the name of the virtual server
12289 capture request header Host len 20
12290
12291 # log the amount of data uploaded during a POST
12292 capture request header Content-Length len 10
12293
12294 # log the beginning of the referrer
12295 capture request header Referer len 20
12296
12297 # server name (useful for outgoing proxies only)
12298 capture response header Server len 20
12299
12300 # logging the content-length is useful with "option logasap"
12301 capture response header Content-Length len 10
12302
12303 # log the expected cache behaviour on the response
12304 capture response header Cache-Control len 8
12305
12306 # the Via header will report the next proxy's name
12307 capture response header Via len 20
12308
12309 # log the URL location during a redirection
12310 capture response header Location len 20
12311
12312 >>> Aug 9 20:26:09 localhost \
12313 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
12314 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
12315 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
12316 "GET http://fr.adserver.yahoo.com/"
12317
12318 >>> Aug 9 20:30:46 localhost \
12319 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
12320 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
12321 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010012322 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012323
12324 >>> Aug 9 20:30:46 localhost \
12325 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
12326 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
12327 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
12328 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010012329 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012330
12331
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200123328.9. Examples of logs
12333---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012334
12335These are real-world examples of logs accompanied with an explanation. Some of
12336them have been made up by hand. The syslog part has been removed for better
12337reading. Their sole purpose is to explain how to decipher them.
12338
12339 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
12340 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
12341 "HEAD / HTTP/1.0"
12342
12343 => long request (6.5s) entered by hand through 'telnet'. The server replied
12344 in 147 ms, and the session ended normally ('----')
12345
12346 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
12347 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
12348 0/9 "HEAD / HTTP/1.0"
12349
12350 => Idem, but the request was queued in the global queue behind 9 other
12351 requests, and waited there for 1230 ms.
12352
12353 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
12354 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
12355 "GET /image.iso HTTP/1.0"
12356
12357 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012358 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012359 14 ms, 243 bytes of headers were sent to the client, and total time from
12360 accept to first data byte is 30 ms.
12361
12362 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
12363 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
12364 "GET /cgi-bin/bug.cgi? HTTP/1.0"
12365
12366 => the proxy blocked a server response either because of an "rspdeny" or
12367 "rspideny" filter, or because the response was improperly formatted and
Willy Tarreau3c92c5f2011-08-28 09:45:47 +020012368 not HTTP-compliant, or because it blocked sensitive information which
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012369 risked being cached. In this case, the response is replaced with a "502
12370 bad gateway". The flags ("PH--") tell us that it was haproxy who decided
12371 to return the 502 and not the server.
12372
12373 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +010012374 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 +010012375
12376 => the client never completed its request and aborted itself ("C---") after
12377 8.5s, while the proxy was waiting for the request headers ("-R--").
12378 Nothing was sent to any server.
12379
12380 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
12381 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
12382
12383 => The client never completed its request, which was aborted by the
12384 time-out ("c---") after 50s, while the proxy was waiting for the request
12385 headers ("-R--"). Nothing was sent to any server, but the proxy could
12386 send a 408 return code to the client.
12387
12388 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
12389 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
12390
12391 => This log was produced with "option tcplog". The client timed out after
12392 5 seconds ("c----").
12393
12394 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
12395 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +010012396 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012397
12398 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012399 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +010012400 (config says 'retries 3'), and no redispatch (otherwise we would have
12401 seen "/+3"). Status code 503 was returned to the client. There were 115
12402 connections on this server, 202 connections on this proxy, and 205 on
12403 the global process. It is possible that the server refused the
12404 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +010012405
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010012406
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200124079. Statistics and monitoring
12408----------------------------
12409
12410It is possible to query HAProxy about its status. The most commonly used
12411mechanism is the HTTP statistics page. This page also exposes an alternative
12412CSV output format for monitoring tools. The same format is provided on the
12413Unix socket.
12414
12415
124169.1. CSV format
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010012417---------------
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010012418
Willy Tarreau7f062c42009-03-05 18:43:00 +010012419The statistics may be consulted either from the unix socket or from the HTTP
12420page. Both means provide a CSV format whose fields follow.
12421
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010012422 0. pxname: proxy name
12423 1. svname: service name (FRONTEND for frontend, BACKEND for backend, any name
12424 for server)
12425 2. qcur: current queued requests
12426 3. qmax: max queued requests
12427 4. scur: current sessions
12428 5. smax: max sessions
12429 6. slim: sessions limit
12430 7. stot: total sessions
12431 8. bin: bytes in
12432 9. bout: bytes out
12433 10. dreq: denied requests
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010012434 11. dresp: denied responses
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010012435 12. ereq: request errors
12436 13. econ: connection errors
Willy Tarreauae526782010-03-04 20:34:23 +010012437 14. eresp: response errors (among which srv_abrt)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010012438 15. wretr: retries (warning)
12439 16. wredis: redispatches (warning)
Cyril Bonté0dae5852010-02-03 00:26:28 +010012440 17. status: status (UP/DOWN/NOLB/MAINT/MAINT(via)...)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010012441 18. weight: server weight (server), total weight (backend)
12442 19. act: server is active (server), number of active servers (backend)
12443 20. bck: server is backup (server), number of backup servers (backend)
12444 21. chkfail: number of failed checks
12445 22. chkdown: number of UP->DOWN transitions
12446 23. lastchg: last status change (in seconds)
12447 24. downtime: total downtime (in seconds)
12448 25. qlimit: queue limit
12449 26. pid: process id (0 for first instance, 1 for second, ...)
12450 27. iid: unique proxy id
12451 28. sid: service id (unique inside a proxy)
12452 29. throttle: warm up status
12453 30. lbtot: total number of times a server was selected
12454 31. tracked: id of proxy/server if tracking is enabled
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +020012455 32. type (0=frontend, 1=backend, 2=server, 3=socket)
Krzysztof Piotr Oledzkidb57c6b2009-08-31 21:23:27 +020012456 33. rate: number of sessions per second over last elapsed second
12457 34. rate_lim: limit on new sessions per second
12458 35. rate_max: max number of new sessions per second
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +020012459 36. check_status: status of last health check, one of:
Cyril Bontéf0c60612010-02-06 14:44:47 +010012460 UNK -> unknown
12461 INI -> initializing
12462 SOCKERR -> socket error
12463 L4OK -> check passed on layer 4, no upper layers testing enabled
12464 L4TMOUT -> layer 1-4 timeout
12465 L4CON -> layer 1-4 connection problem, for example
12466 "Connection refused" (tcp rst) or "No route to host" (icmp)
12467 L6OK -> check passed on layer 6
12468 L6TOUT -> layer 6 (SSL) timeout
12469 L6RSP -> layer 6 invalid response - protocol error
12470 L7OK -> check passed on layer 7
12471 L7OKC -> check conditionally passed on layer 7, for example 404 with
12472 disable-on-404
12473 L7TOUT -> layer 7 (HTTP/SMTP) timeout
12474 L7RSP -> layer 7 invalid response - protocol error
12475 L7STS -> layer 7 response error, for example HTTP 5xx
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +020012476 37. check_code: layer5-7 code, if available
12477 38. check_duration: time in ms took to finish last health check
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012478 39. hrsp_1xx: http responses with 1xx code
12479 40. hrsp_2xx: http responses with 2xx code
12480 41. hrsp_3xx: http responses with 3xx code
12481 42. hrsp_4xx: http responses with 4xx code
12482 43. hrsp_5xx: http responses with 5xx code
12483 44. hrsp_other: http responses with other codes (protocol error)
Willy Tarreaud63335a2010-02-26 12:56:52 +010012484 45. hanafail: failed health checks details
12485 46. req_rate: HTTP requests per second over last elapsed second
12486 47. req_rate_max: max number of HTTP requests per second observed
12487 48. req_tot: total number of HTTP requests received
Willy Tarreauae526782010-03-04 20:34:23 +010012488 49. cli_abrt: number of data transfers aborted by the client
12489 50. srv_abrt: number of data transfers aborted by the server (inc. in eresp)
Willy Tarreau55058a72012-11-21 08:27:21 +010012490 51. comp_in: number of HTTP response bytes fed to the compressor
12491 52. comp_out: number of HTTP response bytes emitted by the compressor
12492 53. comp_byp: number of bytes that bypassed the HTTP compressor (CPU/BW limit)
Willy Tarreau11d4ec82012-11-26 00:49:03 +010012493 54. comp_rsp: number of HTTP responses that were compressed
Willy Tarreau844e3c52008-01-11 16:28:18 +010012494
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010012495
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200124969.2. Unix Socket commands
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010012497-------------------------
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010012498
Willy Tarreau468f4932013-08-01 16:50:16 +020012499The stats socket is not enabled by default. In order to enable it, it is
12500necessary to add one line in the global section of the haproxy configuration.
12501A second line is recommended to set a larger timeout, always appreciated when
12502issuing commands by hand :
12503
12504 global
12505 stats socket /var/run/haproxy.sock mode 600 level admin
12506 stats timeout 2m
12507
12508It is also possible to add multiple instances of the stats socket by repeating
12509the line, and make them listen to a TCP port instead of a UNIX socket. This is
12510never done by default because this is dangerous, but can be handy in some
12511situations :
12512
12513 global
12514 stats socket /var/run/haproxy.sock mode 600 level admin
12515 stats socket ipv4@192.168.0.1:9999 level admin
12516 stats timeout 2m
12517
12518To access the socket, an external utility such as "socat" is required. Socat is a
12519swiss-army knife to connect anything to anything. We use it to connect terminals
12520to the socket, or a couple of stdin/stdout pipes to it for scripts. The two main
12521syntaxes we'll use are the following :
12522
12523 # socat /var/run/haproxy.sock stdio
12524 # socat /var/run/haproxy.sock readline
12525
12526The first one is used with scripts. It is possible to send the output of a
12527script to haproxy, and pass haproxy's output to another script. That's useful
12528for retrieving counters or attack traces for example.
12529
12530The second one is only useful for issuing commands by hand. It has the benefit
12531that the terminal is handled by the readline library which supports line
12532editing and history, which is very convenient when issuing repeated commands
12533(eg: watch a counter).
12534
12535The socket supports two operation modes :
12536 - interactive
12537 - non-interactive
12538
12539The non-interactive mode is the default when socat connects to the socket. In
12540this mode, a single line may be sent. It is processed as a whole, responses are
12541sent back, and the connection closes after the end of the response. This is the
12542mode that scripts and monitoring tools use. It is possible to send multiple
12543commands in this mode, they need to be delimited by a semi-colon (';'). For
12544example :
12545
12546 # echo "show info;show stat;show table" | socat /var/run/haproxy stdio
12547
12548The interactive mode displays a prompt ('>') and waits for commands to be
12549entered on the line, then processes them, and displays the prompt again to wait
12550for a new command. This mode is entered via the "prompt" command which must be
12551sent on the first line in non-interactive mode. The mode is a flip switch, if
12552"prompt" is sent in interactive mode, it is disabled and the connection closes
12553after processing the last command of the same line.
12554
12555For this reason, when debugging by hand, it's quite common to start with the
12556"prompt" command :
12557
12558 # socat /var/run/haproxy readline
12559 prompt
12560 > show info
12561 ...
12562 >
12563
12564Since multiple commands may be issued at once, haproxy uses the empty line as a
12565delimiter to mark an end of output for each command, and takes care of ensuring
12566that no command can emit an empty line on output. A script can thus easily
12567parse the output even when multiple commands were pipelined on a single line.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010012568
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012569It is important to understand that when multiple haproxy processes are started
12570on the same sockets, any process may pick up the request and will output its
12571own stats.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010012572
Willy Tarreau468f4932013-08-01 16:50:16 +020012573The list of commands currently supported on the stats socket is provided below.
12574If an unknown command is sent, haproxy displays the usage message which reminds
12575all supported commands. Some commands support a more complex syntax, generally
12576it will explain what part of the command is invalid when this happens.
12577
Thierry FOURNIERc0e0d7b2013-12-11 16:55:52 +010012578add map <map> <key> <value>
12579 Add an entry into the map <map> to associate the value <value> to the key
12580 <key>. This command does not verify if the entry already exists. It is
12581 mainly used to fill a map after a clear operation.
12582
Willy Tarreaud63335a2010-02-26 12:56:52 +010012583clear counters
12584 Clear the max values of the statistics counters in each proxy (frontend &
12585 backend) and in each server. The cumulated counters are not affected. This
12586 can be used to get clean counters after an incident, without having to
12587 restart nor to clear traffic counters. This command is restricted and can
12588 only be issued on sockets configured for levels "operator" or "admin".
12589
12590clear counters all
12591 Clear all statistics counters in each proxy (frontend & backend) and in each
12592 server. This has the same effect as restarting. This command is restricted
12593 and can only be issued on sockets configured for level "admin".
12594
Thierry FOURNIERc0e0d7b2013-12-11 16:55:52 +010012595clear map <map>
12596 Remove all entries from the map <map>.
12597
Simon Hormanc88b8872011-06-15 15:18:49 +090012598clear table <table> [ data.<type> <operator> <value> ] | [ key <key> ]
12599 Remove entries from the stick-table <table>.
12600
12601 This is typically used to unblock some users complaining they have been
12602 abusively denied access to a service, but this can also be used to clear some
12603 stickiness entries matching a server that is going to be replaced (see "show
12604 table" below for details). Note that sometimes, removal of an entry will be
12605 refused because it is currently tracked by a session. Retrying a few seconds
12606 later after the session ends is usual enough.
12607
12608 In the case where no options arguments are given all entries will be removed.
12609
12610 When the "data." form is used entries matching a filter applied using the
12611 stored data (see "stick-table" in section 4.2) are removed. A stored data
12612 type must be specified in <type>, and this data type must be stored in the
12613 table otherwise an error is reported. The data is compared according to
12614 <operator> with the 64-bit integer <value>. Operators are the same as with
12615 the ACLs :
12616
12617 - eq : match entries whose data is equal to this value
12618 - ne : match entries whose data is not equal to this value
12619 - le : match entries whose data is less than or equal to this value
12620 - ge : match entries whose data is greater than or equal to this value
12621 - lt : match entries whose data is less than this value
12622 - gt : match entries whose data is greater than this value
12623
12624 When the key form is used the entry <key> is removed. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +090012625 same type as the table, which currently is limited to IPv4, IPv6, integer and
12626 string.
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012627
12628 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020012629 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +020012630 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020012631 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
12632 bytes_out_rate(60000)=187
12633 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
12634 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012635
12636 $ echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1
12637
12638 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +020012639 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau62a36c42010-08-17 15:53:10 +020012640 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
12641 bytes_out_rate(60000)=191
Simon Hormanc88b8872011-06-15 15:18:49 +090012642 $ echo "clear table http_proxy data.gpc0 eq 1" | socat stdio /tmp/sock1
12643 $ echo "show table http_proxy" | socat stdio /tmp/sock1
12644 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012645
Thierry FOURNIER0b90f312014-01-29 20:40:18 +010012646del map <map> <key>
12647 Delete all the map entries from the map <map> corresponding to the key <key>.
12648
12649disable agent <backend>/<server>
Simon Horman671b6f02013-11-25 10:46:39 +090012650 Mark the auxiliary agent check as temporarily stopped.
12651
12652 In the case where an agent check is being run as a auxiliary check, due
12653 to the agent-check parameter of a server directive, new checks are only
12654 initialised when the agent is in the enabled. Thus, disable agent will
12655 prevent any new agent checks from begin initiated until the agent
12656 re-enabled using enable agent.
12657
12658 When an agent is disabled the processing of an auxiliary agent check that
12659 was initiated while the agent was set as enabled is as follows: All
12660 results that would alter the weight, specifically "drain" or a weight
12661 returned by the agent, are ignored. The processing of agent check is
12662 otherwise unchanged.
12663
12664 The motivation for this feature is to allow the weight changing effects
12665 of the agent checks to be paused to allow the weight of a server to be
12666 configured using set weight without being overridden by the agent.
12667
12668 This command is restricted and can only be issued on sockets configured for
12669 level "admin".
12670
Willy Tarreau532a4502011-09-07 22:37:44 +020012671disable frontend <frontend>
12672 Mark the frontend as temporarily stopped. This corresponds to the mode which
12673 is used during a soft restart : the frontend releases the port but can be
12674 enabled again if needed. This should be used with care as some non-Linux OSes
12675 are unable to enable it back. This is intended to be used in environments
12676 where stopping a proxy is not even imaginable but a misconfigured proxy must
12677 be fixed. That way it's possible to release the port and bind it into another
12678 process to restore operations. The frontend will appear with status "STOP"
12679 on the stats page.
12680
12681 The frontend may be specified either by its name or by its numeric ID,
12682 prefixed with a sharp ('#').
12683
12684 This command is restricted and can only be issued on sockets configured for
12685 level "admin".
12686
Willy Tarreaud63335a2010-02-26 12:56:52 +010012687disable server <backend>/<server>
12688 Mark the server DOWN for maintenance. In this mode, no more checks will be
12689 performed on the server until it leaves maintenance.
12690 If the server is tracked by other servers, those servers will be set to DOWN
12691 during the maintenance.
12692
12693 In the statistics page, a server DOWN for maintenance will appear with a
12694 "MAINT" status, its tracking servers with the "MAINT(via)" one.
12695
12696 Both the backend and the server may be specified either by their name or by
Willy Tarreauf5f31922011-08-02 11:32:07 +020012697 their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010012698
12699 This command is restricted and can only be issued on sockets configured for
12700 level "admin".
12701
Simon Horman671b6f02013-11-25 10:46:39 +090012702enable agent <backend>/<server>
12703 Resume auxiliary agent check that was temporarily stopped.
12704
12705 See "disable agent" for details of the effect of temporarily starting
12706 and stopping an auxiliary agent.
12707
12708 This command is restricted and can only be issued on sockets configured for
12709 level "admin".
12710
Willy Tarreau532a4502011-09-07 22:37:44 +020012711enable frontend <frontend>
12712 Resume a frontend which was temporarily stopped. It is possible that some of
12713 the listening ports won't be able to bind anymore (eg: if another process
12714 took them since the 'disable frontend' operation). If this happens, an error
12715 is displayed. Some operating systems might not be able to resume a frontend
12716 which was disabled.
12717
12718 The frontend may be specified either by its name or by its numeric ID,
12719 prefixed with a sharp ('#').
12720
12721 This command is restricted and can only be issued on sockets configured for
12722 level "admin".
12723
Willy Tarreaud63335a2010-02-26 12:56:52 +010012724enable server <backend>/<server>
12725 If the server was previously marked as DOWN for maintenance, this marks the
12726 server UP and checks are re-enabled.
12727
12728 Both the backend and the server may be specified either by their name or by
Willy Tarreauf5f31922011-08-02 11:32:07 +020012729 their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010012730
12731 This command is restricted and can only be issued on sockets configured for
12732 level "admin".
12733
12734get weight <backend>/<server>
12735 Report the current weight and the initial weight of server <server> in
12736 backend <backend> or an error if either doesn't exist. The initial weight is
12737 the one that appears in the configuration file. Both are normally equal
12738 unless the current weight has been changed. Both the backend and the server
12739 may be specified either by their name or by their numeric ID, prefixed with a
Willy Tarreauf5f31922011-08-02 11:32:07 +020012740 sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010012741
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012742help
12743 Print the list of known keywords and their basic usage. The same help screen
12744 is also displayed for unknown commands.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010012745
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012746prompt
12747 Toggle the prompt at the beginning of the line and enter or leave interactive
12748 mode. In interactive mode, the connection is not closed after a command
12749 completes. Instead, the prompt will appear again, indicating the user that
12750 the interpreter is waiting for a new command. The prompt consists in a right
12751 angle bracket followed by a space "> ". This mode is particularly convenient
12752 when one wants to periodically check information such as stats or errors.
12753 It is also a good idea to enter interactive mode before issuing a "help"
12754 command.
12755
12756quit
12757 Close the connection when in interactive mode.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010012758
Thierry FOURNIERc0e0d7b2013-12-11 16:55:52 +010012759set map <map> <key> <value>
12760 Modify the value corresponding to each key <key> in a map <map>. The new value
12761 is <value>.
12762
Willy Tarreau2a0f4d22011-08-02 11:49:05 +020012763set maxconn frontend <frontend> <value>
Willy Tarreau3c7a79d2012-09-26 21:07:15 +020012764 Dynamically change the specified frontend's maxconn setting. Any positive
12765 value is allowed including zero, but setting values larger than the global
12766 maxconn does not make much sense. If the limit is increased and connections
12767 were pending, they will immediately be accepted. If it is lowered to a value
12768 below the current number of connections, new connections acceptation will be
Willy Tarreau2a0f4d22011-08-02 11:49:05 +020012769 delayed until the threshold is reached. The frontend might be specified by
12770 either its name or its numeric ID prefixed with a sharp ('#').
12771
Willy Tarreau91886b62011-09-07 14:38:31 +020012772set maxconn global <maxconn>
12773 Dynamically change the global maxconn setting within the range defined by the
12774 initial global maxconn setting. If it is increased and connections were
12775 pending, they will immediately be accepted. If it is lowered to a value below
12776 the current number of connections, new connections acceptation will be
12777 delayed until the threshold is reached. A value of zero restores the initial
12778 setting.
12779
Willy Tarreauf5b22872011-09-07 16:13:44 +020012780set rate-limit connections global <value>
12781 Change the process-wide connection rate limit, which is set by the global
12782 'maxconnrate' setting. A value of zero disables the limitation. This limit
12783 applies to all frontends and the change has an immediate effect. The value
12784 is passed in number of connections per second.
12785
William Lallemandd85f9172012-11-09 17:05:39 +010012786set rate-limit http-compression global <value>
12787 Change the maximum input compression rate, which is set by the global
12788 'maxcomprate' setting. A value of zero disables the limitation. The value is
William Lallemand096f5542012-11-19 17:26:05 +010012789 passed in number of kilobytes per second. The value is available in the "show
12790 info" on the line "CompressBpsRateLim" in bytes.
William Lallemandd85f9172012-11-09 17:05:39 +010012791
Willy Tarreau93e7c002013-10-07 18:51:07 +020012792set rate-limit sessions global <value>
12793 Change the process-wide session rate limit, which is set by the global
12794 'maxsessrate' setting. A value of zero disables the limitation. This limit
12795 applies to all frontends and the change has an immediate effect. The value
12796 is passed in number of sessions per second.
12797
Willy Tarreaue43d5322013-10-07 20:01:52 +020012798set rate-limit ssl-sessions global <value>
12799 Change the process-wide SSL session rate limit, which is set by the global
12800 'maxsslrate' setting. A value of zero disables the limitation. This limit
12801 applies to all frontends and the change has an immediate effect. The value
12802 is passed in number of sessions per second sent to the SSL stack. It applies
12803 before the handshake in order to protect the stack against handshake abuses.
12804
Willy Tarreau47060b62013-08-01 21:11:42 +020012805set table <table> key <key> [data.<data_type> <value>]*
Willy Tarreau654694e2012-06-07 01:03:16 +020012806 Create or update a stick-table entry in the table. If the key is not present,
12807 an entry is inserted. See stick-table in section 4.2 to find all possible
12808 values for <data_type>. The most likely use consists in dynamically entering
12809 entries for source IP addresses, with a flag in gpc0 to dynamically block an
Willy Tarreau47060b62013-08-01 21:11:42 +020012810 IP address or affect its quality of service. It is possible to pass multiple
12811 data_types in a single call.
Willy Tarreau654694e2012-06-07 01:03:16 +020012812
Willy Tarreaud63335a2010-02-26 12:56:52 +010012813set timeout cli <delay>
12814 Change the CLI interface timeout for current connection. This can be useful
12815 during long debugging sessions where the user needs to constantly inspect
12816 some indicators without being disconnected. The delay is passed in seconds.
12817
12818set weight <backend>/<server> <weight>[%]
12819 Change a server's weight to the value passed in argument. If the value ends
12820 with the '%' sign, then the new weight will be relative to the initially
Simon Horman58b5d292013-02-12 10:45:52 +090012821 configured weight. Absolute weights are permitted between 0 and 256.
12822 Relative weights must be positive with the resulting absolute weight is
12823 capped at 256. Servers which are part of a farm running a static
12824 load-balancing algorithm have stricter limitations because the weight
12825 cannot change once set. Thus for these servers, the only accepted values
12826 are 0 and 100% (or 0 and the initial weight). Changes take effect
12827 immediately, though certain LB algorithms require a certain amount of
12828 requests to consider changes. A typical usage of this command is to
12829 disable a server during an update by setting its weight to zero, then to
12830 enable it again after the update by setting it back to 100%. This command
12831 is restricted and can only be issued on sockets configured for level
12832 "admin". Both the backend and the server may be specified either by their
12833 name or by their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010012834
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010012835show errors [<iid>]
12836 Dump last known request and response errors collected by frontends and
12837 backends. If <iid> is specified, the limit the dump to errors concerning
Willy Tarreau6162db22009-10-10 17:13:00 +020012838 either frontend or backend whose ID is <iid>. This command is restricted
12839 and can only be issued on sockets configured for levels "operator" or
12840 "admin".
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010012841
12842 The errors which may be collected are the last request and response errors
12843 caused by protocol violations, often due to invalid characters in header
12844 names. The report precisely indicates what exact character violated the
12845 protocol. Other important information such as the exact date the error was
12846 detected, frontend and backend names, the server name (when known), the
12847 internal session ID and the source address which has initiated the session
12848 are reported too.
12849
12850 All characters are returned, and non-printable characters are encoded. The
12851 most common ones (\t = 9, \n = 10, \r = 13 and \e = 27) are encoded as one
12852 letter following a backslash. The backslash itself is encoded as '\\' to
12853 avoid confusion. Other non-printable characters are encoded '\xNN' where
12854 NN is the two-digits hexadecimal representation of the character's ASCII
12855 code.
12856
12857 Lines are prefixed with the position of their first character, starting at 0
12858 for the beginning of the buffer. At most one input line is printed per line,
12859 and large lines will be broken into multiple consecutive output lines so that
12860 the output never goes beyond 79 characters wide. It is easy to detect if a
12861 line was broken, because it will not end with '\n' and the next line's offset
12862 will be followed by a '+' sign, indicating it is a continuation of previous
12863 line.
12864
12865 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020012866 $ echo "show errors" | socat stdio /tmp/sock1
12867 >>> [04/Mar/2009:15:46:56.081] backend http-in (#2) : invalid response
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010012868 src 127.0.0.1, session #54, frontend fe-eth0 (#1), server s2 (#1)
12869 response length 213 bytes, error at position 23:
12870
12871 00000 HTTP/1.0 200 OK\r\n
12872 00017 header/bizarre:blah\r\n
12873 00038 Location: blah\r\n
12874 00054 Long-line: this is a very long line which should b
12875 00104+ e broken into multiple lines on the output buffer,
12876 00154+ otherwise it would be too large to print in a ter
12877 00204+ minal\r\n
12878 00211 \r\n
12879
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012880 In the example above, we see that the backend "http-in" which has internal
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010012881 ID 2 has blocked an invalid response from its server s2 which has internal
12882 ID 1. The request was on session 54 initiated by source 127.0.0.1 and
12883 received by frontend fe-eth0 whose ID is 1. The total response length was
12884 213 bytes when the error was detected, and the error was at byte 23. This
12885 is the slash ('/') in header name "header/bizarre", which is not a valid
12886 HTTP character for a header name.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010012887
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012888show info
12889 Dump info about haproxy status on current process.
12890
Thierry FOURNIERc0e0d7b2013-12-11 16:55:52 +010012891show map [<map>]
12892 Dump info about map converters. Without argument, the list of all available
12893 maps is returned. If a <map> is specified, its contents are dumped.
12894
Willy Tarreau12833bb2014-01-28 16:49:56 +010012895show pools
12896 Dump the status of internal memory pools. This is useful to track memory
12897 usage when suspecting a memory leak for example. It does exactly the same
12898 as the SIGQUIT when running in foreground except that it does not flush
12899 the pools.
12900
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012901show sess
12902 Dump all known sessions. Avoid doing this on slow connections as this can
Willy Tarreau6162db22009-10-10 17:13:00 +020012903 be huge. This command is restricted and can only be issued on sockets
12904 configured for levels "operator" or "admin".
12905
Willy Tarreau66dc20a2010-03-05 17:53:32 +010012906show sess <id>
12907 Display a lot of internal information about the specified session identifier.
12908 This identifier is the first field at the beginning of the lines in the dumps
12909 of "show sess" (it corresponds to the session pointer). Those information are
12910 useless to most users but may be used by haproxy developers to troubleshoot a
12911 complex bug. The output format is intentionally not documented so that it can
Willy Tarreau76153662012-11-26 01:16:39 +010012912 freely evolve depending on demands. The special id "all" dumps the states of
12913 all sessions, which can be avoided as much as possible as it is highly CPU
12914 intensive and can take a lot of time.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012915
12916show stat [<iid> <type> <sid>]
12917 Dump statistics in the CSV format. By passing <id>, <type> and <sid>, it is
12918 possible to dump only selected items :
12919 - <iid> is a proxy ID, -1 to dump everything
12920 - <type> selects the type of dumpable objects : 1 for frontends, 2 for
12921 backends, 4 for servers, -1 for everything. These values can be ORed,
12922 for example:
12923 1 + 2 = 3 -> frontend + backend.
12924 1 + 2 + 4 = 7 -> frontend + backend + server.
12925 - <sid> is a server ID, -1 to dump everything from the selected proxy.
12926
12927 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020012928 $ echo "show info;show stat" | socat stdio unix-connect:/tmp/sock1
12929 >>> Name: HAProxy
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012930 Version: 1.4-dev2-49
12931 Release_date: 2009/09/23
12932 Nbproc: 1
12933 Process_num: 1
12934 (...)
12935
12936 # pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,dreq, (...)
12937 stats,FRONTEND,,,0,0,1000,0,0,0,0,0,0,,,,,OPEN,,,,,,,,,1,1,0, (...)
12938 stats,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,0,0,0,,0,250,(...)
12939 (...)
12940 www1,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,1,1,0,,0,250, (...)
12941
12942 $
12943
12944 Here, two commands have been issued at once. That way it's easy to find
12945 which process the stats apply to in multi-process mode. Notice the empty
12946 line after the information output which marks the end of the first block.
12947 A similar empty line appears at the end of the second block (stats) so that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012948 the reader knows the output has not been truncated.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012949
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012950show table
12951 Dump general information on all known stick-tables. Their name is returned
12952 (the name of the proxy which holds them), their type (currently zero, always
12953 IP), their size in maximum possible number of entries, and the number of
12954 entries currently in use.
12955
12956 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020012957 $ echo "show table" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090012958 >>> # table: front_pub, type: ip, size:204800, used:171454
12959 >>> # table: back_rdp, type: ip, size:204800, used:0
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012960
Simon Horman17bce342011-06-15 15:18:47 +090012961show table <name> [ data.<type> <operator> <value> ] | [ key <key> ]
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012962 Dump contents of stick-table <name>. In this mode, a first line of generic
12963 information about the table is reported as with "show table", then all
12964 entries are dumped. Since this can be quite heavy, it is possible to specify
Simon Horman17bce342011-06-15 15:18:47 +090012965 a filter in order to specify what entries to display.
12966
12967 When the "data." form is used the filter applies to the stored data (see
12968 "stick-table" in section 4.2). A stored data type must be specified
12969 in <type>, and this data type must be stored in the table otherwise an
12970 error is reported. The data is compared according to <operator> with the
12971 64-bit integer <value>. Operators are the same as with the ACLs :
12972
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012973 - eq : match entries whose data is equal to this value
12974 - ne : match entries whose data is not equal to this value
12975 - le : match entries whose data is less than or equal to this value
12976 - ge : match entries whose data is greater than or equal to this value
12977 - lt : match entries whose data is less than this value
12978 - gt : match entries whose data is greater than this value
12979
Simon Hormanc88b8872011-06-15 15:18:49 +090012980
12981 When the key form is used the entry <key> is shown. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +090012982 same type as the table, which currently is limited to IPv4, IPv6, integer,
12983 and string.
Simon Horman17bce342011-06-15 15:18:47 +090012984
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012985 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020012986 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090012987 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020012988 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
12989 bytes_out_rate(60000)=187
12990 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
12991 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012992
Willy Tarreau62a36c42010-08-17 15:53:10 +020012993 $ echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090012994 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020012995 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
12996 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012997
Willy Tarreau62a36c42010-08-17 15:53:10 +020012998 $ echo "show table http_proxy data.conn_rate gt 5" | \
12999 socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090013000 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020013001 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
13002 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020013003
Simon Horman17bce342011-06-15 15:18:47 +090013004 $ echo "show table http_proxy key 127.0.0.2" | \
13005 socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090013006 >>> # table: http_proxy, type: ip, size:204800, used:2
Simon Horman17bce342011-06-15 15:18:47 +090013007 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
13008 bytes_out_rate(60000)=191
13009
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020013010 When the data criterion applies to a dynamic value dependent on time such as
13011 a bytes rate, the value is dynamically computed during the evaluation of the
13012 entry in order to decide whether it has to be dumped or not. This means that
13013 such a filter could match for some time then not match anymore because as
13014 time goes, the average event rate drops.
13015
13016 It is possible to use this to extract lists of IP addresses abusing the
13017 service, in order to monitor them or even blacklist them in a firewall.
13018 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020013019 $ echo "show table http_proxy data.gpc0 gt 0" \
13020 | socat stdio /tmp/sock1 \
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020013021 | fgrep 'key=' | cut -d' ' -f2 | cut -d= -f2 > abusers-ip.txt
13022 ( or | awk '/key/{ print a[split($2,a,"=")]; }' )
Krzysztof Piotr Oledzki719e7262009-10-04 15:02:46 +020013023
Willy Tarreau532a4502011-09-07 22:37:44 +020013024shutdown frontend <frontend>
13025 Completely delete the specified frontend. All the ports it was bound to will
13026 be released. It will not be possible to enable the frontend anymore after
13027 this operation. This is intended to be used in environments where stopping a
13028 proxy is not even imaginable but a misconfigured proxy must be fixed. That
13029 way it's possible to release the port and bind it into another process to
13030 restore operations. The frontend will not appear at all on the stats page
13031 once it is terminated.
13032
13033 The frontend may be specified either by its name or by its numeric ID,
13034 prefixed with a sharp ('#').
13035
13036 This command is restricted and can only be issued on sockets configured for
13037 level "admin".
13038
Willy Tarreaua295edc2011-09-07 23:21:03 +020013039shutdown session <id>
13040 Immediately terminate the session matching the specified session identifier.
13041 This identifier is the first field at the beginning of the lines in the dumps
13042 of "show sess" (it corresponds to the session pointer). This can be used to
13043 terminate a long-running session without waiting for a timeout or when an
13044 endless transfer is ongoing. Such terminated sessions are reported with a 'K'
13045 flag in the logs.
13046
Willy Tarreau52b2d222011-09-07 23:48:48 +020013047shutdown sessions <backend>/<server>
13048 Immediately terminate all the sessions attached to the specified server. This
13049 can be used to terminate long-running sessions after a server is put into
13050 maintenance mode, for instance. Such terminated sessions are reported with a
13051 'K' flag in the logs.
13052
Willy Tarreau0ba27502007-12-24 16:55:16 +010013053/*
13054 * Local variables:
13055 * fill-column: 79
13056 * End:
13057 */