blob: f1a388e5f3c661648c1cce1bae90ecc386d5aab7 [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 Tarreau0cae4b32012-12-12 00:39:52 +01007 2012/12/12
Willy Tarreau6a06a402007-07-15 20:15:28 +02008
9
10This document covers the configuration language as implemented in the version
11specified above. It does not provide any hint, example or advice. For such
Willy Tarreau0ba27502007-12-24 16:55:16 +010012documentation, please refer to the Reference Manual or the Architecture Manual.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013The summary below is meant to help you search sections by name and navigate
14through the document.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016Note to documentation contributors :
Jamie Gloudonaaa21002012-08-25 00:18:33 -040017 This document is formatted with 80 columns per line, with even number of
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018 spaces for indentation and without tabs. Please follow these rules strictly
19 so that it remains easily printable everywhere. If a line needs to be
20 printed verbatim and does not fit, please end each line with a backslash
Willy Tarreau62a36c42010-08-17 15:53:10 +020021 ('\') and continue on next line, indented by two characters. It is also
22 sometimes useful to prefix all output lines (logs, console outs) with 3
23 closing angle brackets ('>>>') in order to help get the difference between
24 inputs and outputs when it can become ambiguous. If you add sections,
25 please update the summary below for easier searching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020026
27
28Summary
29-------
30
311. Quick reminder about HTTP
321.1. The HTTP transaction model
331.2. HTTP request
341.2.1. The Request line
351.2.2. The request headers
361.3. HTTP response
371.3.1. The Response line
381.3.2. The response headers
39
402. Configuring HAProxy
412.1. Configuration file format
422.2. Time format
Patrick Mezard35da19c2010-06-12 17:02:47 +0200432.3. Examples
Willy Tarreauc57f0e22009-05-10 13:12:33 +020044
453. Global parameters
463.1. Process management and security
473.2. Performance tuning
483.3. Debugging
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100493.4. Userlists
Cyril Bontédc4d9032012-04-08 21:57:39 +0200503.5. Peers
Willy Tarreauc57f0e22009-05-10 13:12:33 +020051
524. Proxies
534.1. Proxy keywords matrix
544.2. Alphabetically sorted keywords reference
55
Willy Tarreau086fbf52012-09-24 20:34:51 +0200565. Bind and Server options
575.1. Bind options
585.2. Server and default-server options
Willy Tarreauc57f0e22009-05-10 13:12:33 +020059
606. HTTP header manipulation
61
Cyril Bonté7d38afb2010-02-03 20:41:26 +0100627. Using ACLs and pattern extraction
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200637.1. Matching integers
647.2. Matching strings
657.3. Matching regular expressions (regexes)
Willy Tarreauceb4ac92012-04-28 00:41:46 +0200667.4. Matching IPv4 and IPv6 addresses
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200677.5. Available matching criteria
687.5.1. Matching at Layer 4 and below
697.5.2. Matching contents at Layer 4
707.5.3. Matching at Layer 7
717.6. Pre-defined ACLs
727.7. Using ACLs to form conditions
Cyril Bonté7d38afb2010-02-03 20:41:26 +0100737.8. Pattern extraction
Willy Tarreauc57f0e22009-05-10 13:12:33 +020074
758. Logging
768.1. Log levels
778.2. Log formats
788.2.1. Default log format
798.2.2. TCP log format
808.2.3. HTTP log format
William Lallemand48940402012-01-30 16:47:22 +0100818.2.4. Custom log format
Willy Tarreau5f51e1a2012-12-03 18:40:10 +0100828.2.5. Error log format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200838.3. Advanced logging options
848.3.1. Disabling logging of external tests
858.3.2. Logging before waiting for the session to terminate
868.3.3. Raising log level upon errors
878.3.4. Disabling logging of successful connections
888.4. Timing events
898.5. Session state at disconnection
908.6. Non-printable characters
918.7. Capturing HTTP cookies
928.8. Capturing HTTP headers
938.9. Examples of logs
94
959. Statistics and monitoring
969.1. CSV format
979.2. Unix Socket commands
98
99
1001. Quick reminder about HTTP
101----------------------------
102
103When haproxy is running in HTTP mode, both the request and the response are
104fully analyzed and indexed, thus it becomes possible to build matching criteria
105on almost anything found in the contents.
106
107However, it is important to understand how HTTP requests and responses are
108formed, and how HAProxy decomposes them. It will then become easier to write
109correct rules and to debug existing configurations.
110
111
1121.1. The HTTP transaction model
113-------------------------------
114
115The HTTP protocol is transaction-driven. This means that each request will lead
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100116to one and only one response. Traditionally, a TCP connection is established
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200117from the client to the server, a request is sent by the client on the
118connection, the server responds and the connection is closed. A new request
119will involve a new connection :
120
121 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
122
123In this mode, called the "HTTP close" mode, there are as many connection
124establishments as there are HTTP transactions. Since the connection is closed
125by the server after the response, the client does not need to know the content
126length.
127
128Due to the transactional nature of the protocol, it was possible to improve it
129to avoid closing a connection between two subsequent transactions. In this mode
130however, it is mandatory that the server indicates the content length for each
131response so that the client does not wait indefinitely. For this, a special
132header is used: "Content-length". This mode is called the "keep-alive" mode :
133
134 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
135
136Its advantages are a reduced latency between transactions, and less processing
137power required on the server side. It is generally better than the close mode,
138but not always because the clients often limit their concurrent connections to
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200139a smaller value.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200140
141A last improvement in the communications is the pipelining mode. It still uses
142keep-alive, but the client does not wait for the first response to send the
143second request. This is useful for fetching large number of images composing a
144page :
145
146 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
147
148This can obviously have a tremendous benefit on performance because the network
149latency is eliminated between subsequent requests. Many HTTP agents do not
150correctly support pipelining since there is no way to associate a response with
151the corresponding request in HTTP. For this reason, it is mandatory for the
Cyril Bonté78caf842010-03-10 22:41:43 +0100152server to reply in the exact same order as the requests were received.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200153
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200154By default HAProxy operates in a tunnel-like mode with regards to persistent
155connections: for each connection it processes the first request and forwards
156everything else (including additional requests) to selected server. Once
157established, the connection is persisted both on the client and server
158sides. Use "option http-server-close" to preserve client persistent connections
159while handling every incoming request individually, dispatching them one after
160another to servers, in HTTP close mode. Use "option httpclose" to switch both
161sides to HTTP close mode. "option forceclose" and "option
162http-pretend-keepalive" help working around servers misbehaving in HTTP close
163mode.
164
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200165
1661.2. HTTP request
167-----------------
168
169First, let's consider this HTTP request :
170
171 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100172 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200173 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
174 2 Host: www.mydomain.com
175 3 User-agent: my small browser
176 4 Accept: image/jpeg, image/gif
177 5 Accept: image/png
178
179
1801.2.1. The Request line
181-----------------------
182
183Line 1 is the "request line". It is always composed of 3 fields :
184
185 - a METHOD : GET
186 - a URI : /serv/login.php?lang=en&profile=2
187 - a version tag : HTTP/1.1
188
189All of them are delimited by what the standard calls LWS (linear white spaces),
190which are commonly spaces, but can also be tabs or line feeds/carriage returns
191followed by spaces/tabs. The method itself cannot contain any colon (':') and
192is limited to alphabetic letters. All those various combinations make it
193desirable that HAProxy performs the splitting itself rather than leaving it to
194the user to write a complex or inaccurate regular expression.
195
196The URI itself can have several forms :
197
198 - A "relative URI" :
199
200 /serv/login.php?lang=en&profile=2
201
202 It is a complete URL without the host part. This is generally what is
203 received by servers, reverse proxies and transparent proxies.
204
205 - An "absolute URI", also called a "URL" :
206
207 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
208
209 It is composed of a "scheme" (the protocol name followed by '://'), a host
210 name or address, optionally a colon (':') followed by a port number, then
211 a relative URI beginning at the first slash ('/') after the address part.
212 This is generally what proxies receive, but a server supporting HTTP/1.1
213 must accept this form too.
214
215 - a star ('*') : this form is only accepted in association with the OPTIONS
216 method and is not relayable. It is used to inquiry a next hop's
217 capabilities.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100218
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200219 - an address:port combination : 192.168.0.12:80
220 This is used with the CONNECT method, which is used to establish TCP
221 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
222 other protocols too.
223
224In a relative URI, two sub-parts are identified. The part before the question
225mark is called the "path". It is typically the relative path to static objects
226on the server. The part after the question mark is called the "query string".
227It is mostly used with GET requests sent to dynamic scripts and is very
228specific to the language, framework or application in use.
229
230
2311.2.2. The request headers
232--------------------------
233
234The headers start at the second line. They are composed of a name at the
235beginning of the line, immediately followed by a colon (':'). Traditionally,
236an LWS is added after the colon but that's not required. Then come the values.
237Multiple identical headers may be folded into one single line, delimiting the
238values with commas, provided that their order is respected. This is commonly
239encountered in the "Cookie:" field. A header may span over multiple lines if
240the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
241define a total of 3 values for the "Accept:" header.
242
243Contrary to a common mis-conception, header names are not case-sensitive, and
244their values are not either if they refer to other header names (such as the
245"Connection:" header).
246
247The end of the headers is indicated by the first empty line. People often say
248that it's a double line feed, which is not exact, even if a double line feed
249is one valid form of empty line.
250
251Fortunately, HAProxy takes care of all these complex combinations when indexing
252headers, checking values and counting them, so there is no reason to worry
253about the way they could be written, but it is important not to accuse an
254application of being buggy if it does unusual, valid things.
255
256Important note:
257 As suggested by RFC2616, HAProxy normalizes headers by replacing line breaks
258 in the middle of headers by LWS in order to join multi-line headers. This
259 is necessary for proper analysis and helps less capable HTTP parsers to work
260 correctly and not to be fooled by such complex constructs.
261
262
2631.3. HTTP response
264------------------
265
266An HTTP response looks very much like an HTTP request. Both are called HTTP
267messages. Let's consider this HTTP response :
268
269 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100270 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200271 1 HTTP/1.1 200 OK
272 2 Content-length: 350
273 3 Content-Type: text/html
274
Willy Tarreau816b9792009-09-15 21:25:21 +0200275As a special case, HTTP supports so called "Informational responses" as status
276codes 1xx. These messages are special in that they don't convey any part of the
277response, they're just used as sort of a signaling message to ask a client to
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100278continue to post its request for instance. In the case of a status 100 response
279the requested information will be carried by the next non-100 response message
280following the informational one. This implies that multiple responses may be
281sent to a single request, and that this only works when keep-alive is enabled
282(1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to
283correctly forward and skip them, and only process the next non-100 response. As
284such, these messages are neither logged nor transformed, unless explicitly
285state otherwise. Status 101 messages indicate that the protocol is changing
286over the same connection and that haproxy must switch to tunnel mode, just as
287if a CONNECT had occurred. Then the Upgrade header would contain additional
288information about the type of protocol the connection is switching to.
Willy Tarreau816b9792009-09-15 21:25:21 +0200289
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200290
2911.3.1. The Response line
292------------------------
293
294Line 1 is the "response line". It is always composed of 3 fields :
295
296 - a version tag : HTTP/1.1
297 - a status code : 200
298 - a reason : OK
299
300The status code is always 3-digit. The first digit indicates a general status :
Willy Tarreau816b9792009-09-15 21:25:21 +0200301 - 1xx = informational message to be skipped (eg: 100, 101)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200302 - 2xx = OK, content is following (eg: 200, 206)
303 - 3xx = OK, no content following (eg: 302, 304)
304 - 4xx = error caused by the client (eg: 401, 403, 404)
305 - 5xx = error caused by the server (eg: 500, 502, 503)
306
307Please refer to RFC2616 for the detailed meaning of all such codes. The
Willy Tarreaud72758d2010-01-12 10:42:19 +0100308"reason" field is just a hint, but is not parsed by clients. Anything can be
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200309found there, but it's a common practice to respect the well-established
310messages. It can be composed of one or multiple words, such as "OK", "Found",
311or "Authentication Required".
312
313Haproxy may emit the following status codes by itself :
314
315 Code When / reason
316 200 access to stats page, and when replying to monitoring requests
317 301 when performing a redirection, depending on the configured code
318 302 when performing a redirection, depending on the configured code
319 303 when performing a redirection, depending on the configured code
320 400 for an invalid or too large request
321 401 when an authentication is required to perform the action (when
322 accessing the stats page)
323 403 when a request is forbidden by a "block" ACL or "reqdeny" filter
324 408 when the request timeout strikes before the request is complete
325 500 when haproxy encounters an unrecoverable internal error, such as a
326 memory allocation failure, which should never happen
327 502 when the server returns an empty, invalid or incomplete response, or
328 when an "rspdeny" filter blocks the response.
329 503 when no server was available to handle the request, or in response to
330 monitoring requests which match the "monitor fail" condition
331 504 when the response timeout strikes before the server responds
332
333The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3344.2).
335
336
3371.3.2. The response headers
338---------------------------
339
340Response headers work exactly like request headers, and as such, HAProxy uses
341the same parsing function for both. Please refer to paragraph 1.2.2 for more
342details.
343
344
3452. Configuring HAProxy
346----------------------
347
3482.1. Configuration file format
349------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200350
351HAProxy's configuration process involves 3 major sources of parameters :
352
353 - the arguments from the command-line, which always take precedence
354 - the "global" section, which sets process-wide parameters
355 - the proxies sections which can take form of "defaults", "listen",
356 "frontend" and "backend".
357
Willy Tarreau0ba27502007-12-24 16:55:16 +0100358The configuration file syntax consists in lines beginning with a keyword
359referenced in this manual, optionally followed by one or several parameters
360delimited by spaces. If spaces have to be entered in strings, then they must be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100361preceded by a backslash ('\') to be escaped. Backslashes also have to be
Willy Tarreau0ba27502007-12-24 16:55:16 +0100362escaped by doubling them.
363
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200364
3652.2. Time format
366----------------
367
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100368Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100369values are generally expressed in milliseconds (unless explicitly stated
370otherwise) but may be expressed in any other unit by suffixing the unit to the
371numeric value. It is important to consider this because it will not be repeated
372for every keyword. Supported units are :
373
374 - us : microseconds. 1 microsecond = 1/1000000 second
375 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
376 - s : seconds. 1s = 1000ms
377 - m : minutes. 1m = 60s = 60000ms
378 - h : hours. 1h = 60m = 3600s = 3600000ms
379 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
380
381
Patrick Mezard35da19c2010-06-12 17:02:47 +02003822.3. Examples
383-------------
384
385 # Simple configuration for an HTTP proxy listening on port 80 on all
386 # interfaces and forwarding requests to a single backend "servers" with a
387 # single server "server1" listening on 127.0.0.1:8000
388 global
389 daemon
390 maxconn 256
391
392 defaults
393 mode http
394 timeout connect 5000ms
395 timeout client 50000ms
396 timeout server 50000ms
397
398 frontend http-in
399 bind *:80
400 default_backend servers
401
402 backend servers
403 server server1 127.0.0.1:8000 maxconn 32
404
405
406 # The same configuration defined with a single listen block. Shorter but
407 # less expressive, especially in HTTP mode.
408 global
409 daemon
410 maxconn 256
411
412 defaults
413 mode http
414 timeout connect 5000ms
415 timeout client 50000ms
416 timeout server 50000ms
417
418 listen http-in
419 bind *:80
420 server server1 127.0.0.1:8000 maxconn 32
421
422
423Assuming haproxy is in $PATH, test these configurations in a shell with:
424
Willy Tarreauccb289d2010-12-11 20:19:38 +0100425 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200426
427
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004283. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200429--------------------
430
431Parameters in the "global" section are process-wide and often OS-specific. They
432are generally set once for all and do not need being changed once correct. Some
433of them have command-line equivalents.
434
435The following keywords are supported in the "global" section :
436
437 * Process management and security
Emeric Brunc8e8d122012-10-02 18:42:10 +0200438 - ca-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200439 - chroot
Emeric Brunc8e8d122012-10-02 18:42:10 +0200440 - crt-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200441 - daemon
442 - gid
443 - group
444 - log
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100445 - log-send-hostname
Willy Tarreau6a06a402007-07-15 20:15:28 +0200446 - nbproc
447 - pidfile
448 - uid
449 - ulimit-n
450 - user
Willy Tarreaufbee7132007-10-18 13:53:22 +0200451 - stats
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200452 - node
453 - description
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100454 - unix-bind
Willy Tarreaud72758d2010-01-12 10:42:19 +0100455
Willy Tarreau6a06a402007-07-15 20:15:28 +0200456 * Performance tuning
457 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +0200458 - maxconnrate
William Lallemandd85f9172012-11-09 17:05:39 +0100459 - maxcomprate
William Lallemand072a2bf2012-11-20 17:01:01 +0100460 - maxcompcpuusage
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100461 - maxpipes
Willy Tarreau403edff2012-09-06 11:58:37 +0200462 - maxsslconn
Willy Tarreau6a06a402007-07-15 20:15:28 +0200463 - noepoll
464 - nokqueue
465 - nopoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100466 - nosplice
Willy Tarreaufe255b72007-10-14 23:09:26 +0200467 - spread-checks
Willy Tarreau27a674e2009-08-17 07:23:33 +0200468 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200469 - tune.chksize
William Lallemandf3747832012-11-09 12:33:10 +0100470 - tune.comp.maxlevel
Willy Tarreau193b8c62012-11-22 00:17:38 +0100471 - tune.http.cookielen
Willy Tarreauac1932d2011-10-24 19:14:41 +0200472 - tune.http.maxhdr
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100473 - tune.maxaccept
474 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200475 - tune.maxrewrite
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200476 - tune.pipesize
Willy Tarreaue803de22010-01-21 17:43:04 +0100477 - tune.rcvbuf.client
478 - tune.rcvbuf.server
479 - tune.sndbuf.client
480 - tune.sndbuf.server
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100481 - tune.ssl.cachesize
William Lallemanda509e4c2012-11-07 16:54:34 +0100482 - tune.zlib.memlevel
483 - tune.zlib.windowsize
Willy Tarreaud72758d2010-01-12 10:42:19 +0100484
Willy Tarreau6a06a402007-07-15 20:15:28 +0200485 * Debugging
486 - debug
487 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200488
489
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004903.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200491------------------------------------
492
Emeric Brunc8e8d122012-10-02 18:42:10 +0200493ca-base <dir>
494 Assigns a default directory to fetch SSL CA certificates and CRLs from when a
Emeric Brunfd33a262012-10-11 16:28:27 +0200495 relative path is used with "ca-file" or "crl-file" directives. Absolute
496 locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200497
Willy Tarreau6a06a402007-07-15 20:15:28 +0200498chroot <jail dir>
499 Changes current directory to <jail dir> and performs a chroot() there before
500 dropping privileges. This increases the security level in case an unknown
501 vulnerability would be exploited, since it would make it very hard for the
502 attacker to exploit the system. This only works when the process is started
503 with superuser privileges. It is important to ensure that <jail_dir> is both
504 empty and unwritable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100505
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100506cpu-map <"all"|"odd"|"even"|process_num> <cpu-set>...
507 On Linux 2.6 and above, it is possible to bind a process to a specific CPU
508 set. This means that the process will never run on other CPUs. The "cpu-map"
509 directive specifies CPU sets for process sets. The first argument is the
510 process number to bind. This process must have a number between 1 and 32,
511 and any process IDs above nbproc are ignored. It is possible to specify all
512 processes at once using "all", only odd numbers using "odd" or even numbers
513 using "even", just like with the "bind-process" directive. The second and
514 forthcoming arguments are CPU sets. Each CPU set is either a unique number
515 between 0 and 31 or a range with two such numbers delimited by a dash ('-').
516 Multiple CPU numbers or ranges may be specified, and the processes will be
517 allowed to bind to all of them. Obviously, multiple "cpu-map" directives may
518 be specified. Each "cpu-map" directive will replace the previous ones when
519 they overlap.
520
Emeric Brunc8e8d122012-10-02 18:42:10 +0200521crt-base <dir>
522 Assigns a default directory to fetch SSL certificates from when a relative
523 path is used with "crtfile" directives. Absolute locations specified after
524 "crtfile" prevail and ignore "crt-base".
525
Willy Tarreau6a06a402007-07-15 20:15:28 +0200526daemon
527 Makes the process fork into background. This is the recommended mode of
528 operation. It is equivalent to the command line "-D" argument. It can be
529 disabled by the command line "-db" argument.
530
531gid <number>
532 Changes the process' group ID to <number>. It is recommended that the group
533 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
534 be started with a user belonging to this group, or with superuser privileges.
535 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100536
Willy Tarreau6a06a402007-07-15 20:15:28 +0200537group <group name>
538 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
539 See also "gid" and "user".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100540
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200541log <address> <facility> [max level [min level]]
Willy Tarreau6a06a402007-07-15 20:15:28 +0200542 Adds a global syslog server. Up to two global servers can be defined. They
543 will receive logs for startups and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100544 configured with "log global".
545
546 <address> can be one of:
547
Willy Tarreau2769aa02007-12-27 18:26:09 +0100548 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100549 no port is specified, 514 is used by default (the standard syslog
550 port).
551
David du Colombier24bb5f52011-03-17 10:40:23 +0100552 - An IPv6 address followed by a colon and optionally a UDP port. If
553 no port is specified, 514 is used by default (the standard syslog
554 port).
555
Robert Tsai81ae1952007-12-05 10:47:29 +0100556 - A filesystem path to a UNIX domain socket, keeping in mind
557 considerations for chroot (be sure the path is accessible inside
558 the chroot) and uid/gid (be sure the path is appropriately
559 writeable).
560
561 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200562
563 kern user mail daemon auth syslog lpr news
564 uucp cron auth2 ftp ntp audit alert cron2
565 local0 local1 local2 local3 local4 local5 local6 local7
566
567 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200568 all messages are sent. If a maximum level is specified, only messages with a
569 severity at least as important as this level will be sent. An optional minimum
570 level can be specified. If it is set, logs emitted with a more severe level
571 than this one will be capped to this level. This is used to avoid sending
572 "emerg" messages on all terminals on some default syslog configurations.
573 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200574
Cyril Bontédc4d9032012-04-08 21:57:39 +0200575 emerg alert crit err warning notice info debug
Willy Tarreau6a06a402007-07-15 20:15:28 +0200576
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100577log-send-hostname [<string>]
578 Sets the hostname field in the syslog header. If optional "string" parameter
579 is set the header is set to the string contents, otherwise uses the hostname
580 of the system. Generally used if one is not relaying logs through an
581 intermediate syslog server or for simply customizing the hostname printed in
582 the logs.
583
Kevinm48936af2010-12-22 16:08:21 +0000584log-tag <string>
585 Sets the tag field in the syslog header to this string. It defaults to the
586 program name as launched from the command line, which usually is "haproxy".
587 Sometimes it can be useful to differentiate between multiple processes
588 running on the same host.
589
Willy Tarreau6a06a402007-07-15 20:15:28 +0200590nbproc <number>
591 Creates <number> processes when going daemon. This requires the "daemon"
592 mode. By default, only one process is created, which is the recommended mode
593 of operation. For systems limited to small sets of file descriptors per
594 process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES
595 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon".
596
597pidfile <pidfile>
598 Writes pids of all daemons into file <pidfile>. This option is equivalent to
599 the "-p" command line argument. The file must be accessible to the user
600 starting the process. See also "daemon".
601
Willy Tarreau110ecc12012-11-15 17:50:01 +0100602stats bind-process [ all | odd | even | <number 1-32>[-<number 1-32>] ] ...
Willy Tarreau35b7b162012-10-22 23:17:18 +0200603 Limits the stats socket to a certain set of processes numbers. By default the
604 stats socket is bound to all processes, causing a warning to be emitted when
605 nbproc is greater than 1 because there is no way to select the target process
606 when connecting. However, by using this setting, it becomes possible to pin
607 the stats socket to a specific set of processes, typically the first one. The
608 warning will automatically be disabled when this setting is used, whatever
609 the number of processes used.
610
Willy Tarreauabb175f2012-09-24 12:43:26 +0200611stats socket [<address:port>|<path>] [param*]
612 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
613 Connections to this socket will return various statistics outputs and even
614 allow some commands to be issued to change some runtime settings. Please
615 consult section 9.2 "Unix Socket commands" for more details.
Willy Tarreau6162db22009-10-10 17:13:00 +0200616
Willy Tarreauabb175f2012-09-24 12:43:26 +0200617 All parameters supported by "bind" lines are supported, for instance to
618 restrict access to some users or their access rights. Please consult
619 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200620
621stats timeout <timeout, in milliseconds>
622 The default timeout on the stats socket is set to 10 seconds. It is possible
623 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +0100624 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200625
626stats maxconn <connections>
627 By default, the stats socket is limited to 10 concurrent connections. It is
628 possible to change this value with "stats maxconn".
629
Willy Tarreau6a06a402007-07-15 20:15:28 +0200630uid <number>
631 Changes the process' user ID to <number>. It is recommended that the user ID
632 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
633 be started with superuser privileges in order to be able to switch to another
634 one. See also "gid" and "user".
635
636ulimit-n <number>
637 Sets the maximum number of per-process file-descriptors to <number>. By
638 default, it is automatically computed, so it is recommended not to use this
639 option.
640
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100641unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
642 [ group <group> ] [ gid <gid> ]
643
644 Fixes common settings to UNIX listening sockets declared in "bind" statements.
645 This is mainly used to simplify declaration of those UNIX sockets and reduce
646 the risk of errors, since those settings are most commonly required but are
647 also process-specific. The <prefix> setting can be used to force all socket
648 path to be relative to that directory. This might be needed to access another
649 component's chroot. Note that those paths are resolved before haproxy chroots
650 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
651 all have the same meaning as their homonyms used by the "bind" statement. If
652 both are specified, the "bind" statement has priority, meaning that the
653 "unix-bind" settings may be seen as process-wide default settings.
654
Willy Tarreau6a06a402007-07-15 20:15:28 +0200655user <user name>
656 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
657 See also "uid" and "group".
658
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200659node <name>
660 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
661
662 This statement is useful in HA configurations where two or more processes or
663 servers share the same IP address. By setting a different node-name on all
664 nodes, it becomes easy to immediately spot what server is handling the
665 traffic.
666
667description <text>
668 Add a text that describes the instance.
669
670 Please note that it is required to escape certain characters (# for example)
671 and this text is inserted into a html page so you should avoid using
672 "<" and ">" characters.
673
Willy Tarreau6a06a402007-07-15 20:15:28 +0200674
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006753.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +0200676-----------------------
677
678maxconn <number>
679 Sets the maximum per-process number of concurrent connections to <number>. It
680 is equivalent to the command-line argument "-n". Proxies will stop accepting
681 connections when this limit is reached. The "ulimit-n" parameter is
682 automatically adjusted according to this value. See also "ulimit-n".
683
Willy Tarreau81c25d02011-09-07 15:17:21 +0200684maxconnrate <number>
685 Sets the maximum per-process number of connections per second to <number>.
686 Proxies will stop accepting connections when this limit is reached. It can be
687 used to limit the global capacity regardless of each frontend capacity. It is
688 important to note that this can only be used as a service protection measure,
689 as there will not necessarily be a fair share between frontends when the
690 limit is reached, so it's a good idea to also limit each frontend to some
691 value close to its expected share. Also, lowering tune.maxaccept can improve
692 fairness.
693
William Lallemandd85f9172012-11-09 17:05:39 +0100694maxcomprate <number>
695 Sets the maximum per-process input compression rate to <number> kilobytes
696 pers second. For each session, if the maximum is reached, the compression
697 level will be decreased during the session. If the maximum is reached at the
698 beginning of a session, the session will not compress at all. If the maximum
699 is not reached, the compression level will be increased up to
700 tune.comp.maxlevel. A value of zero means there is no limit, this is the
701 default value.
702
William Lallemand072a2bf2012-11-20 17:01:01 +0100703maxcompcpuusage <number>
704 Sets the maximum CPU usage HAProxy can reach before stopping the compression
705 for new requests or decreasing the compression level of current requests.
706 It works like 'maxcomprate' but measures CPU usage instead of incoming data
707 bandwidth. The value is expressed in percent of the CPU used by haproxy. In
708 case of multiple processes (nbproc > 1), each process manages its individual
709 usage. A value of 100 disable the limit. The default value is 100. Setting
710 a lower value will prevent the compression work from slowing the whole
711 process down and from introducing high latencies.
712
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100713maxpipes <number>
714 Sets the maximum per-process number of pipes to <number>. Currently, pipes
715 are only used by kernel-based tcp splicing. Since a pipe contains two file
716 descriptors, the "ulimit-n" value will be increased accordingly. The default
717 value is maxconn/4, which seems to be more than enough for most heavy usages.
718 The splice code dynamically allocates and releases pipes, and can fall back
719 to standard copy, so setting this value too low may only impact performance.
720
Willy Tarreau403edff2012-09-06 11:58:37 +0200721maxsslconn <number>
722 Sets the maximum per-process number of concurrent SSL connections to
723 <number>. By default there is no SSL-specific limit, which means that the
724 global maxconn setting will apply to all connections. Setting this limit
725 avoids having openssl use too much memory and crash when malloc returns NULL
726 (since it unfortunately does not reliably check for such conditions). Note
727 that the limit applies both to incoming and outgoing connections, so one
728 connection which is deciphered then ciphered accounts for 2 SSL connections.
729
William Lallemand9d5f5482012-11-07 16:12:57 +0100730maxzlibmem <number>
731 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
732 When the maximum amount is reached, future sessions will not compress as long
733 as RAM is unavailable. When sets to 0, there is no limit.
William Lallemande3a7d992012-11-20 11:25:20 +0100734 The default value is 0. The value is available in bytes on the UNIX socket
735 with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is
736 "ZlibMemUsage" in bytes.
737
Willy Tarreau6a06a402007-07-15 20:15:28 +0200738noepoll
739 Disables the use of the "epoll" event polling system on Linux. It is
740 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100741 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +0200742
743nokqueue
744 Disables the use of the "kqueue" event polling system on BSD. It is
745 equivalent to the command-line argument "-dk". The next polling system
746 used will generally be "poll". See also "nopoll".
747
748nopoll
749 Disables the use of the "poll" event polling system. It is equivalent to the
750 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +0100751 It should never be needed to disable "poll" since it's available on all
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100752 platforms supported by HAProxy. See also "nokqueue" and "noepoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +0200753
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100754nosplice
755 Disables the use of kernel tcp splicing between sockets on Linux. It is
756 equivalent to the command line argument "-dS". Data will then be copied
757 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100758 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100759 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
760 be used. This option makes it easier to globally disable kernel splicing in
761 case of doubt. See also "option splice-auto", "option splice-request" and
762 "option splice-response".
763
Willy Tarreaufe255b72007-10-14 23:09:26 +0200764spread-checks <0..50, in percent>
765 Sometimes it is desirable to avoid sending health checks to servers at exact
766 intervals, for instance when many logical servers are located on the same
767 physical server. With the help of this parameter, it becomes possible to add
768 some randomness in the check interval between 0 and +/- 50%. A value between
769 2 and 5 seems to show good results. The default value remains at 0.
770
Willy Tarreau27a674e2009-08-17 07:23:33 +0200771tune.bufsize <number>
772 Sets the buffer size to this size (in bytes). Lower values allow more
773 sessions to coexist in the same amount of RAM, and higher values allow some
774 applications with very large cookies to work. The default value is 16384 and
775 can be changed at build time. It is strongly recommended not to change this
776 from the default value, as very low values will break some services such as
777 statistics, and values larger than default size will increase memory usage,
778 possibly causing the system to run out of memory. At least the global maxconn
779 parameter should be decreased by the same factor as this one is increased.
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +0400780 If HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will
781 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
782 than this size, haproxy will return HTTP 502 (Bad Gateway).
Willy Tarreau27a674e2009-08-17 07:23:33 +0200783
Willy Tarreau43961d52010-10-04 20:39:20 +0200784tune.chksize <number>
785 Sets the check buffer size to this size (in bytes). Higher values may help
786 find string or regex patterns in very large pages, though doing so may imply
787 more memory and CPU usage. The default value is 16384 and can be changed at
788 build time. It is not recommended to change this value, but to use better
789 checks whenever possible.
790
William Lallemandf3747832012-11-09 12:33:10 +0100791tune.comp.maxlevel <number>
792 Sets the maximum compression level. The compression level affects CPU
793 usage during compression. This value affects CPU usage during compression.
794 Each session using compression initializes the compression algorithm with
795 this value. The default value is 1.
796
Willy Tarreau193b8c62012-11-22 00:17:38 +0100797tune.http.cookielen <number>
798 Sets the maximum length of captured cookies. This is the maximum value that
799 the "capture cookie xxx len yyy" will be allowed to take, and any upper value
800 will automatically be truncated to this one. It is important not to set too
801 high a value because all cookie captures still allocate this size whatever
802 their configured value (they share a same pool). This value is per request
803 per response, so the memory allocated is twice this value per connection.
804 When not specified, the limit is set to 63 characters. It is recommended not
805 to change this value.
806
Willy Tarreauac1932d2011-10-24 19:14:41 +0200807tune.http.maxhdr <number>
808 Sets the maximum number of headers in a request. When a request comes with a
809 number of headers greater than this value (including the first line), it is
810 rejected with a "400 Bad Request" status code. Similarly, too large responses
811 are blocked with "502 Bad Gateway". The default value is 101, which is enough
812 for all usages, considering that the widely deployed Apache server uses the
813 same limit. It can be useful to push this limit further to temporarily allow
814 a buggy application to work by the time it gets fixed. Keep in mind that each
815 new header consumes 32bits of memory for each session, so don't push this
816 limit too high.
817
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100818tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +0100819 Sets the maximum number of consecutive connections a process may accept in a
820 row before switching to other work. In single process mode, higher numbers
821 give better performance at high connection rates. However in multi-process
822 modes, keeping a bit of fairness between processes generally is better to
823 increase performance. This value applies individually to each listener, so
824 that the number of processes a listener is bound to is taken into account.
825 This value defaults to 64. In multi-process mode, it is divided by twice
826 the number of processes the listener is bound to. Setting this value to -1
827 completely disables the limitation. It should normally not be needed to tweak
828 this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100829
830tune.maxpollevents <number>
831 Sets the maximum amount of events that can be processed at once in a call to
832 the polling system. The default value is adapted to the operating system. It
833 has been noticed that reducing it below 200 tends to slightly decrease
834 latency at the expense of network bandwidth, and increasing it above 200
835 tends to trade latency for slightly increased bandwidth.
836
Willy Tarreau27a674e2009-08-17 07:23:33 +0200837tune.maxrewrite <number>
838 Sets the reserved buffer space to this size in bytes. The reserved space is
839 used for header rewriting or appending. The first reads on sockets will never
840 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
841 bufsize, though that does not make much sense since there are rarely large
842 numbers of headers to add. Setting it too high prevents processing of large
843 requests or responses. Setting it too low prevents addition of new headers
844 to already large requests or to POST requests. It is generally wise to set it
845 to about 1024. It is automatically readjusted to half of bufsize if it is
846 larger than that. This means you don't have to worry about it when changing
847 bufsize.
848
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200849tune.pipesize <number>
850 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
851 are the default size for the system. But sometimes when using TCP splicing,
852 it can improve performance to increase pipe sizes, especially if it is
853 suspected that pipes are not filled and that many calls to splice() are
854 performed. This has an impact on the kernel's memory footprint, so this must
855 not be changed if impacts are not understood.
856
Willy Tarreaue803de22010-01-21 17:43:04 +0100857tune.rcvbuf.client <number>
858tune.rcvbuf.server <number>
859 Forces the kernel socket receive buffer size on the client or the server side
860 to the specified value in bytes. This value applies to all TCP/HTTP frontends
861 and backends. It should normally never be set, and the default size (0) lets
862 the kernel autotune this value depending on the amount of available memory.
863 However it can sometimes help to set it to very low values (eg: 4096) in
864 order to save kernel memory by preventing it from buffering too large amounts
865 of received data. Lower values will significantly increase CPU usage though.
866
867tune.sndbuf.client <number>
868tune.sndbuf.server <number>
869 Forces the kernel socket send buffer size on the client or the server side to
870 the specified value in bytes. This value applies to all TCP/HTTP frontends
871 and backends. It should normally never be set, and the default size (0) lets
872 the kernel autotune this value depending on the amount of available memory.
873 However it can sometimes help to set it to very low values (eg: 4096) in
874 order to save kernel memory by preventing it from buffering too large amounts
875 of received data. Lower values will significantly increase CPU usage though.
876 Another use case is to prevent write timeouts with extremely slow clients due
877 to the kernel waiting for a large part of the buffer to be read before
878 notifying haproxy again.
879
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100880tune.ssl.cachesize <number>
Emeric Brunaf9619d2012-11-28 18:47:52 +0100881 Sets the size of the global SSL session cache, in a number of blocks. A block
882 is large enough to contain an encoded session without peer certificate.
883 An encoded session with peer certificate is stored in multiple blocks
884 depending on the size of the peer certificate. A block use approximatively
885 200 bytes of memory. The default value may be forced at build time, otherwise
886 defaults to 20000. When the cache is full, the most idle entries are purged
887 and reassigned. Higher values reduce the occurrence of such a purge, hence
888 the number of CPU-intensive SSL handshakes by ensuring that all users keep
889 their session as long as possible. All entries are pre-allocated upon startup
890 and are shared between all processes if "nbproc" is greater than 1.
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100891
Emeric Brun4f65bff2012-11-16 15:11:00 +0100892tune.ssl.lifetime <timeout>
893 Sets how long a cached SSL session may remain valid. This time is expressed
894 in seconds and defaults to 300 (5 mn). It is important to understand that it
895 does not guarantee that sessions will last that long, because if the cache is
896 full, the longest idle sessions will be purged despite their configured
897 lifetime. The real usefulness of this setting is to prevent sessions from
898 being used for too long.
899
William Lallemanda509e4c2012-11-07 16:54:34 +0100900tune.zlib.memlevel <number>
901 Sets the memLevel parameter in zlib initialization for each session. It
902 defines how much memory should be allocated for the intenal compression
903 state. A value of 1 uses minimum memory but is slow and reduces compression
904 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
905 between 1 and 9. The default value is 8.
906
907tune.zlib.windowsize <number>
908 Sets the window size (the size of the history buffer) as a parameter of the
909 zlib initialization for each session. Larger values of this parameter result
910 in better compression at the expense of memory usage. Can be a value between
911 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200912
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009133.3. Debugging
914--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200915
916debug
917 Enables debug mode which dumps to stdout all exchanges, and disables forking
918 into background. It is the equivalent of the command-line argument "-d". It
919 should never be used in a production configuration since it may prevent full
920 system startup.
921
922quiet
923 Do not display any message during startup. It is equivalent to the command-
924 line argument "-q".
925
Emeric Brunf099e792010-09-27 12:05:28 +0200926
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01009273.4. Userlists
928--------------
929It is possible to control access to frontend/backend/listen sections or to
930http stats by allowing only authenticated and authorized users. To do this,
931it is required to create at least one userlist and to define users.
932
933userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +0100934 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100935 used to store authentication & authorization data for independent customers.
936
937group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +0100938 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100939 attach users to this group by using a comma separated list of names
940 proceeded by "users" keyword.
941
Cyril Bontéf0c60612010-02-06 14:44:47 +0100942user <username> [password|insecure-password <password>]
943 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100944 Adds user <username> to the current userlist. Both secure (encrypted) and
945 insecure (unencrypted) passwords can be used. Encrypted passwords are
Cyril Bonté78caf842010-03-10 22:41:43 +0100946 evaluated using the crypt(3) function so depending of the system's
947 capabilities, different algorithms are supported. For example modern Glibc
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100948 based Linux system supports MD5, SHA-256, SHA-512 and of course classic,
949 DES-based method of crypting passwords.
950
951
952 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +0100953 userlist L1
954 group G1 users tiger,scott
955 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100956
Cyril Bontéf0c60612010-02-06 14:44:47 +0100957 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
958 user scott insecure-password elgato
959 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100960
Cyril Bontéf0c60612010-02-06 14:44:47 +0100961 userlist L2
962 group G1
963 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100964
Cyril Bontéf0c60612010-02-06 14:44:47 +0100965 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
966 user scott insecure-password elgato groups G1,G2
967 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100968
969 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200970
Emeric Brunf099e792010-09-27 12:05:28 +0200971
9723.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +0200973----------
Emeric Brunf099e792010-09-27 12:05:28 +0200974It is possible to synchronize server entries in stick tables between several
975haproxy instances over TCP connections in a multi-master fashion. Each instance
976pushes its local updates and insertions to remote peers. Server IDs are used to
977identify servers remotely, so it is important that configurations look similar
978or at least that the same IDs are forced on each server on all participants.
979Interrupted exchanges are automatically detected and recovered from the last
980known point. In addition, during a soft restart, the old process connects to
981the new one using such a TCP connection to push all its entries before the new
982process tries to connect to other peers. That ensures very fast replication
983during a reload, it typically takes a fraction of a second even for large
984tables.
985
986peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -0400987 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +0200988 which is referenced by one or more stick-tables.
989
990peer <peername> <ip>:<port>
991 Defines a peer inside a peers section.
992 If <peername> is set to the local peer name (by default hostname, or forced
993 using "-L" command line option), haproxy will listen for incoming remote peer
994 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
995 to join the remote peer, and <peername> is used at the protocol level to
996 identify and validate the remote peer on the server side.
997
998 During a soft restart, local peer <ip>:<port> is used by the old instance to
999 connect the new one and initiate a complete replication (teaching process).
1000
1001 It is strongly recommended to have the exact same peers declaration on all
1002 peers and to only rely on the "-L" command line argument to change the local
1003 peer name. This makes it easier to maintain coherent configuration files
1004 across all peers.
1005
Cyril Bontédc4d9032012-04-08 21:57:39 +02001006 Example:
Emeric Brunf099e792010-09-27 12:05:28 +02001007 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001008 peer haproxy1 192.168.0.1:1024
1009 peer haproxy2 192.168.0.2:1024
1010 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +02001011
1012 backend mybackend
1013 mode tcp
1014 balance roundrobin
1015 stick-table type ip size 20k peers mypeers
1016 stick on src
1017
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001018 server srv1 192.168.0.30:80
1019 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +02001020
1021
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010224. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +02001023----------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001024
Willy Tarreau6a06a402007-07-15 20:15:28 +02001025Proxy configuration can be located in a set of sections :
1026 - defaults <name>
1027 - frontend <name>
1028 - backend <name>
1029 - listen <name>
1030
1031A "defaults" section sets default parameters for all other sections following
1032its declaration. Those default parameters are reset by the next "defaults"
1033section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +01001034section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001035
1036A "frontend" section describes a set of listening sockets accepting client
1037connections.
1038
1039A "backend" section describes a set of servers to which the proxy will connect
1040to forward incoming connections.
1041
1042A "listen" section defines a complete proxy with its frontend and backend
1043parts combined in one section. It is generally useful for TCP-only traffic.
1044
Willy Tarreau0ba27502007-12-24 16:55:16 +01001045All proxy names must be formed from upper and lower case letters, digits,
1046'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
1047case-sensitive, which means that "www" and "WWW" are two different proxies.
1048
1049Historically, all proxy names could overlap, it just caused troubles in the
1050logs. Since the introduction of content switching, it is mandatory that two
1051proxies with overlapping capabilities (frontend/backend) have different names.
1052However, it is still permitted that a frontend and a backend share the same
1053name, as this configuration seems to be commonly encountered.
1054
1055Right now, two major proxy modes are supported : "tcp", also known as layer 4,
1056and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001057bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01001058protocol, and can interact with it by allowing, blocking, switching, adding,
1059modifying, or removing arbitrary contents in requests or responses, based on
1060arbitrary criteria.
1061
Willy Tarreau0ba27502007-12-24 16:55:16 +01001062
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010634.1. Proxy keywords matrix
1064--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001065
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001066The following list of keywords is supported. Most of them may only be used in a
1067limited set of section types. Some of them are marked as "deprecated" because
1068they are inherited from an old syntax which may be confusing or functionally
1069limited, and there are new recommended keywords to replace them. Keywords
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001070marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001071option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02001072and must be disabled for a specific instance. Such options may also be prefixed
1073with "default" in order to restore default settings regardless of what has been
1074specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001075
Willy Tarreau6a06a402007-07-15 20:15:28 +02001076
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001077 keyword defaults frontend listen backend
1078------------------------------------+----------+----------+---------+---------
1079acl - X X X
1080appsession - - X X
1081backlog X X X -
1082balance X - X X
1083bind - X X -
1084bind-process X X X X
1085block - X X X
1086capture cookie - X X -
1087capture request header - X X -
1088capture response header - X X -
1089clitimeout (deprecated) X X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02001090compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001091contimeout (deprecated) X - X X
1092cookie X - X X
1093default-server X - X X
1094default_backend X X X -
1095description - X X X
1096disabled X X X X
1097dispatch - - X X
1098enabled X X X X
1099errorfile X X X X
1100errorloc X X X X
1101errorloc302 X X X X
1102-- keyword -------------------------- defaults - frontend - listen -- backend -
1103errorloc303 X X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001104force-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001105fullconn X - X X
1106grace X X X X
1107hash-type X - X X
1108http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +01001109http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02001110http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001111http-request - X X X
1112id - X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001113ignore-persist - X X X
William Lallemand0f99e342011-10-12 17:50:54 +02001114log (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001115maxconn X X X -
1116mode X X X X
1117monitor fail - X X -
1118monitor-net X X X -
1119monitor-uri X X X -
1120option abortonclose (*) X - X X
1121option accept-invalid-http-request (*) X X X -
1122option accept-invalid-http-response (*) X - X X
1123option allbackups (*) X - X X
1124option checkcache (*) X - X X
1125option clitcpka (*) X X X -
1126option contstats (*) X X X -
1127option dontlog-normal (*) X X X -
1128option dontlognull (*) X X X -
1129option forceclose (*) X X X X
1130-- keyword -------------------------- defaults - frontend - listen -- backend -
1131option forwardfor X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02001132option http-no-delay (*) X X X X
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02001133option http-pretend-keepalive (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001134option http-server-close (*) X X X X
1135option http-use-proxy-header (*) X X X -
1136option httpchk X - X X
1137option httpclose (*) X X X X
1138option httplog X X X X
1139option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001140option independent-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02001141option ldap-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001142option log-health-checks (*) X - X X
1143option log-separate-errors (*) X X X -
1144option logasap (*) X X X -
1145option mysql-check X - X X
Rauf Kuliyev38b41562011-01-04 15:14:13 +01001146option pgsql-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001147option nolinger (*) X X X X
1148option originalto X X X X
1149option persist (*) X - X X
1150option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02001151option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001152option smtpchk X - X X
1153option socket-stats (*) X X X -
1154option splice-auto (*) X X X X
1155option splice-request (*) X X X X
1156option splice-response (*) X X X X
1157option srvtcpka (*) X - X X
1158option ssl-hello-chk X - X X
1159-- keyword -------------------------- defaults - frontend - listen -- backend -
1160option tcp-smart-accept (*) X X X -
1161option tcp-smart-connect (*) X - X X
1162option tcpka X X X X
1163option tcplog X X X X
1164option transparent (*) X - X X
1165persist rdp-cookie X - X X
1166rate-limit sessions X X X -
1167redirect - X X X
1168redisp (deprecated) X - X X
1169redispatch (deprecated) X - X X
1170reqadd - X X X
1171reqallow - X X X
1172reqdel - X X X
1173reqdeny - X X X
1174reqiallow - X X X
1175reqidel - X X X
1176reqideny - X X X
1177reqipass - X X X
1178reqirep - X X X
1179reqisetbe - X X X
1180reqitarpit - X X X
1181reqpass - X X X
1182reqrep - X X X
1183-- keyword -------------------------- defaults - frontend - listen -- backend -
1184reqsetbe - X X X
1185reqtarpit - X X X
1186retries X - X X
1187rspadd - X X X
1188rspdel - X X X
1189rspdeny - X X X
1190rspidel - X X X
1191rspideny - X X X
1192rspirep - X X X
1193rsprep - X X X
1194server - - X X
1195source X - X X
1196srvtimeout (deprecated) X - X X
Cyril Bonté66c327d2010-10-12 00:14:37 +02001197stats admin - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001198stats auth X - X X
1199stats enable X - X X
1200stats hide-version X - X X
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02001201stats http-request - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001202stats realm X - X X
1203stats refresh X - X X
1204stats scope X - X X
1205stats show-desc X - X X
1206stats show-legends X - X X
1207stats show-node X - X X
1208stats uri X - X X
1209-- keyword -------------------------- defaults - frontend - listen -- backend -
1210stick match - - X X
1211stick on - - X X
1212stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02001213stick store-response - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001214stick-table - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02001215tcp-request connection - X X -
1216tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02001217tcp-request inspect-delay - X X X
Emeric Brun0a3b67f2010-09-24 15:34:53 +02001218tcp-response content - - X X
1219tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001220timeout check X - X X
1221timeout client X X X -
1222timeout clitimeout (deprecated) X X X -
1223timeout connect X - X X
1224timeout contimeout (deprecated) X - X X
1225timeout http-keep-alive X X X X
1226timeout http-request X X X X
1227timeout queue X - X X
1228timeout server X - X X
1229timeout srvtimeout (deprecated) X - X X
1230timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02001231timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001232transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01001233unique-id-format X X X -
1234unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001235use_backend - X X -
Willy Tarreau4a5cade2012-04-05 21:09:48 +02001236use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001237------------------------------------+----------+----------+---------+---------
1238 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02001239
Willy Tarreau0ba27502007-12-24 16:55:16 +01001240
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012414.2. Alphabetically sorted keywords reference
1242---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001243
1244This section provides a description of each keyword and its usage.
1245
1246
1247acl <aclname> <criterion> [flags] [operator] <value> ...
1248 Declare or complete an access list.
1249 May be used in sections : defaults | frontend | listen | backend
1250 no | yes | yes | yes
1251 Example:
1252 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1253 acl invalid_src src_port 0:1023
1254 acl local_dst hdr(host) -i localhost
1255
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001256 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001257
1258
Cyril Bontéb21570a2009-11-29 20:04:48 +01001259appsession <cookie> len <length> timeout <holdtime>
1260 [request-learn] [prefix] [mode <path-parameters|query-string>]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001261 Define session stickiness on an existing application cookie.
1262 May be used in sections : defaults | frontend | listen | backend
1263 no | no | yes | yes
1264 Arguments :
1265 <cookie> this is the name of the cookie used by the application and which
1266 HAProxy will have to learn for each new session.
1267
Cyril Bontéb21570a2009-11-29 20:04:48 +01001268 <length> this is the max number of characters that will be memorized and
Willy Tarreau0ba27502007-12-24 16:55:16 +01001269 checked in each cookie value.
1270
1271 <holdtime> this is the time after which the cookie will be removed from
1272 memory if unused. If no unit is specified, this time is in
1273 milliseconds.
1274
Cyril Bontébf47aeb2009-10-15 00:15:40 +02001275 request-learn
1276 If this option is specified, then haproxy will be able to learn
1277 the cookie found in the request in case the server does not
1278 specify any in response. This is typically what happens with
1279 PHPSESSID cookies, or when haproxy's session expires before
1280 the application's session and the correct server is selected.
1281 It is recommended to specify this option to improve reliability.
1282
Cyril Bontéb21570a2009-11-29 20:04:48 +01001283 prefix When this option is specified, haproxy will match on the cookie
1284 prefix (or URL parameter prefix). The appsession value is the
1285 data following this prefix.
1286
1287 Example :
1288 appsession ASPSESSIONID len 64 timeout 3h prefix
1289
1290 This will match the cookie ASPSESSIONIDXXXX=XXXXX,
1291 the appsession value will be XXXX=XXXXX.
1292
1293 mode This option allows to change the URL parser mode.
1294 2 modes are currently supported :
1295 - path-parameters :
1296 The parser looks for the appsession in the path parameters
1297 part (each parameter is separated by a semi-colon), which is
1298 convenient for JSESSIONID for example.
1299 This is the default mode if the option is not set.
1300 - query-string :
1301 In this mode, the parser will look for the appsession in the
1302 query string.
1303
Willy Tarreau0ba27502007-12-24 16:55:16 +01001304 When an application cookie is defined in a backend, HAProxy will check when
1305 the server sets such a cookie, and will store its value in a table, and
1306 associate it with the server's identifier. Up to <length> characters from
1307 the value will be retained. On each connection, haproxy will look for this
Cyril Bontéb21570a2009-11-29 20:04:48 +01001308 cookie both in the "Cookie:" headers, and as a URL parameter (depending on
1309 the mode used). If a known value is found, the client will be directed to the
1310 server associated with this value. Otherwise, the load balancing algorithm is
Willy Tarreau0ba27502007-12-24 16:55:16 +01001311 applied. Cookies are automatically removed from memory when they have been
1312 unused for a duration longer than <holdtime>.
1313
1314 The definition of an application cookie is limited to one per backend.
1315
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001316 Note : Consider not using this feature in multi-process mode (nbproc > 1)
1317 unless you know what you do : memory is not shared between the
1318 processes, which can result in random behaviours.
1319
Willy Tarreau0ba27502007-12-24 16:55:16 +01001320 Example :
1321 appsession JSESSIONID len 52 timeout 3h
1322
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001323 See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
1324 "ignore-persist", "nbproc" and "bind-process".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001325
1326
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001327backlog <conns>
1328 Give hints to the system about the approximate listen backlog desired size
1329 May be used in sections : defaults | frontend | listen | backend
1330 yes | yes | yes | no
1331 Arguments :
1332 <conns> is the number of pending connections. Depending on the operating
1333 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02001334 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001335
1336 In order to protect against SYN flood attacks, one solution is to increase
1337 the system's SYN backlog size. Depending on the system, sometimes it is just
1338 tunable via a system parameter, sometimes it is not adjustable at all, and
1339 sometimes the system relies on hints given by the application at the time of
1340 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
1341 to the listen() syscall. On systems which can make use of this value, it can
1342 sometimes be useful to be able to specify a different value, hence this
1343 backlog parameter.
1344
1345 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
1346 used as a hint and the system accepts up to the smallest greater power of
1347 two, and never more than some limits (usually 32768).
1348
1349 See also : "maxconn" and the target operating system's tuning guide.
1350
1351
Willy Tarreau0ba27502007-12-24 16:55:16 +01001352balance <algorithm> [ <arguments> ]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001353balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001354 Define the load balancing algorithm to be used in a backend.
1355 May be used in sections : defaults | frontend | listen | backend
1356 yes | no | yes | yes
1357 Arguments :
1358 <algorithm> is the algorithm used to select a server when doing load
1359 balancing. This only applies when no persistence information
1360 is available, or when a connection is redispatched to another
1361 server. <algorithm> may be one of the following :
1362
1363 roundrobin Each server is used in turns, according to their weights.
1364 This is the smoothest and fairest algorithm when the server's
1365 processing time remains equally distributed. This algorithm
1366 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02001367 on the fly for slow starts for instance. It is limited by
1368 design to 4128 active servers per backend. Note that in some
1369 large farms, when a server becomes up after having been down
1370 for a very short time, it may sometimes take a few hundreds
1371 requests for it to be re-integrated into the farm and start
1372 receiving traffic. This is normal, though very rare. It is
1373 indicated here in case you would have the chance to observe
1374 it, so that you don't worry.
1375
1376 static-rr Each server is used in turns, according to their weights.
1377 This algorithm is as similar to roundrobin except that it is
1378 static, which means that changing a server's weight on the
1379 fly will have no effect. On the other hand, it has no design
1380 limitation on the number of servers, and when a server goes
1381 up, it is always immediately reintroduced into the farm, once
1382 the full map is recomputed. It also uses slightly less CPU to
1383 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01001384
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01001385 leastconn The server with the lowest number of connections receives the
1386 connection. Round-robin is performed within groups of servers
1387 of the same load to ensure that all servers will be used. Use
1388 of this algorithm is recommended where very long sessions are
1389 expected, such as LDAP, SQL, TSE, etc... but is not very well
1390 suited for protocols using short sessions such as HTTP. This
1391 algorithm is dynamic, which means that server weights may be
1392 adjusted on the fly for slow starts for instance.
1393
Willy Tarreauf09c6602012-02-13 17:12:08 +01001394 first The first server with available connection slots receives the
1395 connection. The servers are choosen from the lowest numeric
1396 identifier to the highest (see server parameter "id"), which
1397 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02001398 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01001399 not make sense to use this algorithm without setting maxconn.
1400 The purpose of this algorithm is to always use the smallest
1401 number of servers so that extra servers can be powered off
1402 during non-intensive hours. This algorithm ignores the server
1403 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02001404 or IMAP than HTTP, though it can be useful there too. In
1405 order to use this algorithm efficiently, it is recommended
1406 that a cloud controller regularly checks server usage to turn
1407 them off when unused, and regularly checks backend queue to
1408 turn new servers on when the queue inflates. Alternatively,
1409 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01001410
Willy Tarreau0ba27502007-12-24 16:55:16 +01001411 source The source IP address is hashed and divided by the total
1412 weight of the running servers to designate which server will
1413 receive the request. This ensures that the same client IP
1414 address will always reach the same server as long as no
1415 server goes down or up. If the hash result changes due to the
1416 number of running servers changing, many clients will be
1417 directed to a different server. This algorithm is generally
1418 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001419 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01001420 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001421 static by default, which means that changing a server's
1422 weight on the fly will have no effect, but this can be
1423 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001424
Oskar Stolc8dc41842012-05-19 10:19:54 +01001425 uri This algorithm hashes either the left part of the URI (before
1426 the question mark) or the whole URI (if the "whole" parameter
1427 is present) and divides the hash value by the total weight of
1428 the running servers. The result designates which server will
1429 receive the request. This ensures that the same URI will
1430 always be directed to the same server as long as no server
1431 goes up or down. This is used with proxy caches and
1432 anti-virus proxies in order to maximize the cache hit rate.
1433 Note that this algorithm may only be used in an HTTP backend.
1434 This algorithm is static by default, which means that
1435 changing a server's weight on the fly will have no effect,
1436 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001437
Oskar Stolc8dc41842012-05-19 10:19:54 +01001438 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001439 "depth", both followed by a positive integer number. These
1440 options may be helpful when it is needed to balance servers
1441 based on the beginning of the URI only. The "len" parameter
1442 indicates that the algorithm should only consider that many
1443 characters at the beginning of the URI to compute the hash.
1444 Note that having "len" set to 1 rarely makes sense since most
1445 URIs start with a leading "/".
1446
1447 The "depth" parameter indicates the maximum directory depth
1448 to be used to compute the hash. One level is counted for each
1449 slash in the request. If both parameters are specified, the
1450 evaluation stops when either is reached.
1451
Willy Tarreau0ba27502007-12-24 16:55:16 +01001452 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001453 the query string of each HTTP GET request.
1454
1455 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02001456 request entity will be searched for the parameter argument,
1457 when it is not found in a query string after a question mark
1458 ('?') in the URL. Optionally, specify a number of octets to
1459 wait for before attempting to search the message body. If the
1460 entity can not be searched, then round robin is used for each
1461 request. For instance, if your clients always send the LB
1462 parameter in the first 128 bytes, then specify that. The
1463 default is 48. The entity data will not be scanned until the
1464 required number of octets have arrived at the gateway, this
1465 is the minimum of: (default/max_wait, Content-Length or first
1466 chunk length). If Content-Length is missing or zero, it does
1467 not need to wait for more data than the client promised to
1468 send. When Content-Length is present and larger than
1469 <max_wait>, then waiting is limited to <max_wait> and it is
1470 assumed that this will be enough data to search for the
1471 presence of the parameter. In the unlikely event that
1472 Transfer-Encoding: chunked is used, only the first chunk is
1473 scanned. Parameter values separated by a chunk boundary, may
1474 be randomly balanced if at all.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001475
1476 If the parameter is found followed by an equal sign ('=') and
1477 a value, then the value is hashed and divided by the total
1478 weight of the running servers. The result designates which
1479 server will receive the request.
1480
1481 This is used to track user identifiers in requests and ensure
1482 that a same user ID will always be sent to the same server as
1483 long as no server goes up or down. If no value is found or if
1484 the parameter is not found, then a round robin algorithm is
1485 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001486 backend. This algorithm is static by default, which means
1487 that changing a server's weight on the fly will have no
1488 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001489
Cyril Bontédc4d9032012-04-08 21:57:39 +02001490 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
1491 request. Just as with the equivalent ACL 'hdr()' function,
1492 the header name in parenthesis is not case sensitive. If the
1493 header is absent or if it does not contain any value, the
1494 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01001495
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001496 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01001497 reducing the hash algorithm to the main domain part with some
1498 specific headers such as 'Host'. For instance, in the Host
1499 value "haproxy.1wt.eu", only "1wt" will be considered.
1500
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001501 This algorithm is static by default, which means that
1502 changing a server's weight on the fly will have no effect,
1503 but this can be changed using "hash-type".
1504
Emeric Brun736aa232009-06-30 17:56:00 +02001505 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02001506 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02001507 The RDP cookie <name> (or "mstshash" if omitted) will be
1508 looked up and hashed for each incoming TCP request. Just as
1509 with the equivalent ACL 'req_rdp_cookie()' function, the name
1510 is not case-sensitive. This mechanism is useful as a degraded
1511 persistence mode, as it makes it possible to always send the
1512 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001513 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02001514 used instead.
1515
1516 Note that for this to work, the frontend must ensure that an
1517 RDP cookie is already present in the request buffer. For this
1518 you must use 'tcp-request content accept' rule combined with
1519 a 'req_rdp_cookie_cnt' ACL.
1520
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001521 This algorithm is static by default, which means that
1522 changing a server's weight on the fly will have no effect,
1523 but this can be changed using "hash-type".
1524
Cyril Bontédc4d9032012-04-08 21:57:39 +02001525 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09001526
Willy Tarreau0ba27502007-12-24 16:55:16 +01001527 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001528 algorithms. Right now, only "url_param" and "uri" support an
1529 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001530
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001531 balance uri [len <len>] [depth <depth>]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001532 balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001533
Willy Tarreau3cd9af22009-03-15 14:06:41 +01001534 The load balancing algorithm of a backend is set to roundrobin when no other
1535 algorithm, mode nor option have been set. The algorithm may only be set once
1536 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001537
1538 Examples :
1539 balance roundrobin
1540 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001541 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01001542 balance hdr(User-Agent)
1543 balance hdr(host)
1544 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001545
1546 Note: the following caveats and limitations on using the "check_post"
1547 extension with "url_param" must be considered :
1548
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001549 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001550 to determine if the parameters will be found in the body or entity which
1551 may contain binary data. Therefore another method may be required to
1552 restrict consideration of POST requests that have no URL parameters in
1553 the body. (see acl reqideny http_end)
1554
1555 - using a <max_wait> value larger than the request buffer size does not
1556 make sense and is useless. The buffer size is set at build time, and
1557 defaults to 16 kB.
1558
1559 - Content-Encoding is not supported, the parameter search will probably
1560 fail; and load balancing will fall back to Round Robin.
1561
1562 - Expect: 100-continue is not supported, load balancing will fall back to
1563 Round Robin.
1564
1565 - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk.
1566 If the entire parameter value is not present in the first chunk, the
1567 selection of server is undefined (actually, defined by how little
1568 actually appeared in the first chunk).
1569
1570 - This feature does not support generation of a 100, 411 or 501 response.
1571
1572 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001573 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001574 white space or control characters are found, indicating the end of what
1575 might be a URL parameter list. This is probably not a concern with SGML
1576 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001577
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001578 See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and
1579 "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001580
1581
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001582bind [<address>]:<port_range> [, ...] [param*]
1583bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001584 Define one or several listening addresses and/or ports in a frontend.
1585 May be used in sections : defaults | frontend | listen | backend
1586 no | yes | yes | no
1587 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001588 <address> is optional and can be a host name, an IPv4 address, an IPv6
1589 address, or '*'. It designates the address the frontend will
1590 listen on. If unset, all IPv4 addresses of the system will be
1591 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01001592 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001593
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001594 <port_range> is either a unique TCP port, or a port range for which the
1595 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001596 above. The port is mandatory for TCP listeners. Note that in
1597 the case of an IPv6 address, the port is always the number
1598 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001599 - a numerical port (ex: '80')
1600 - a dash-delimited ports range explicitly stating the lower
1601 and upper bounds (ex: '2000-2100') which are included in
1602 the range.
1603
1604 Particular care must be taken against port ranges, because
1605 every <address:port> couple consumes one socket (= a file
1606 descriptor), so it's easy to consume lots of descriptors
1607 with a simple range, and to run out of sockets. Also, each
1608 <address:port> couple must be used only once among all
1609 instances running on a same system. Please note that binding
1610 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001611 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001612 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001613
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001614 <path> is a UNIX socket path beginning with a slash ('/'). This is
1615 alternative to the TCP listening port. Haproxy will then
1616 receive UNIX connections on the socket located at this place.
1617 The path must begin with a slash and by default is absolute.
1618 It can be relative to the prefix defined by "unix-bind" in
1619 the global section. Note that the total length of the prefix
1620 followed by the socket path cannot exceed some system limits
1621 for UNIX sockets, which commonly are set to 107 characters.
1622
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001623 <param*> is a list of parameters common to all sockets declared on the
1624 same line. These numerous parameters depend on OS and build
1625 options and have a complete section dedicated to them. Please
1626 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001627
Willy Tarreau0ba27502007-12-24 16:55:16 +01001628 It is possible to specify a list of address:port combinations delimited by
1629 commas. The frontend will then listen on all of these addresses. There is no
1630 fixed limit to the number of addresses and ports which can be listened on in
1631 a frontend, as well as there is no limit to the number of "bind" statements
1632 in a frontend.
1633
1634 Example :
1635 listen http_proxy
1636 bind :80,:443
1637 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001638 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01001639
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001640 listen http_https_proxy
1641 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02001642 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001643
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001644 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001645 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001646
1647
Willy Tarreau110ecc12012-11-15 17:50:01 +01001648bind-process [ all | odd | even | <number 1-32>[-<number 1-32>] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001649 Limit visibility of an instance to a certain set of processes numbers.
1650 May be used in sections : defaults | frontend | listen | backend
1651 yes | yes | yes | yes
1652 Arguments :
1653 all All process will see this instance. This is the default. It
1654 may be used to override a default value.
1655
1656 odd This instance will be enabled on processes 1,3,5,...31. This
1657 option may be combined with other numbers.
1658
1659 even This instance will be enabled on processes 2,4,6,...32. This
1660 option may be combined with other numbers. Do not use it
1661 with less than 2 processes otherwise some instances might be
1662 missing from all processes.
1663
Willy Tarreau110ecc12012-11-15 17:50:01 +01001664 number The instance will be enabled on this process number or range,
1665 whose values must all be between 1 and 32. You must be
1666 careful not to reference a process number greater than the
1667 configured global.nbproc, otherwise some instances might be
1668 missing from all processes.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001669
1670 This keyword limits binding of certain instances to certain processes. This
1671 is useful in order not to have too many processes listening to the same
1672 ports. For instance, on a dual-core machine, it might make sense to set
1673 'nbproc 2' in the global section, then distributes the listeners among 'odd'
1674 and 'even' instances.
1675
1676 At the moment, it is not possible to reference more than 32 processes using
1677 this keyword, but this should be more than enough for most setups. Please
1678 note that 'all' really means all processes and is not limited to the first
1679 32.
1680
1681 If some backends are referenced by frontends bound to other processes, the
1682 backend automatically inherits the frontend's processes.
1683
1684 Example :
1685 listen app_ip1
1686 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001687 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001688
1689 listen app_ip2
1690 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001691 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001692
1693 listen management
1694 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001695 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001696
Willy Tarreau110ecc12012-11-15 17:50:01 +01001697 listen management
1698 bind 10.0.0.4:80
1699 bind-process 1-4
1700
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001701 See also : "nbproc" in global section.
1702
1703
Willy Tarreau0ba27502007-12-24 16:55:16 +01001704block { if | unless } <condition>
1705 Block a layer 7 request if/unless a condition is matched
1706 May be used in sections : defaults | frontend | listen | backend
1707 no | yes | yes | yes
1708
1709 The HTTP request will be blocked very early in the layer 7 processing
1710 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001711 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02001712 typically used to deny access to certain sensitive resources if some
Willy Tarreau0ba27502007-12-24 16:55:16 +01001713 conditions are met or not met. There is no fixed limit to the number of
1714 "block" statements per instance.
1715
1716 Example:
1717 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1718 acl invalid_src src_port 0:1023
1719 acl local_dst hdr(host) -i localhost
1720 block if invalid_src || local_dst
1721
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001722 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001723
1724
1725capture cookie <name> len <length>
1726 Capture and log a cookie in the request and in the response.
1727 May be used in sections : defaults | frontend | listen | backend
1728 no | yes | yes | no
1729 Arguments :
1730 <name> is the beginning of the name of the cookie to capture. In order
1731 to match the exact name, simply suffix the name with an equal
1732 sign ('='). The full name will appear in the logs, which is
1733 useful with application servers which adjust both the cookie name
1734 and value (eg: ASPSESSIONXXXXX).
1735
1736 <length> is the maximum number of characters to report in the logs, which
1737 include the cookie name, the equal sign and the value, all in the
1738 standard "name=value" form. The string will be truncated on the
1739 right if it exceeds <length>.
1740
1741 Only the first cookie is captured. Both the "cookie" request headers and the
1742 "set-cookie" response headers are monitored. This is particularly useful to
1743 check for application bugs causing session crossing or stealing between
1744 users, because generally the user's cookies can only change on a login page.
1745
1746 When the cookie was not presented by the client, the associated log column
1747 will report "-". When a request does not cause a cookie to be assigned by the
1748 server, a "-" is reported in the response column.
1749
1750 The capture is performed in the frontend only because it is necessary that
1751 the log format does not change for a given frontend depending on the
1752 backends. This may change in the future. Note that there can be only one
Willy Tarreau193b8c62012-11-22 00:17:38 +01001753 "capture cookie" statement in a frontend. The maximum capture length is set
1754 by the global "tune.http.cookielen" setting and defaults to 63 characters. It
1755 is not possible to specify a capture in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001756
1757 Example:
1758 capture cookie ASPSESSION len 32
1759
1760 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001761 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001762
1763
1764capture request header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01001765 Capture and log the last occurrence of the specified request header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001766 May be used in sections : defaults | frontend | listen | backend
1767 no | yes | yes | no
1768 Arguments :
1769 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001770 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001771 appear in the requests, with the first letter of each word in
1772 upper case. The header name will not appear in the logs, only the
1773 value is reported, but the position in the logs is respected.
1774
1775 <length> is the maximum number of characters to extract from the value and
1776 report in the logs. The string will be truncated on the right if
1777 it exceeds <length>.
1778
Willy Tarreau4460d032012-11-21 23:37:37 +01001779 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001780 value will be added to the logs between braces ('{}'). If multiple headers
1781 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001782 in the same order they were declared in the configuration. Non-existent
1783 headers will be logged just as an empty string. Common uses for request
1784 header captures include the "Host" field in virtual hosting environments, the
1785 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001786 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001787 environments to find where the request came from.
1788
1789 Note that when capturing headers such as "User-agent", some spaces may be
1790 logged, making the log analysis more difficult. Thus be careful about what
1791 you log if you know your log parser is not smart enough to rely on the
1792 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001793
Willy Tarreau0900abb2012-11-22 00:21:46 +01001794 There is no limit to the number of captured request headers nor to their
1795 length, though it is wise to keep them low to limit memory usage per session.
1796 In order to keep log format consistent for a same frontend, header captures
1797 can only be declared in a frontend. It is not possible to specify a capture
1798 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001799
1800 Example:
1801 capture request header Host len 15
1802 capture request header X-Forwarded-For len 15
1803 capture request header Referrer len 15
1804
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001805 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001806 about logging.
1807
1808
1809capture response header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01001810 Capture and log the last occurrence of the specified response header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001811 May be used in sections : defaults | frontend | listen | backend
1812 no | yes | yes | no
1813 Arguments :
1814 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001815 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001816 appear in the response, with the first letter of each word in
1817 upper case. The header name will not appear in the logs, only the
1818 value is reported, but the position in the logs is respected.
1819
1820 <length> is the maximum number of characters to extract from the value and
1821 report in the logs. The string will be truncated on the right if
1822 it exceeds <length>.
1823
Willy Tarreau4460d032012-11-21 23:37:37 +01001824 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001825 result will be added to the logs between braces ('{}') after the captured
1826 request headers. If multiple headers are captured, they will be delimited by
1827 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001828 the configuration. Non-existent headers will be logged just as an empty
1829 string. Common uses for response header captures include the "Content-length"
1830 header which indicates how many bytes are expected to be returned, the
1831 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001832
Willy Tarreau0900abb2012-11-22 00:21:46 +01001833 There is no limit to the number of captured response headers nor to their
1834 length, though it is wise to keep them low to limit memory usage per session.
1835 In order to keep log format consistent for a same frontend, header captures
1836 can only be declared in a frontend. It is not possible to specify a capture
1837 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001838
1839 Example:
1840 capture response header Content-length len 9
1841 capture response header Location len 15
1842
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001843 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001844 about logging.
1845
1846
Cyril Bontéf0c60612010-02-06 14:44:47 +01001847clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01001848 Set the maximum inactivity time on the client side.
1849 May be used in sections : defaults | frontend | listen | backend
1850 yes | yes | yes | no
1851 Arguments :
1852 <timeout> is the timeout value is specified in milliseconds by default, but
1853 can be in any other unit if the number is suffixed by the unit,
1854 as explained at the top of this document.
1855
1856 The inactivity timeout applies when the client is expected to acknowledge or
1857 send data. In HTTP mode, this timeout is particularly important to consider
1858 during the first phase, when the client sends the request, and during the
1859 response while it is reading data sent by the server. The value is specified
1860 in milliseconds by default, but can be in any other unit if the number is
1861 suffixed by the unit, as specified at the top of this document. In TCP mode
1862 (and to a lesser extent, in HTTP mode), it is highly recommended that the
1863 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001864 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01001865 losses by specifying timeouts that are slightly above multiples of 3 seconds
1866 (eg: 4 or 5 seconds).
1867
1868 This parameter is specific to frontends, but can be specified once for all in
1869 "defaults" sections. This is in fact one of the easiest solutions not to
1870 forget about it. An unspecified timeout results in an infinite timeout, which
1871 is not recommended. Such a usage is accepted and works but reports a warning
1872 during startup because it may results in accumulation of expired sessions in
1873 the system if the system's timeouts are not configured either.
1874
1875 This parameter is provided for compatibility but is currently deprecated.
1876 Please use "timeout client" instead.
1877
Willy Tarreau036fae02008-01-06 13:24:40 +01001878 See also : "timeout client", "timeout http-request", "timeout server", and
1879 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001880
Cyril Bonté316a8cf2012-11-11 13:38:27 +01001881compression algo <algorithm> ...
1882compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02001883compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02001884 Enable HTTP compression.
1885 May be used in sections : defaults | frontend | listen | backend
1886 yes | yes | yes | yes
1887 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01001888 algo is followed by the list of supported compression algorithms.
1889 type is followed by the list of MIME types that will be compressed.
1890 offload makes haproxy work as a compression offloader only (see notes).
1891
1892 The currently supported algorithms are :
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04001893 identity this is mostly for debugging, and it was useful for developing
Cyril Bonté316a8cf2012-11-11 13:38:27 +01001894 the compression feature. Identity does not apply any change on
1895 data.
1896
1897 gzip applies gzip compression. This setting is only available when
1898 support for zlib was built in.
1899
1900 deflate same as gzip, but with deflate algorithm and zlib format.
1901 Note that this algorithm has ambiguous support on many browsers
1902 and no support at all from recent ones. It is strongly
1903 recommended not to use it for anything else than experimentation.
1904 This setting is only available when support for zlib was built
1905 in.
1906
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04001907 Compression will be activated depending on the Accept-Encoding request
Cyril Bonté316a8cf2012-11-11 13:38:27 +01001908 header. With identity, it does not take care of that header.
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04001909 If backend servers support HTTP compression, these directives
1910 will be no-op: haproxy will see the compressed response and will not
1911 compress again. If backend servers do not support HTTP compression and
1912 there is Accept-Encoding header in request, haproxy will compress the
1913 matching response.
Willy Tarreau70737d12012-10-27 00:34:28 +02001914
1915 The "offload" setting makes haproxy remove the Accept-Encoding header to
1916 prevent backend servers from compressing responses. It is strongly
1917 recommended not to do this because this means that all the compression work
1918 will be done on the single point where haproxy is located. However in some
1919 deployment scenarios, haproxy may be installed in front of a buggy gateway
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04001920 with broken HTTP compression implementation which can't be turned off.
1921 In that case haproxy can be used to prevent that gateway from emitting
1922 invalid payloads. In this case, simply removing the header in the
1923 configuration does not work because it applies before the header is parsed,
1924 so that prevents haproxy from compressing. The "offload" setting should
1925 then be used for such scenarios.
William Lallemand82fe75c2012-10-23 10:25:10 +02001926
William Lallemand05097442012-11-20 12:14:28 +01001927 Compression is disabled when:
1928 * the server is not HTTP/1.1.
William Lallemandd3002612012-11-26 14:34:47 +01001929 * HTTP status code is not 200
William Lallemand05097442012-11-20 12:14:28 +01001930 * requests does not contain Transfer-Encoding: chunked or Content-Length.
William Lallemandd3002612012-11-26 14:34:47 +01001931 * Content-Type is multipart
William Lallemand05097442012-11-20 12:14:28 +01001932 * the request contains "Cache-control: no-transform".
1933 * User-Agent matches "Mozilla/4" except MSIE 6 with XP SP2, or MSIE 7 and later.
1934 * The response is already compressed (see compression offload).
1935
1936 The compression does not rewrite Etag headers
1937
William Lallemand82fe75c2012-10-23 10:25:10 +02001938 Examples :
1939 compression algo gzip
1940 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01001941
Cyril Bontéf0c60612010-02-06 14:44:47 +01001942contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01001943 Set the maximum time to wait for a connection attempt to a server to succeed.
1944 May be used in sections : defaults | frontend | listen | backend
1945 yes | no | yes | yes
1946 Arguments :
1947 <timeout> is the timeout value is specified in milliseconds by default, but
1948 can be in any other unit if the number is suffixed by the unit,
1949 as explained at the top of this document.
1950
1951 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001952 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01001953 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01001954 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
1955 connect timeout also presets the queue timeout to the same value if this one
1956 has not been specified. Historically, the contimeout was also used to set the
1957 tarpit timeout in a listen section, which is not possible in a pure frontend.
1958
1959 This parameter is specific to backends, but can be specified once for all in
1960 "defaults" sections. This is in fact one of the easiest solutions not to
1961 forget about it. An unspecified timeout results in an infinite timeout, which
1962 is not recommended. Such a usage is accepted and works but reports a warning
1963 during startup because it may results in accumulation of failed sessions in
1964 the system if the system's timeouts are not configured either.
1965
1966 This parameter is provided for backwards compatibility but is currently
1967 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
1968 instead.
1969
1970 See also : "timeout connect", "timeout queue", "timeout tarpit",
1971 "timeout server", "contimeout".
1972
1973
Willy Tarreau55165fe2009-05-10 12:02:55 +02001974cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02001975 [ postonly ] [ preserve ] [ httponly ] [ secure ]
1976 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001977 Enable cookie-based persistence in a backend.
1978 May be used in sections : defaults | frontend | listen | backend
1979 yes | no | yes | yes
1980 Arguments :
1981 <name> is the name of the cookie which will be monitored, modified or
1982 inserted in order to bring persistence. This cookie is sent to
1983 the client via a "Set-Cookie" header in the response, and is
1984 brought back by the client in a "Cookie" header in all requests.
1985 Special care should be taken to choose a name which does not
1986 conflict with any likely application cookie. Also, if the same
1987 backends are subject to be used by the same clients (eg:
1988 HTTP/HTTPS), care should be taken to use different cookie names
1989 between all backends if persistence between them is not desired.
1990
1991 rewrite This keyword indicates that the cookie will be provided by the
1992 server and that haproxy will have to modify its value to set the
1993 server's identifier in it. This mode is handy when the management
1994 of complex combinations of "Set-cookie" and "Cache-control"
1995 headers is left to the application. The application can then
1996 decide whether or not it is appropriate to emit a persistence
1997 cookie. Since all responses should be monitored, this mode only
1998 works in HTTP close mode. Unless the application behaviour is
1999 very complex and/or broken, it is advised not to start with this
2000 mode for new deployments. This keyword is incompatible with
2001 "insert" and "prefix".
2002
2003 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02002004 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002005
Willy Tarreaua79094d2010-08-31 22:54:15 +02002006 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002007 server. When used without the "preserve" option, if the server
2008 emits a cookie with the same name, it will be remove before
2009 processing. For this reason, this mode can be used to upgrade
2010 existing configurations running in the "rewrite" mode. The cookie
2011 will only be a session cookie and will not be stored on the
2012 client's disk. By default, unless the "indirect" option is added,
2013 the server will see the cookies emitted by the client. Due to
2014 caching effects, it is generally wise to add the "nocache" or
2015 "postonly" keywords (see below). The "insert" keyword is not
2016 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002017
2018 prefix This keyword indicates that instead of relying on a dedicated
2019 cookie for the persistence, an existing one will be completed.
2020 This may be needed in some specific environments where the client
2021 does not support more than one single cookie and the application
2022 already needs it. In this case, whenever the server sets a cookie
2023 named <name>, it will be prefixed with the server's identifier
2024 and a delimiter. The prefix will be removed from all client
2025 requests so that the server still finds the cookie it emitted.
2026 Since all requests and responses are subject to being modified,
2027 this mode requires the HTTP close mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02002028 not compatible with "rewrite" and "insert". Note: it is highly
2029 recommended not to use "indirect" with "prefix", otherwise server
2030 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002031
Willy Tarreaua79094d2010-08-31 22:54:15 +02002032 indirect When this option is specified, no cookie will be emitted to a
2033 client which already has a valid one for the server which has
2034 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002035 it will be removed, unless the "preserve" option is also set. In
2036 "insert" mode, this will additionally remove cookies from the
2037 requests transmitted to the server, making the persistence
2038 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02002039 Note: it is highly recommended not to use "indirect" with
2040 "prefix", otherwise server cookie updates would not be sent to
2041 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002042
2043 nocache This option is recommended in conjunction with the insert mode
2044 when there is a cache between the client and HAProxy, as it
2045 ensures that a cacheable response will be tagged non-cacheable if
2046 a cookie needs to be inserted. This is important because if all
2047 persistence cookies are added on a cacheable home page for
2048 instance, then all customers will then fetch the page from an
2049 outer cache and will all share the same persistence cookie,
2050 leading to one server receiving much more traffic than others.
2051 See also the "insert" and "postonly" options.
2052
2053 postonly This option ensures that cookie insertion will only be performed
2054 on responses to POST requests. It is an alternative to the
2055 "nocache" option, because POST responses are not cacheable, so
2056 this ensures that the persistence cookie will never get cached.
2057 Since most sites do not need any sort of persistence before the
2058 first POST which generally is a login request, this is a very
2059 efficient method to optimize caching without risking to find a
2060 persistence cookie in the cache.
2061 See also the "insert" and "nocache" options.
2062
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002063 preserve This option may only be used with "insert" and/or "indirect". It
2064 allows the server to emit the persistence cookie itself. In this
2065 case, if a cookie is found in the response, haproxy will leave it
2066 untouched. This is useful in order to end persistence after a
2067 logout request for instance. For this, the server just has to
2068 emit a cookie with an invalid value (eg: empty) or with a date in
2069 the past. By combining this mechanism with the "disable-on-404"
2070 check option, it is possible to perform a completely graceful
2071 shutdown because users will definitely leave the server after
2072 they logout.
2073
Willy Tarreau4992dd22012-05-31 21:02:17 +02002074 httponly This option tells haproxy to add an "HttpOnly" cookie attribute
2075 when a cookie is inserted. This attribute is used so that a
2076 user agent doesn't share the cookie with non-HTTP components.
2077 Please check RFC6265 for more information on this attribute.
2078
2079 secure This option tells haproxy to add a "Secure" cookie attribute when
2080 a cookie is inserted. This attribute is used so that a user agent
2081 never emits this cookie over non-secure channels, which means
2082 that a cookie learned with this flag will be presented only over
2083 SSL/TLS connections. Please check RFC6265 for more information on
2084 this attribute.
2085
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002086 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002087 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01002088 name. If the domain begins with a dot, the browser is allowed to
2089 use it for any host ending with that name. It is also possible to
2090 specify several domain names by invoking this option multiple
2091 times. Some browsers might have small limits on the number of
2092 domains, so be careful when doing that. For the record, sending
2093 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002094
Willy Tarreau996a92c2010-10-13 19:30:47 +02002095 maxidle This option allows inserted cookies to be ignored after some idle
2096 time. It only works with insert-mode cookies. When a cookie is
2097 sent to the client, the date this cookie was emitted is sent too.
2098 Upon further presentations of this cookie, if the date is older
2099 than the delay indicated by the parameter (in seconds), it will
2100 be ignored. Otherwise, it will be refreshed if needed when the
2101 response is sent to the client. This is particularly useful to
2102 prevent users who never close their browsers from remaining for
2103 too long on the same server (eg: after a farm size change). When
2104 this option is set and a cookie has no date, it is always
2105 accepted, but gets refreshed in the response. This maintains the
2106 ability for admins to access their sites. Cookies that have a
2107 date in the future further than 24 hours are ignored. Doing so
2108 lets admins fix timezone issues without risking kicking users off
2109 the site.
2110
2111 maxlife This option allows inserted cookies to be ignored after some life
2112 time, whether they're in use or not. It only works with insert
2113 mode cookies. When a cookie is first sent to the client, the date
2114 this cookie was emitted is sent too. Upon further presentations
2115 of this cookie, if the date is older than the delay indicated by
2116 the parameter (in seconds), it will be ignored. If the cookie in
2117 the request has no date, it is accepted and a date will be set.
2118 Cookies that have a date in the future further than 24 hours are
2119 ignored. Doing so lets admins fix timezone issues without risking
2120 kicking users off the site. Contrary to maxidle, this value is
2121 not refreshed, only the first visit date counts. Both maxidle and
2122 maxlife may be used at the time. This is particularly useful to
2123 prevent users who never close their browsers from remaining for
2124 too long on the same server (eg: after a farm size change). This
2125 is stronger than the maxidle method in that it forces a
2126 redispatch after some absolute delay.
2127
Willy Tarreau0ba27502007-12-24 16:55:16 +01002128 There can be only one persistence cookie per HTTP backend, and it can be
2129 declared in a defaults section. The value of the cookie will be the value
2130 indicated after the "cookie" keyword in a "server" statement. If no cookie
2131 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002132
Willy Tarreau0ba27502007-12-24 16:55:16 +01002133 Examples :
2134 cookie JSESSIONID prefix
2135 cookie SRV insert indirect nocache
2136 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02002137 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01002138
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002139 See also : "appsession", "balance source", "capture cookie", "server"
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002140 and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002141
Willy Tarreau983e01e2010-01-11 18:42:06 +01002142
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002143default-server [param*]
2144 Change default options for a server in a backend
2145 May be used in sections : defaults | frontend | listen | backend
2146 yes | no | yes | yes
2147 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01002148 <param*> is a list of parameters for this server. The "default-server"
2149 keyword accepts an important number of options and has a complete
2150 section dedicated to it. Please refer to section 5 for more
2151 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002152
Willy Tarreau983e01e2010-01-11 18:42:06 +01002153 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002154 default-server inter 1000 weight 13
2155
2156 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01002157
Willy Tarreau983e01e2010-01-11 18:42:06 +01002158
Willy Tarreau0ba27502007-12-24 16:55:16 +01002159default_backend <backend>
2160 Specify the backend to use when no "use_backend" rule has been matched.
2161 May be used in sections : defaults | frontend | listen | backend
2162 yes | yes | yes | no
2163 Arguments :
2164 <backend> is the name of the backend to use.
2165
2166 When doing content-switching between frontend and backends using the
2167 "use_backend" keyword, it is often useful to indicate which backend will be
2168 used when no rule has matched. It generally is the dynamic backend which
2169 will catch all undetermined requests.
2170
Willy Tarreau0ba27502007-12-24 16:55:16 +01002171 Example :
2172
2173 use_backend dynamic if url_dyn
2174 use_backend static if url_css url_img extension_img
2175 default_backend dynamic
2176
Willy Tarreau2769aa02007-12-27 18:26:09 +01002177 See also : "use_backend", "reqsetbe", "reqisetbe"
2178
Willy Tarreau0ba27502007-12-24 16:55:16 +01002179
2180disabled
2181 Disable a proxy, frontend or backend.
2182 May be used in sections : defaults | frontend | listen | backend
2183 yes | yes | yes | yes
2184 Arguments : none
2185
2186 The "disabled" keyword is used to disable an instance, mainly in order to
2187 liberate a listening port or to temporarily disable a service. The instance
2188 will still be created and its configuration will be checked, but it will be
2189 created in the "stopped" state and will appear as such in the statistics. It
2190 will not receive any traffic nor will it send any health-checks or logs. It
2191 is possible to disable many instances at once by adding the "disabled"
2192 keyword in a "defaults" section.
2193
2194 See also : "enabled"
2195
2196
Willy Tarreau5ce94572010-06-07 14:35:41 +02002197dispatch <address>:<port>
2198 Set a default server address
2199 May be used in sections : defaults | frontend | listen | backend
2200 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002201 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02002202
2203 <address> is the IPv4 address of the default server. Alternatively, a
2204 resolvable hostname is supported, but this name will be resolved
2205 during start-up.
2206
2207 <ports> is a mandatory port specification. All connections will be sent
2208 to this port, and it is not permitted to use port offsets as is
2209 possible with normal servers.
2210
Willy Tarreau787aed52011-04-15 06:45:37 +02002211 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02002212 server can take the connection. In the past it was used to forward non
2213 persistent connections to an auxiliary load balancer. Due to its simple
2214 syntax, it has also been used for simple TCP relays. It is recommended not to
2215 use it for more clarity, and to use the "server" directive instead.
2216
2217 See also : "server"
2218
2219
Willy Tarreau0ba27502007-12-24 16:55:16 +01002220enabled
2221 Enable a proxy, frontend or backend.
2222 May be used in sections : defaults | frontend | listen | backend
2223 yes | yes | yes | yes
2224 Arguments : none
2225
2226 The "enabled" keyword is used to explicitly enable an instance, when the
2227 defaults has been set to "disabled". This is very rarely used.
2228
2229 See also : "disabled"
2230
2231
2232errorfile <code> <file>
2233 Return a file contents instead of errors generated by HAProxy
2234 May be used in sections : defaults | frontend | listen | backend
2235 yes | yes | yes | yes
2236 Arguments :
2237 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002238 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002239
2240 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002241 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01002242 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01002243 error pages, and to use absolute paths, since files are read
2244 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002245
2246 It is important to understand that this keyword is not meant to rewrite
2247 errors returned by the server, but errors detected and returned by HAProxy.
2248 This is why the list of supported errors is limited to a small set.
2249
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002250 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2251
Willy Tarreau0ba27502007-12-24 16:55:16 +01002252 The files are returned verbatim on the TCP socket. This allows any trick such
2253 as redirections to another URL or site, as well as tricks to clean cookies,
2254 force enable or disable caching, etc... The package provides default error
2255 files returning the same contents as default errors.
2256
Willy Tarreau59140a22009-02-22 12:02:30 +01002257 The files should not exceed the configured buffer size (BUFSIZE), which
2258 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
2259 not to put any reference to local contents (eg: images) in order to avoid
2260 loops between the client and HAProxy when all servers are down, causing an
2261 error to be returned instead of an image. For better HTTP compliance, it is
2262 recommended that all header lines end with CR-LF and not LF alone.
2263
Willy Tarreau0ba27502007-12-24 16:55:16 +01002264 The files are read at the same time as the configuration and kept in memory.
2265 For this reason, the errors continue to be returned even when the process is
2266 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01002267 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002268 403 status code and interrogating a blocked URL.
2269
2270 See also : "errorloc", "errorloc302", "errorloc303"
2271
Willy Tarreau59140a22009-02-22 12:02:30 +01002272 Example :
2273 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
2274 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
2275 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
2276
Willy Tarreau2769aa02007-12-27 18:26:09 +01002277
2278errorloc <code> <url>
2279errorloc302 <code> <url>
2280 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2281 May be used in sections : defaults | frontend | listen | backend
2282 yes | yes | yes | yes
2283 Arguments :
2284 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002285 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002286
2287 <url> it is the exact contents of the "Location" header. It may contain
2288 either a relative URI to an error page hosted on the same site,
2289 or an absolute URI designating an error page on another site.
2290 Special care should be given to relative URIs to avoid redirect
2291 loops if the URI itself may generate the same error (eg: 500).
2292
2293 It is important to understand that this keyword is not meant to rewrite
2294 errors returned by the server, but errors detected and returned by HAProxy.
2295 This is why the list of supported errors is limited to a small set.
2296
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002297 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2298
Willy Tarreau2769aa02007-12-27 18:26:09 +01002299 Note that both keyword return the HTTP 302 status code, which tells the
2300 client to fetch the designated URL using the same HTTP method. This can be
2301 quite problematic in case of non-GET methods such as POST, because the URL
2302 sent to the client might not be allowed for something other than GET. To
2303 workaround this problem, please use "errorloc303" which send the HTTP 303
2304 status code, indicating to the client that the URL must be fetched with a GET
2305 request.
2306
2307 See also : "errorfile", "errorloc303"
2308
2309
2310errorloc303 <code> <url>
2311 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2312 May be used in sections : defaults | frontend | listen | backend
2313 yes | yes | yes | yes
2314 Arguments :
2315 <code> is the HTTP status code. Currently, HAProxy is capable of
2316 generating codes 400, 403, 408, 500, 502, 503, and 504.
2317
2318 <url> it is the exact contents of the "Location" header. It may contain
2319 either a relative URI to an error page hosted on the same site,
2320 or an absolute URI designating an error page on another site.
2321 Special care should be given to relative URIs to avoid redirect
2322 loops if the URI itself may generate the same error (eg: 500).
2323
2324 It is important to understand that this keyword is not meant to rewrite
2325 errors returned by the server, but errors detected and returned by HAProxy.
2326 This is why the list of supported errors is limited to a small set.
2327
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002328 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2329
Willy Tarreau2769aa02007-12-27 18:26:09 +01002330 Note that both keyword return the HTTP 303 status code, which tells the
2331 client to fetch the designated URL using the same HTTP GET method. This
2332 solves the usual problems associated with "errorloc" and the 302 code. It is
2333 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002334 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002335
2336 See also : "errorfile", "errorloc", "errorloc302"
2337
2338
Willy Tarreau4de91492010-01-22 19:10:05 +01002339force-persist { if | unless } <condition>
2340 Declare a condition to force persistence on down servers
2341 May be used in sections: defaults | frontend | listen | backend
2342 no | yes | yes | yes
2343
2344 By default, requests are not dispatched to down servers. It is possible to
2345 force this using "option persist", but it is unconditional and redispatches
2346 to a valid server if "option redispatch" is set. That leaves with very little
2347 possibilities to force some requests to reach a server which is artificially
2348 marked down for maintenance operations.
2349
2350 The "force-persist" statement allows one to declare various ACL-based
2351 conditions which, when met, will cause a request to ignore the down status of
2352 a server and still try to connect to it. That makes it possible to start a
2353 server, still replying an error to the health checks, and run a specially
2354 configured browser to test the service. Among the handy methods, one could
2355 use a specific source IP address, or a specific cookie. The cookie also has
2356 the advantage that it can easily be added/removed on the browser from a test
2357 page. Once the service is validated, it is then possible to open the service
2358 to the world by returning a valid response to health checks.
2359
2360 The forced persistence is enabled when an "if" condition is met, or unless an
2361 "unless" condition is met. The final redispatch is always disabled when this
2362 is used.
2363
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002364 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002365 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01002366
2367
Willy Tarreau2769aa02007-12-27 18:26:09 +01002368fullconn <conns>
2369 Specify at what backend load the servers will reach their maxconn
2370 May be used in sections : defaults | frontend | listen | backend
2371 yes | no | yes | yes
2372 Arguments :
2373 <conns> is the number of connections on the backend which will make the
2374 servers use the maximal number of connections.
2375
Willy Tarreau198a7442008-01-17 12:05:32 +01002376 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01002377 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01002378 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01002379 load. The server will then always accept at least <minconn> connections,
2380 never more than <maxconn>, and the limit will be on the ramp between both
2381 values when the backend has less than <conns> concurrent connections. This
2382 makes it possible to limit the load on the servers during normal loads, but
2383 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002384 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002385
Willy Tarreaufbb78422011-06-05 15:38:35 +02002386 Since it's hard to get this value right, haproxy automatically sets it to
2387 10% of the sum of the maxconns of all frontends that may branch to this
2388 backend. That way it's safe to leave it unset.
2389
Willy Tarreau2769aa02007-12-27 18:26:09 +01002390 Example :
2391 # The servers will accept between 100 and 1000 concurrent connections each
2392 # and the maximum of 1000 will be reached when the backend reaches 10000
2393 # connections.
2394 backend dynamic
2395 fullconn 10000
2396 server srv1 dyn1:80 minconn 100 maxconn 1000
2397 server srv2 dyn2:80 minconn 100 maxconn 1000
2398
2399 See also : "maxconn", "server"
2400
2401
2402grace <time>
2403 Maintain a proxy operational for some time after a soft stop
2404 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01002405 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01002406 Arguments :
2407 <time> is the time (by default in milliseconds) for which the instance
2408 will remain operational with the frontend sockets still listening
2409 when a soft-stop is received via the SIGUSR1 signal.
2410
2411 This may be used to ensure that the services disappear in a certain order.
2412 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002413 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01002414 needed by the equipment to detect the failure.
2415
2416 Note that currently, there is very little benefit in using this parameter,
2417 and it may in fact complicate the soft-reconfiguration process more than
2418 simplify it.
2419
Willy Tarreau0ba27502007-12-24 16:55:16 +01002420
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002421hash-type <method>
2422 Specify a method to use for mapping hashes to servers
2423 May be used in sections : defaults | frontend | listen | backend
2424 yes | no | yes | yes
2425 Arguments :
2426 map-based the hash table is a static array containing all alive servers.
2427 The hashes will be very smooth, will consider weights, but will
2428 be static in that weight changes while a server is up will be
2429 ignored. This means that there will be no slow start. Also,
2430 since a server is selected by its position in the array, most
2431 mappings are changed when the server count changes. This means
2432 that when a server goes up or down, or when a server is added
2433 to a farm, most connections will be redistributed to different
2434 servers. This can be inconvenient with caches for instance.
2435
Willy Tarreau798a39c2010-11-24 15:04:29 +01002436 avalanche this mechanism uses the default map-based hashing described
2437 above but applies a full avalanche hash before performing the
2438 mapping. The result is a slightly less smooth hash for most
2439 situations, but the hash becomes better than pure map-based
2440 hashes when the number of servers is a multiple of the size of
2441 the input set. When using URI hash with a number of servers
2442 multiple of 64, it's desirable to change the hash type to
2443 this value.
2444
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002445 consistent the hash table is a tree filled with many occurrences of each
2446 server. The hash key is looked up in the tree and the closest
2447 server is chosen. This hash is dynamic, it supports changing
2448 weights while the servers are up, so it is compatible with the
2449 slow start feature. It has the advantage that when a server
2450 goes up or down, only its associations are moved. When a server
2451 is added to the farm, only a few part of the mappings are
2452 redistributed, making it an ideal algorithm for caches.
2453 However, due to its principle, the algorithm will never be very
2454 smooth and it may sometimes be necessary to adjust a server's
2455 weight or its ID to get a more balanced distribution. In order
2456 to get the same distribution on multiple load balancers, it is
2457 important that all servers have the same IDs.
2458
2459 The default hash type is "map-based" and is recommended for most usages.
2460
2461 See also : "balance", "server"
2462
2463
Willy Tarreau0ba27502007-12-24 16:55:16 +01002464http-check disable-on-404
2465 Enable a maintenance mode upon HTTP/404 response to health-checks
2466 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01002467 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01002468 Arguments : none
2469
2470 When this option is set, a server which returns an HTTP code 404 will be
2471 excluded from further load-balancing, but will still receive persistent
2472 connections. This provides a very convenient method for Web administrators
2473 to perform a graceful shutdown of their servers. It is also important to note
2474 that a server which is detected as failed while it was in this mode will not
2475 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
2476 will immediately be reinserted into the farm. The status on the stats page
2477 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01002478 option only works in conjunction with the "httpchk" option. If this option
2479 is used with "http-check expect", then it has precedence over it so that 404
2480 responses will still be considered as soft-stop.
2481
2482 See also : "option httpchk", "http-check expect"
2483
2484
2485http-check expect [!] <match> <pattern>
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002486 Make HTTP health checks consider response contents or specific status codes
Willy Tarreaubd741542010-03-16 18:46:54 +01002487 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau1ee51a62011-08-19 20:04:17 +02002488 yes | no | yes | yes
Willy Tarreaubd741542010-03-16 18:46:54 +01002489 Arguments :
2490 <match> is a keyword indicating how to look for a specific pattern in the
2491 response. The keyword may be one of "status", "rstatus",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002492 "string", or "rstring". The keyword may be preceded by an
Willy Tarreaubd741542010-03-16 18:46:54 +01002493 exclamation mark ("!") to negate the match. Spaces are allowed
2494 between the exclamation mark and the keyword. See below for more
2495 details on the supported keywords.
2496
2497 <pattern> is the pattern to look for. It may be a string or a regular
2498 expression. If the pattern contains spaces, they must be escaped
2499 with the usual backslash ('\').
2500
2501 By default, "option httpchk" considers that response statuses 2xx and 3xx
2502 are valid, and that others are invalid. When "http-check expect" is used,
2503 it defines what is considered valid or invalid. Only one "http-check"
2504 statement is supported in a backend. If a server fails to respond or times
2505 out, the check obviously fails. The available matches are :
2506
2507 status <string> : test the exact string match for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002508 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002509 response's status code is exactly this string. If the
2510 "status" keyword is prefixed with "!", then the response
2511 will be considered invalid if the status code matches.
2512
2513 rstatus <regex> : test a regular expression for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002514 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002515 response's status code matches the expression. If the
2516 "rstatus" keyword is prefixed with "!", then the response
2517 will be considered invalid if the status code matches.
2518 This is mostly used to check for multiple codes.
2519
2520 string <string> : test the exact string match in the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002521 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002522 response's body contains this exact string. If the
2523 "string" keyword is prefixed with "!", then the response
2524 will be considered invalid if the body contains this
2525 string. This can be used to look for a mandatory word at
2526 the end of a dynamic page, or to detect a failure when a
2527 specific error appears on the check page (eg: a stack
2528 trace).
2529
2530 rstring <regex> : test a regular expression on the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002531 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002532 response's body matches this expression. If the "rstring"
2533 keyword is prefixed with "!", then the response will be
2534 considered invalid if the body matches the expression.
2535 This can be used to look for a mandatory word at the end
2536 of a dynamic page, or to detect a failure when a specific
2537 error appears on the check page (eg: a stack trace).
2538
2539 It is important to note that the responses will be limited to a certain size
2540 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
2541 Thus, too large responses may not contain the mandatory pattern when using
2542 "string" or "rstring". If a large response is absolutely required, it is
2543 possible to change the default max size by setting the global variable.
2544 However, it is worth keeping in mind that parsing very large responses can
2545 waste some CPU cycles, especially when regular expressions are used, and that
2546 it is always better to focus the checks on smaller resources.
2547
2548 Last, if "http-check expect" is combined with "http-check disable-on-404",
2549 then this last one has precedence when the server responds with 404.
2550
2551 Examples :
2552 # only accept status 200 as valid
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002553 http-check expect status 200
Willy Tarreaubd741542010-03-16 18:46:54 +01002554
2555 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002556 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01002557
2558 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002559 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01002560
2561 # check that we have a correct hexadecimal tag before /html
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002562 http-check expect rstring <!--tag:[0-9a-f]*</html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01002563
Willy Tarreaubd741542010-03-16 18:46:54 +01002564 See also : "option httpchk", "http-check disable-on-404"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002565
2566
Willy Tarreauef781042010-01-27 11:53:01 +01002567http-check send-state
2568 Enable emission of a state header with HTTP health checks
2569 May be used in sections : defaults | frontend | listen | backend
2570 yes | no | yes | yes
2571 Arguments : none
2572
2573 When this option is set, haproxy will systematically send a special header
2574 "X-Haproxy-Server-State" with a list of parameters indicating to each server
2575 how they are seen by haproxy. This can be used for instance when a server is
2576 manipulated without access to haproxy and the operator needs to know whether
2577 haproxy still sees it up or not, or if the server is the last one in a farm.
2578
2579 The header is composed of fields delimited by semi-colons, the first of which
2580 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
2581 checks on the total number before transition, just as appears in the stats
2582 interface. Next headers are in the form "<variable>=<value>", indicating in
2583 no specific order some values available in the stats interface :
2584 - a variable "name", containing the name of the backend followed by a slash
2585 ("/") then the name of the server. This can be used when a server is
2586 checked in multiple backends.
2587
2588 - a variable "node" containing the name of the haproxy node, as set in the
2589 global "node" variable, otherwise the system's hostname if unspecified.
2590
2591 - a variable "weight" indicating the weight of the server, a slash ("/")
2592 and the total weight of the farm (just counting usable servers). This
2593 helps to know if other servers are available to handle the load when this
2594 one fails.
2595
2596 - a variable "scur" indicating the current number of concurrent connections
2597 on the server, followed by a slash ("/") then the total number of
2598 connections on all servers of the same backend.
2599
2600 - a variable "qcur" indicating the current number of requests in the
2601 server's queue.
2602
2603 Example of a header received by the application server :
2604 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
2605 scur=13/22; qcur=0
2606
2607 See also : "option httpchk", "http-check disable-on-404"
2608
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002609http-request { allow | deny | auth [realm <realm>] }
Cyril Bontéf0c60612010-02-06 14:44:47 +01002610 [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002611 Access control for Layer 7 requests
2612
2613 May be used in sections: defaults | frontend | listen | backend
2614 no | yes | yes | yes
2615
2616 These set of options allow to fine control access to a
2617 frontend/listen/backend. Each option may be followed by if/unless and acl.
2618 First option with matched condition (or option without condition) is final.
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002619 For "deny" a 403 error will be returned, for "allow" normal processing is
2620 performed, for "auth" a 401/407 error code is returned so the client
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002621 should be asked to enter a username and password.
2622
2623 There is no fixed limit to the number of http-request statements per
2624 instance.
2625
2626 Example:
Cyril Bonté78caf842010-03-10 22:41:43 +01002627 acl nagios src 192.168.129.3
2628 acl local_net src 192.168.0.0/16
2629 acl auth_ok http_auth(L1)
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002630
Cyril Bonté78caf842010-03-10 22:41:43 +01002631 http-request allow if nagios
2632 http-request allow if local_net auth_ok
2633 http-request auth realm Gimme if local_net auth_ok
2634 http-request deny
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002635
Cyril Bonté78caf842010-03-10 22:41:43 +01002636 Example:
2637 acl auth_ok http_auth_group(L1) G1
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002638
Cyril Bonté78caf842010-03-10 22:41:43 +01002639 http-request auth unless auth_ok
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002640
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002641 See also : "stats http-request", section 3.4 about userlists and section 7
2642 about ACL usage.
Willy Tarreauef781042010-01-27 11:53:01 +01002643
Mark Lamourinec2247f02012-01-04 13:02:01 -05002644http-send-name-header [<header>]
2645 Add the server name to a request. Use the header string given by <header>
2646
2647 May be used in sections: defaults | frontend | listen | backend
2648 yes | no | yes | yes
2649
2650 Arguments :
2651
2652 <header> The header string to use to send the server name
2653
2654 The "http-send-name-header" statement causes the name of the target
2655 server to be added to the headers of an HTTP request. The name
2656 is added with the header string proved.
2657
2658 See also : "server"
2659
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01002660id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02002661 Set a persistent ID to a proxy.
2662 May be used in sections : defaults | frontend | listen | backend
2663 no | yes | yes | yes
2664 Arguments : none
2665
2666 Set a persistent ID for the proxy. This ID must be unique and positive.
2667 An unused ID will automatically be assigned if unset. The first assigned
2668 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01002669
2670
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002671ignore-persist { if | unless } <condition>
2672 Declare a condition to ignore persistence
2673 May be used in sections: defaults | frontend | listen | backend
2674 no | yes | yes | yes
2675
2676 By default, when cookie persistence is enabled, every requests containing
2677 the cookie are unconditionally persistent (assuming the target server is up
2678 and running).
2679
2680 The "ignore-persist" statement allows one to declare various ACL-based
2681 conditions which, when met, will cause a request to ignore persistence.
2682 This is sometimes useful to load balance requests for static files, which
2683 oftenly don't require persistence. This can also be used to fully disable
2684 persistence for a specific User-Agent (for example, some web crawler bots).
2685
2686 Combined with "appsession", it can also help reduce HAProxy memory usage, as
2687 the appsession table won't grow if persistence is ignored.
2688
2689 The persistence is ignored when an "if" condition is met, or unless an
2690 "unless" condition is met.
2691
2692 See also : "force-persist", "cookie", and section 7 about ACL usage.
2693
2694
Willy Tarreau2769aa02007-12-27 18:26:09 +01002695log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002696log <address> <facility> [<level> [<minlevel>]]
William Lallemand0f99e342011-10-12 17:50:54 +02002697no log
Willy Tarreau2769aa02007-12-27 18:26:09 +01002698 Enable per-instance logging of events and traffic.
2699 May be used in sections : defaults | frontend | listen | backend
2700 yes | yes | yes | yes
William Lallemand0f99e342011-10-12 17:50:54 +02002701
2702 Prefix :
2703 no should be used when the logger list must be flushed. For example,
2704 if you don't want to inherit from the default logger list. This
2705 prefix does not allow arguments.
2706
Willy Tarreau2769aa02007-12-27 18:26:09 +01002707 Arguments :
2708 global should be used when the instance's logging parameters are the
2709 same as the global ones. This is the most common usage. "global"
2710 replaces <address>, <facility> and <level> with those of the log
2711 entries found in the "global" section. Only one "log global"
2712 statement may be used per instance, and this form takes no other
2713 parameter.
2714
2715 <address> indicates where to send the logs. It takes the same format as
2716 for the "global" section's logs, and can be one of :
2717
2718 - An IPv4 address optionally followed by a colon (':') and a UDP
2719 port. If no port is specified, 514 is used by default (the
2720 standard syslog port).
2721
David du Colombier24bb5f52011-03-17 10:40:23 +01002722 - An IPv6 address followed by a colon (':') and optionally a UDP
2723 port. If no port is specified, 514 is used by default (the
2724 standard syslog port).
2725
Willy Tarreau2769aa02007-12-27 18:26:09 +01002726 - A filesystem path to a UNIX domain socket, keeping in mind
2727 considerations for chroot (be sure the path is accessible
2728 inside the chroot) and uid/gid (be sure the path is
2729 appropriately writeable).
2730
2731 <facility> must be one of the 24 standard syslog facilities :
2732
2733 kern user mail daemon auth syslog lpr news
2734 uucp cron auth2 ftp ntp audit alert cron2
2735 local0 local1 local2 local3 local4 local5 local6 local7
2736
2737 <level> is optional and can be specified to filter outgoing messages. By
2738 default, all messages are sent. If a level is specified, only
2739 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002740 will be sent. An optional minimum level can be specified. If it
2741 is set, logs emitted with a more severe level than this one will
2742 be capped to this level. This is used to avoid sending "emerg"
2743 messages on all terminals on some default syslog configurations.
2744 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01002745
2746 emerg alert crit err warning notice info debug
2747
William Lallemand0f99e342011-10-12 17:50:54 +02002748 It is important to keep in mind that it is the frontend which decides what to
2749 log from a connection, and that in case of content switching, the log entries
2750 from the backend will be ignored. Connections are logged at level "info".
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002751
2752 However, backend log declaration define how and where servers status changes
2753 will be logged. Level "notice" will be used to indicate a server going up,
2754 "warning" will be used for termination signals and definitive service
2755 termination, and "alert" will be used for when a server goes down.
2756
2757 Note : According to RFC3164, messages are truncated to 1024 bytes before
2758 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002759
2760 Example :
2761 log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002762 log 127.0.0.1:514 local0 notice # only send important events
2763 log 127.0.0.1:514 local0 notice notice # same but limit output level
Willy Tarreau2769aa02007-12-27 18:26:09 +01002764
William Lallemand48940402012-01-30 16:47:22 +01002765log-format <string>
2766 Allows you to custom a log line.
2767
2768 See also : Custom Log Format (8.2.4)
2769
Willy Tarreau2769aa02007-12-27 18:26:09 +01002770
2771maxconn <conns>
2772 Fix the maximum number of concurrent connections on a frontend
2773 May be used in sections : defaults | frontend | listen | backend
2774 yes | yes | yes | no
2775 Arguments :
2776 <conns> is the maximum number of concurrent connections the frontend will
2777 accept to serve. Excess connections will be queued by the system
2778 in the socket's listen queue and will be served once a connection
2779 closes.
2780
2781 If the system supports it, it can be useful on big sites to raise this limit
2782 very high so that haproxy manages connection queues, instead of leaving the
2783 clients with unanswered connection attempts. This value should not exceed the
2784 global maxconn. Also, keep in mind that a connection contains two buffers
2785 of 8kB each, as well as some other data resulting in about 17 kB of RAM being
2786 consumed per established connection. That means that a medium system equipped
2787 with 1GB of RAM can withstand around 40000-50000 concurrent connections if
2788 properly tuned.
2789
2790 Also, when <conns> is set to large values, it is possible that the servers
2791 are not sized to accept such loads, and for this reason it is generally wise
2792 to assign them some reasonable connection limits.
2793
Vincent Bernat6341be52012-06-27 17:18:30 +02002794 By default, this value is set to 2000.
2795
Willy Tarreau2769aa02007-12-27 18:26:09 +01002796 See also : "server", global section's "maxconn", "fullconn"
2797
2798
2799mode { tcp|http|health }
2800 Set the running mode or protocol of the instance
2801 May be used in sections : defaults | frontend | listen | backend
2802 yes | yes | yes | yes
2803 Arguments :
2804 tcp The instance will work in pure TCP mode. A full-duplex connection
2805 will be established between clients and servers, and no layer 7
2806 examination will be performed. This is the default mode. It
2807 should be used for SSL, SSH, SMTP, ...
2808
2809 http The instance will work in HTTP mode. The client request will be
2810 analyzed in depth before connecting to any server. Any request
2811 which is not RFC-compliant will be rejected. Layer 7 filtering,
2812 processing and switching will be possible. This is the mode which
2813 brings HAProxy most of its value.
2814
2815 health The instance will work in "health" mode. It will just reply "OK"
Willy Tarreau82569f92012-09-27 23:48:56 +02002816 to incoming connections and close the connection. Alternatively,
2817 If the "httpchk" option is set, "HTTP/1.0 200 OK" will be sent
2818 instead. Nothing will be logged in either case. This mode is used
2819 to reply to external components health checks. This mode is
2820 deprecated and should not be used anymore as it is possible to do
2821 the same and even better by combining TCP or HTTP modes with the
2822 "monitor" keyword.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002823
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002824 When doing content switching, it is mandatory that the frontend and the
2825 backend are in the same mode (generally HTTP), otherwise the configuration
2826 will be refused.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002827
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002828 Example :
Willy Tarreau2769aa02007-12-27 18:26:09 +01002829 defaults http_instances
2830 mode http
2831
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002832 See also : "monitor", "monitor-net"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002833
Willy Tarreau0ba27502007-12-24 16:55:16 +01002834
Cyril Bontéf0c60612010-02-06 14:44:47 +01002835monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01002836 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002837 May be used in sections : defaults | frontend | listen | backend
2838 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01002839 Arguments :
2840 if <cond> the monitor request will fail if the condition is satisfied,
2841 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002842 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01002843 are met, for instance a low number of servers both in a
2844 backend and its backup.
2845
2846 unless <cond> the monitor request will succeed only if the condition is
2847 satisfied, and will fail otherwise. Such a condition may be
2848 based on a test on the presence of a minimum number of active
2849 servers in a list of backends.
2850
2851 This statement adds a condition which can force the response to a monitor
2852 request to report a failure. By default, when an external component queries
2853 the URI dedicated to monitoring, a 200 response is returned. When one of the
2854 conditions above is met, haproxy will return 503 instead of 200. This is
2855 very useful to report a site failure to an external component which may base
2856 routing advertisements between multiple sites on the availability reported by
2857 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002858 criterion. Note that "monitor fail" only works in HTTP mode. Both status
2859 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002860
2861 Example:
2862 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01002863 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01002864 acl site_dead nbsrv(dynamic) lt 2
2865 acl site_dead nbsrv(static) lt 2
2866 monitor-uri /site_alive
2867 monitor fail if site_dead
2868
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002869 See also : "monitor-net", "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002870
2871
2872monitor-net <source>
2873 Declare a source network which is limited to monitor requests
2874 May be used in sections : defaults | frontend | listen | backend
2875 yes | yes | yes | no
2876 Arguments :
2877 <source> is the source IPv4 address or network which will only be able to
2878 get monitor responses to any request. It can be either an IPv4
2879 address, a host name, or an address followed by a slash ('/')
2880 followed by a mask.
2881
2882 In TCP mode, any connection coming from a source matching <source> will cause
2883 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002884 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01002885 forwarding the connection to a remote server.
2886
2887 In HTTP mode, a connection coming from a source matching <source> will be
2888 accepted, the following response will be sent without waiting for a request,
2889 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
2890 enough for any front-end HTTP probe to detect that the service is UP and
Willy Tarreau82569f92012-09-27 23:48:56 +02002891 running without forwarding the request to a backend server. Note that this
2892 response is sent in raw format, without any transformation. This is important
2893 as it means that it will not be SSL-encrypted on SSL listeners.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002894
Willy Tarreau82569f92012-09-27 23:48:56 +02002895 Monitor requests are processed very early, just after tcp-request connection
2896 ACLs which are the only ones able to block them. These connections are short
2897 lived and never wait for any data from the client. They cannot be logged, and
2898 it is the intended purpose. They are only used to report HAProxy's health to
2899 an upper component, nothing more. Please note that "monitor fail" rules do
2900 not apply to connections intercepted by "monitor-net".
Willy Tarreau2769aa02007-12-27 18:26:09 +01002901
Willy Tarreau95cd2832010-03-04 23:36:33 +01002902 Last, please note that only one "monitor-net" statement can be specified in
2903 a frontend. If more than one is found, only the last one will be considered.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002904
Willy Tarreau2769aa02007-12-27 18:26:09 +01002905 Example :
2906 # addresses .252 and .253 are just probing us.
2907 frontend www
2908 monitor-net 192.168.0.252/31
2909
2910 See also : "monitor fail", "monitor-uri"
2911
2912
2913monitor-uri <uri>
2914 Intercept a URI used by external components' monitor requests
2915 May be used in sections : defaults | frontend | listen | backend
2916 yes | yes | yes | no
2917 Arguments :
2918 <uri> is the exact URI which we want to intercept to return HAProxy's
2919 health status instead of forwarding the request.
2920
2921 When an HTTP request referencing <uri> will be received on a frontend,
2922 HAProxy will not forward it nor log it, but instead will return either
2923 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
2924 conditions defined with "monitor fail". This is normally enough for any
2925 front-end HTTP probe to detect that the service is UP and running without
2926 forwarding the request to a backend server. Note that the HTTP method, the
2927 version and all headers are ignored, but the request must at least be valid
2928 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
2929
2930 Monitor requests are processed very early. It is not possible to block nor
2931 divert them using ACLs. They cannot be logged either, and it is the intended
2932 purpose. They are only used to report HAProxy's health to an upper component,
2933 nothing more. However, it is possible to add any number of conditions using
2934 "monitor fail" and ACLs so that the result can be adjusted to whatever check
2935 can be imagined (most often the number of available servers in a backend).
2936
2937 Example :
2938 # Use /haproxy_test to report haproxy's status
2939 frontend www
2940 mode http
2941 monitor-uri /haproxy_test
2942
2943 See also : "monitor fail", "monitor-net"
2944
Willy Tarreau0ba27502007-12-24 16:55:16 +01002945
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002946option abortonclose
2947no option abortonclose
2948 Enable or disable early dropping of aborted requests pending in queues.
2949 May be used in sections : defaults | frontend | listen | backend
2950 yes | no | yes | yes
2951 Arguments : none
2952
2953 In presence of very high loads, the servers will take some time to respond.
2954 The per-instance connection queue will inflate, and the response time will
2955 increase respective to the size of the queue times the average per-session
2956 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01002957 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002958 the queue, and slowing down other users, and the servers as well, because the
2959 request will eventually be served, then aborted at the first error
2960 encountered while delivering the response.
2961
2962 As there is no way to distinguish between a full STOP and a simple output
2963 close on the client side, HTTP agents should be conservative and consider
2964 that the client might only have closed its output channel while waiting for
2965 the response. However, this introduces risks of congestion when lots of users
2966 do the same, and is completely useless nowadays because probably no client at
2967 all will close the session while waiting for the response. Some HTTP agents
Willy Tarreaud72758d2010-01-12 10:42:19 +01002968 support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002969 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01002970 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002971 of being the single component to break rare but valid traffic is extremely
2972 low, which adds to the temptation to be able to abort a session early while
2973 still not served and not pollute the servers.
2974
2975 In HAProxy, the user can choose the desired behaviour using the option
2976 "abortonclose". By default (without the option) the behaviour is HTTP
2977 compliant and aborted requests will be served. But when the option is
2978 specified, a session with an incoming channel closed will be aborted while
2979 it is still possible, either pending in the queue for a connection slot, or
2980 during the connection establishment if the server has not yet acknowledged
2981 the connection request. This considerably reduces the queue size and the load
2982 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01002983 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01002984
2985 If this option has been enabled in a "defaults" section, it can be disabled
2986 in a specific instance by prepending the "no" keyword before it.
2987
2988 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
2989
2990
Willy Tarreau4076a152009-04-02 15:18:36 +02002991option accept-invalid-http-request
2992no option accept-invalid-http-request
2993 Enable or disable relaxing of HTTP request parsing
2994 May be used in sections : defaults | frontend | listen | backend
2995 yes | yes | yes | no
2996 Arguments : none
2997
2998 By default, HAProxy complies with RFC2616 in terms of message parsing. This
2999 means that invalid characters in header names are not permitted and cause an
3000 error to be returned to the client. This is the desired behaviour as such
3001 forbidden characters are essentially used to build attacks exploiting server
3002 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
3003 server will emit invalid header names for whatever reason (configuration,
3004 implementation) and the issue will not be immediately fixed. In such a case,
3005 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau422246e2012-01-07 23:54:13 +01003006 even if that does not make sense, by specifying this option. Similarly, the
3007 list of characters allowed to appear in a URI is well defined by RFC3986, and
3008 chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
3009 ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
3010 not allowed at all. Haproxy always blocks a number of them (0..32, 127). The
3011 remaining ones are blocked by default unless this option is enabled.
Willy Tarreau4076a152009-04-02 15:18:36 +02003012
3013 This option should never be enabled by default as it hides application bugs
3014 and open security breaches. It should only be deployed after a problem has
3015 been confirmed.
3016
3017 When this option is enabled, erroneous header names will still be accepted in
3018 requests, but the complete request will be captured in order to permit later
Willy Tarreau422246e2012-01-07 23:54:13 +01003019 analysis using the "show errors" request on the UNIX stats socket. Similarly,
3020 requests containing invalid chars in the URI part will be logged. Doing this
Willy Tarreau4076a152009-04-02 15:18:36 +02003021 also helps confirming that the issue has been solved.
3022
3023 If this option has been enabled in a "defaults" section, it can be disabled
3024 in a specific instance by prepending the "no" keyword before it.
3025
3026 See also : "option accept-invalid-http-response" and "show errors" on the
3027 stats socket.
3028
3029
3030option accept-invalid-http-response
3031no option accept-invalid-http-response
3032 Enable or disable relaxing of HTTP response parsing
3033 May be used in sections : defaults | frontend | listen | backend
3034 yes | no | yes | yes
3035 Arguments : none
3036
3037 By default, HAProxy complies with RFC2616 in terms of message parsing. This
3038 means that invalid characters in header names are not permitted and cause an
3039 error to be returned to the client. This is the desired behaviour as such
3040 forbidden characters are essentially used to build attacks exploiting server
3041 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
3042 server will emit invalid header names for whatever reason (configuration,
3043 implementation) and the issue will not be immediately fixed. In such a case,
3044 it is possible to relax HAProxy's header name parser to accept any character
3045 even if that does not make sense, by specifying this option.
3046
3047 This option should never be enabled by default as it hides application bugs
3048 and open security breaches. It should only be deployed after a problem has
3049 been confirmed.
3050
3051 When this option is enabled, erroneous header names will still be accepted in
3052 responses, but the complete response will be captured in order to permit
3053 later analysis using the "show errors" request on the UNIX stats socket.
3054 Doing this also helps confirming that the issue has been solved.
3055
3056 If this option has been enabled in a "defaults" section, it can be disabled
3057 in a specific instance by prepending the "no" keyword before it.
3058
3059 See also : "option accept-invalid-http-request" and "show errors" on the
3060 stats socket.
3061
3062
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003063option allbackups
3064no option allbackups
3065 Use either all backup servers at a time or only the first one
3066 May be used in sections : defaults | frontend | listen | backend
3067 yes | no | yes | yes
3068 Arguments : none
3069
3070 By default, the first operational backup server gets all traffic when normal
3071 servers are all down. Sometimes, it may be preferred to use multiple backups
3072 at once, because one will not be enough. When "option allbackups" is enabled,
3073 the load balancing will be performed among all backup servers when all normal
3074 ones are unavailable. The same load balancing algorithm will be used and the
3075 servers' weights will be respected. Thus, there will not be any priority
3076 order between the backup servers anymore.
3077
3078 This option is mostly used with static server farms dedicated to return a
3079 "sorry" page when an application is completely offline.
3080
3081 If this option has been enabled in a "defaults" section, it can be disabled
3082 in a specific instance by prepending the "no" keyword before it.
3083
3084
3085option checkcache
3086no option checkcache
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003087 Analyze all server responses and block requests with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003088 May be used in sections : defaults | frontend | listen | backend
3089 yes | no | yes | yes
3090 Arguments : none
3091
3092 Some high-level frameworks set application cookies everywhere and do not
3093 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003094 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003095 high risk of session crossing or stealing between users traversing the same
3096 caches. In some situations, it is better to block the response than to let
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02003097 some sensitive session information go in the wild.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003098
3099 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003100 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01003101 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003102 response to check if there's a risk of caching a cookie on a client-side
3103 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01003104 to the client are :
3105 - all those without "Set-Cookie" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003106 - all those with a return code other than 200, 203, 206, 300, 301, 410,
Willy Tarreau198a7442008-01-17 12:05:32 +01003107 provided that the server has not set a "Cache-control: public" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003108 - all those that come from a POST request, provided that the server has not
3109 set a 'Cache-Control: public' header ;
3110 - those with a 'Pragma: no-cache' header
3111 - those with a 'Cache-control: private' header
3112 - those with a 'Cache-control: no-store' header
3113 - those with a 'Cache-control: max-age=0' header
3114 - those with a 'Cache-control: s-maxage=0' header
3115 - those with a 'Cache-control: no-cache' header
3116 - those with a 'Cache-control: no-cache="set-cookie"' header
3117 - those with a 'Cache-control: no-cache="set-cookie,' header
3118 (allowing other fields after set-cookie)
3119
3120 If a response doesn't respect these requirements, then it will be blocked
Willy Tarreau198a7442008-01-17 12:05:32 +01003121 just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003122 The session state shows "PH--" meaning that the proxy blocked the response
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003123 during headers processing. Additionally, an alert will be sent in the logs so
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003124 that admins are informed that there's something to be fixed.
3125
3126 Due to the high impact on the application, the application should be tested
3127 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003128 good practice to always activate it during tests, even if it is not used in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003129 production, as it will report potentially dangerous application behaviours.
3130
3131 If this option has been enabled in a "defaults" section, it can be disabled
3132 in a specific instance by prepending the "no" keyword before it.
3133
3134
3135option clitcpka
3136no option clitcpka
3137 Enable or disable the sending of TCP keepalive packets on the client side
3138 May be used in sections : defaults | frontend | listen | backend
3139 yes | yes | yes | no
3140 Arguments : none
3141
3142 When there is a firewall or any session-aware component between a client and
3143 a server, and when the protocol involves very long sessions with long idle
3144 periods (eg: remote desktops), there is a risk that one of the intermediate
3145 components decides to expire a session which has remained idle for too long.
3146
3147 Enabling socket-level TCP keep-alives makes the system regularly send packets
3148 to the other end of the connection, leaving it active. The delay between
3149 keep-alive probes is controlled by the system only and depends both on the
3150 operating system and its tuning parameters.
3151
3152 It is important to understand that keep-alive packets are neither emitted nor
3153 received at the application level. It is only the network stacks which sees
3154 them. For this reason, even if one side of the proxy already uses keep-alives
3155 to maintain its connection alive, those keep-alive packets will not be
3156 forwarded to the other side of the proxy.
3157
3158 Please note that this has nothing to do with HTTP keep-alive.
3159
3160 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
3161 client side of a connection, which should help when session expirations are
3162 noticed between HAProxy and a client.
3163
3164 If this option has been enabled in a "defaults" section, it can be disabled
3165 in a specific instance by prepending the "no" keyword before it.
3166
3167 See also : "option srvtcpka", "option tcpka"
3168
3169
Willy Tarreau0ba27502007-12-24 16:55:16 +01003170option contstats
3171 Enable continuous traffic statistics updates
3172 May be used in sections : defaults | frontend | listen | backend
3173 yes | yes | yes | no
3174 Arguments : none
3175
3176 By default, counters used for statistics calculation are incremented
3177 only when a session finishes. It works quite well when serving small
3178 objects, but with big ones (for example large images or archives) or
3179 with A/V streaming, a graph generated from haproxy counters looks like
3180 a hedgehog. With this option enabled counters get incremented continuously,
3181 during a whole session. Recounting touches a hotpath directly so
3182 it is not enabled by default, as it has small performance impact (~0.5%).
3183
3184
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003185option dontlog-normal
3186no option dontlog-normal
3187 Enable or disable logging of normal, successful connections
3188 May be used in sections : defaults | frontend | listen | backend
3189 yes | yes | yes | no
3190 Arguments : none
3191
3192 There are large sites dealing with several thousand connections per second
3193 and for which logging is a major pain. Some of them are even forced to turn
3194 logs off and cannot debug production issues. Setting this option ensures that
3195 normal connections, those which experience no error, no timeout, no retry nor
3196 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
3197 mode, the response status code is checked and return codes 5xx will still be
3198 logged.
3199
3200 It is strongly discouraged to use this option as most of the time, the key to
3201 complex issues is in the normal logs which will not be logged here. If you
3202 need to separate logs, see the "log-separate-errors" option instead.
3203
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003204 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003205 logging.
3206
3207
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003208option dontlognull
3209no option dontlognull
3210 Enable or disable logging of null connections
3211 May be used in sections : defaults | frontend | listen | backend
3212 yes | yes | yes | no
3213 Arguments : none
3214
3215 In certain environments, there are components which will regularly connect to
3216 various systems to ensure that they are still alive. It can be the case from
3217 another load balancer as well as from monitoring systems. By default, even a
3218 simple port probe or scan will produce a log. If those connections pollute
3219 the logs too much, it is possible to enable option "dontlognull" to indicate
3220 that a connection on which no data has been transferred will not be logged,
3221 which typically corresponds to those probes.
3222
3223 It is generally recommended not to use this option in uncontrolled
3224 environments (eg: internet), otherwise scans and other malicious activities
3225 would not be logged.
3226
3227 If this option has been enabled in a "defaults" section, it can be disabled
3228 in a specific instance by prepending the "no" keyword before it.
3229
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003230 See also : "log", "monitor-net", "monitor-uri" and section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003231
3232
3233option forceclose
3234no option forceclose
3235 Enable or disable active connection closing after response is transferred.
3236 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaua31e5df2009-12-30 01:10:35 +01003237 yes | yes | yes | yes
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003238 Arguments : none
3239
3240 Some HTTP servers do not necessarily close the connections when they receive
3241 the "Connection: close" set by "option httpclose", and if the client does not
3242 close either, then the connection remains open till the timeout expires. This
3243 causes high number of simultaneous connections on the servers and shows high
3244 global session times in the logs.
3245
3246 When this happens, it is possible to use "option forceclose". It will
Willy Tarreau82eeaf22009-12-29 12:09:05 +01003247 actively close the outgoing server channel as soon as the server has finished
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003248 to respond. This option implicitly enables the "httpclose" option. Note that
3249 this option also enables the parsing of the full request and response, which
3250 means we can close the connection to the server very quickly, releasing some
3251 resources earlier than with httpclose.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003252
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003253 This option may also be combined with "option http-pretend-keepalive", which
3254 will disable sending of the "Connection: close" header, but will still cause
3255 the connection to be closed once the whole response is received.
3256
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003257 If this option has been enabled in a "defaults" section, it can be disabled
3258 in a specific instance by prepending the "no" keyword before it.
3259
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003260 See also : "option httpclose" and "option http-pretend-keepalive"
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003261
3262
Willy Tarreau87cf5142011-08-19 22:57:24 +02003263option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003264 Enable insertion of the X-Forwarded-For header to requests sent to servers
3265 May be used in sections : defaults | frontend | listen | backend
3266 yes | yes | yes | yes
3267 Arguments :
3268 <network> is an optional argument used to disable this option for sources
3269 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02003270 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01003271 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003272
3273 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
3274 their client address. This is sometimes annoying when the client's IP address
3275 is expected in server logs. To solve this problem, the well-known HTTP header
3276 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
3277 This header contains a value representing the client's IP address. Since this
3278 header is always appended at the end of the existing header list, the server
3279 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02003280 the server's manual to find how to enable use of this standard header. Note
3281 that only the last occurrence of the header must be used, since it is really
3282 possible that the client has already brought one.
3283
Willy Tarreaud72758d2010-01-12 10:42:19 +01003284 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02003285 the default "X-Forwarded-For". This can be useful where you might already
Willy Tarreaud72758d2010-01-12 10:42:19 +01003286 have a "X-Forwarded-For" header from a different application (eg: stunnel),
3287 and you need preserve it. Also if your backend server doesn't use the
Ross Westaf72a1d2008-08-03 10:51:45 +02003288 "X-Forwarded-For" header and requires different one (eg: Zeus Web Servers
3289 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01003290
3291 Sometimes, a same HAProxy instance may be shared between a direct client
3292 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
3293 used to decrypt HTTPS traffic). It is possible to disable the addition of the
3294 header for a known source address or network by adding the "except" keyword
3295 followed by the network address. In this case, any source IP matching the
3296 network will not cause an addition of this header. Most common uses are with
3297 private networks or 127.0.0.1.
3298
Willy Tarreau87cf5142011-08-19 22:57:24 +02003299 Alternatively, the keyword "if-none" states that the header will only be
3300 added if it is not present. This should only be used in perfectly trusted
3301 environment, as this might cause a security issue if headers reaching haproxy
3302 are under the control of the end-user.
3303
Willy Tarreauc27debf2008-01-06 08:57:02 +01003304 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02003305 least one of them uses it, the header will be added. Note that the backend's
3306 setting of the header subargument takes precedence over the frontend's if
Willy Tarreau87cf5142011-08-19 22:57:24 +02003307 both are defined. In the case of the "if-none" argument, if at least one of
3308 the frontend or the backend does not specify it, it wants the addition to be
3309 mandatory, so it wins.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003310
Willy Tarreau87cf5142011-08-19 22:57:24 +02003311 It is important to note that by default, HAProxy works in tunnel mode and
3312 only inspects the first request of a connection, meaning that only the first
3313 request will have the header appended, which is certainly not what you want.
3314 In order to fix this, ensure that any of the "httpclose", "forceclose" or
3315 "http-server-close" options is set when using this option.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003316
Ross Westaf72a1d2008-08-03 10:51:45 +02003317 Examples :
Willy Tarreauc27debf2008-01-06 08:57:02 +01003318 # Public HTTP address also used by stunnel on the same machine
3319 frontend www
3320 mode http
3321 option forwardfor except 127.0.0.1 # stunnel already adds the header
3322
Ross Westaf72a1d2008-08-03 10:51:45 +02003323 # Those servers want the IP Address in X-Client
3324 backend www
3325 mode http
3326 option forwardfor header X-Client
3327
Willy Tarreau87cf5142011-08-19 22:57:24 +02003328 See also : "option httpclose", "option http-server-close",
3329 "option forceclose"
Willy Tarreauc27debf2008-01-06 08:57:02 +01003330
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003331
Willy Tarreau96e31212011-05-30 18:10:30 +02003332option http-no-delay
3333no option http-no-delay
3334 Instruct the system to favor low interactive delays over performance in HTTP
3335 May be used in sections : defaults | frontend | listen | backend
3336 yes | yes | yes | yes
3337 Arguments : none
3338
3339 In HTTP, each payload is unidirectional and has no notion of interactivity.
3340 Any agent is expected to queue data somewhat for a reasonably low delay.
3341 There are some very rare server-to-server applications that abuse the HTTP
3342 protocol and expect the payload phase to be highly interactive, with many
3343 interleaved data chunks in both directions within a single request. This is
3344 absolutely not supported by the HTTP specification and will not work across
3345 most proxies or servers. When such applications attempt to do this through
3346 haproxy, it works but they will experience high delays due to the network
3347 optimizations which favor performance by instructing the system to wait for
3348 enough data to be available in order to only send full packets. Typical
3349 delays are around 200 ms per round trip. Note that this only happens with
3350 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
3351 affected.
3352
3353 When "option http-no-delay" is present in either the frontend or the backend
3354 used by a connection, all such optimizations will be disabled in order to
3355 make the exchanges as fast as possible. Of course this offers no guarantee on
3356 the functionality, as it may break at any other place. But if it works via
3357 HAProxy, it will work as fast as possible. This option should never be used
3358 by default, and should never be used at all unless such a buggy application
3359 is discovered. The impact of using this option is an increase of bandwidth
3360 usage and CPU usage, which may significantly lower performance in high
3361 latency environments.
3362
3363
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003364option http-pretend-keepalive
3365no option http-pretend-keepalive
3366 Define whether haproxy will announce keepalive to the server or not
3367 May be used in sections : defaults | frontend | listen | backend
3368 yes | yes | yes | yes
3369 Arguments : none
3370
3371 When running with "option http-server-close" or "option forceclose", haproxy
3372 adds a "Connection: close" header to the request forwarded to the server.
3373 Unfortunately, when some servers see this header, they automatically refrain
3374 from using the chunked encoding for responses of unknown length, while this
3375 is totally unrelated. The immediate effect is that this prevents haproxy from
3376 maintaining the client connection alive. A second effect is that a client or
3377 a cache could receive an incomplete response without being aware of it, and
3378 consider the response complete.
3379
3380 By setting "option http-pretend-keepalive", haproxy will make the server
3381 believe it will keep the connection alive. The server will then not fall back
3382 to the abnormal undesired above. When haproxy gets the whole response, it
3383 will close the connection with the server just as it would do with the
3384 "forceclose" option. That way the client gets a normal response and the
3385 connection is correctly closed on the server side.
3386
3387 It is recommended not to enable this option by default, because most servers
3388 will more efficiently close the connection themselves after the last packet,
3389 and release its buffers slightly earlier. Also, the added packet on the
3390 network could slightly reduce the overall peak performance. However it is
3391 worth noting that when this option is enabled, haproxy will have slightly
3392 less work to do. So if haproxy is the bottleneck on the whole architecture,
3393 enabling this option might save a few CPU cycles.
3394
3395 This option may be set both in a frontend and in a backend. It is enabled if
3396 at least one of the frontend or backend holding a connection has it enabled.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003397 This option may be combined with "option httpclose", which will cause
Willy Tarreau22a95342010-09-29 14:31:41 +02003398 keepalive to be announced to the server and close to be announced to the
3399 client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003400
3401 If this option has been enabled in a "defaults" section, it can be disabled
3402 in a specific instance by prepending the "no" keyword before it.
3403
3404 See also : "option forceclose" and "option http-server-close"
3405
Willy Tarreauc27debf2008-01-06 08:57:02 +01003406
Willy Tarreaub608feb2010-01-02 22:47:18 +01003407option http-server-close
3408no option http-server-close
3409 Enable or disable HTTP connection closing on the server side
3410 May be used in sections : defaults | frontend | listen | backend
3411 yes | yes | yes | yes
3412 Arguments : none
3413
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003414 By default, when a client communicates with a server, HAProxy will only
3415 analyze, log, and process the first request of each connection. Setting
3416 "option http-server-close" enables HTTP connection-close mode on the server
3417 side while keeping the ability to support HTTP keep-alive and pipelining on
3418 the client side. This provides the lowest latency on the client side (slow
3419 network) and the fastest session reuse on the server side to save server
3420 resources, similarly to "option forceclose". It also permits non-keepalive
3421 capable servers to be served in keep-alive mode to the clients if they
3422 conform to the requirements of RFC2616. Please note that some servers do not
3423 always conform to those requirements when they see "Connection: close" in the
3424 request. The effect will be that keep-alive will never be used. A workaround
3425 consists in enabling "option http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003426
3427 At the moment, logs will not indicate whether requests came from the same
3428 session or not. The accept date reported in the logs corresponds to the end
3429 of the previous request, and the request time corresponds to the time spent
3430 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01003431 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
3432 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01003433
3434 This option may be set both in a frontend and in a backend. It is enabled if
3435 at least one of the frontend or backend holding a connection has it enabled.
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003436 It is worth noting that "option forceclose" has precedence over "option
3437 http-server-close" and that combining "http-server-close" with "httpclose"
3438 basically achieve the same result as "forceclose".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003439
3440 If this option has been enabled in a "defaults" section, it can be disabled
3441 in a specific instance by prepending the "no" keyword before it.
3442
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003443 See also : "option forceclose", "option http-pretend-keepalive",
3444 "option httpclose" and "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003445
3446
Willy Tarreau88d349d2010-01-25 12:15:43 +01003447option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01003448no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01003449 Make use of non-standard Proxy-Connection header instead of Connection
3450 May be used in sections : defaults | frontend | listen | backend
3451 yes | yes | yes | no
3452 Arguments : none
3453
3454 While RFC2616 explicitly states that HTTP/1.1 agents must use the
3455 Connection header to indicate their wish of persistent or non-persistent
3456 connections, both browsers and proxies ignore this header for proxied
3457 connections and make use of the undocumented, non-standard Proxy-Connection
3458 header instead. The issue begins when trying to put a load balancer between
3459 browsers and such proxies, because there will be a difference between what
3460 haproxy understands and what the client and the proxy agree on.
3461
3462 By setting this option in a frontend, haproxy can automatically switch to use
3463 that non-standard header if it sees proxied requests. A proxied request is
3464 defined here as one where the URI begins with neither a '/' nor a '*'. The
3465 choice of header only affects requests passing through proxies making use of
3466 one of the "httpclose", "forceclose" and "http-server-close" options. Note
3467 that this option can only be specified in a frontend and will affect the
3468 request along its whole life.
3469
Willy Tarreau844a7e72010-01-31 21:46:18 +01003470 Also, when this option is set, a request which requires authentication will
3471 automatically switch to use proxy authentication headers if it is itself a
3472 proxied request. That makes it possible to check or enforce authentication in
3473 front of an existing proxy.
3474
Willy Tarreau88d349d2010-01-25 12:15:43 +01003475 This option should normally never be used, except in front of a proxy.
3476
3477 See also : "option httpclose", "option forceclose" and "option
3478 http-server-close".
3479
3480
Willy Tarreaud63335a2010-02-26 12:56:52 +01003481option httpchk
3482option httpchk <uri>
3483option httpchk <method> <uri>
3484option httpchk <method> <uri> <version>
3485 Enable HTTP protocol to check on the servers health
3486 May be used in sections : defaults | frontend | listen | backend
3487 yes | no | yes | yes
3488 Arguments :
3489 <method> is the optional HTTP method used with the requests. When not set,
3490 the "OPTIONS" method is used, as it generally requires low server
3491 processing and is easy to filter out from the logs. Any method
3492 may be used, though it is not recommended to invent non-standard
3493 ones.
3494
3495 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
3496 which is accessible by default on almost any server, but may be
3497 changed to any other URI. Query strings are permitted.
3498
3499 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
3500 but some servers might behave incorrectly in HTTP 1.0, so turning
3501 it to HTTP/1.1 may sometimes help. Note that the Host field is
3502 mandatory in HTTP/1.1, and as a trick, it is possible to pass it
3503 after "\r\n" following the version string.
3504
3505 By default, server health checks only consist in trying to establish a TCP
3506 connection. When "option httpchk" is specified, a complete HTTP request is
3507 sent once the TCP connection is established, and responses 2xx and 3xx are
3508 considered valid, while all other ones indicate a server failure, including
3509 the lack of any response.
3510
3511 The port and interval are specified in the server configuration.
3512
3513 This option does not necessarily require an HTTP backend, it also works with
3514 plain TCP backends. This is particularly useful to check simple scripts bound
3515 to some dedicated ports using the inetd daemon.
3516
3517 Examples :
3518 # Relay HTTPS traffic to Apache instance and check service availability
3519 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
3520 backend https_relay
3521 mode tcp
3522 option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www
3523 server apache1 192.168.1.1:443 check port 80
3524
3525 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003526 "option pgsql-check", "http-check" and the "check", "port" and
3527 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01003528
3529
Willy Tarreauc27debf2008-01-06 08:57:02 +01003530option httpclose
3531no option httpclose
3532 Enable or disable passive HTTP connection closing
3533 May be used in sections : defaults | frontend | listen | backend
3534 yes | yes | yes | yes
3535 Arguments : none
3536
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003537 By default, when a client communicates with a server, HAProxy will only
3538 analyze, log, and process the first request of each connection. If "option
3539 httpclose" is set, it will check if a "Connection: close" header is already
3540 set in each direction, and will add one if missing. Each end should react to
3541 this by actively closing the TCP connection after each transfer, thus
3542 resulting in a switch to the HTTP close mode. Any "Connection" header
3543 different from "close" will also be removed.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003544
3545 It seldom happens that some servers incorrectly ignore this header and do not
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003546 close the connection even though they reply "Connection: close". For this
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003547 reason, they are not compatible with older HTTP 1.0 browsers. If this happens
3548 it is possible to use the "option forceclose" which actively closes the
3549 request connection once the server responds. Option "forceclose" also
3550 releases the server connection earlier because it does not have to wait for
3551 the client to acknowledge it.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003552
3553 This option may be set both in a frontend and in a backend. It is enabled if
3554 at least one of the frontend or backend holding a connection has it enabled.
3555 If "option forceclose" is specified too, it has precedence over "httpclose".
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003556 If "option http-server-close" is enabled at the same time as "httpclose", it
3557 basically achieves the same result as "option forceclose".
Willy Tarreauc27debf2008-01-06 08:57:02 +01003558
3559 If this option has been enabled in a "defaults" section, it can be disabled
3560 in a specific instance by prepending the "no" keyword before it.
3561
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003562 See also : "option forceclose", "option http-server-close" and
3563 "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01003564
3565
Emeric Brun3a058f32009-06-30 18:26:00 +02003566option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003567 Enable logging of HTTP request, session state and timers
3568 May be used in sections : defaults | frontend | listen | backend
3569 yes | yes | yes | yes
Emeric Brun3a058f32009-06-30 18:26:00 +02003570 Arguments :
3571 clf if the "clf" argument is added, then the output format will be
3572 the CLF format instead of HAProxy's default HTTP format. You can
3573 use this when you need to feed HAProxy's logs through a specific
3574 log analyser which only support the CLF format and which is not
3575 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003576
3577 By default, the log output format is very poor, as it only contains the
3578 source and destination addresses, and the instance name. By specifying
3579 "option httplog", each log line turns into a much richer format including,
3580 but not limited to, the HTTP request, the connection timers, the session
3581 status, the connections numbers, the captured headers and cookies, the
3582 frontend, backend and server name, and of course the source address and
3583 ports.
3584
3585 This option may be set either in the frontend or the backend.
3586
Emeric Brun3a058f32009-06-30 18:26:00 +02003587 If this option has been enabled in a "defaults" section, it can be disabled
3588 in a specific instance by prepending the "no" keyword before it. Specifying
3589 only "option httplog" will automatically clear the 'clf' mode if it was set
3590 by default.
3591
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003592 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003593
Willy Tarreau55165fe2009-05-10 12:02:55 +02003594
3595option http_proxy
3596no option http_proxy
3597 Enable or disable plain HTTP proxy mode
3598 May be used in sections : defaults | frontend | listen | backend
3599 yes | yes | yes | yes
3600 Arguments : none
3601
3602 It sometimes happens that people need a pure HTTP proxy which understands
3603 basic proxy requests without caching nor any fancy feature. In this case,
3604 it may be worth setting up an HAProxy instance with the "option http_proxy"
3605 set. In this mode, no server is declared, and the connection is forwarded to
3606 the IP address and port found in the URL after the "http://" scheme.
3607
3608 No host address resolution is performed, so this only works when pure IP
3609 addresses are passed. Since this option's usage perimeter is rather limited,
3610 it will probably be used only by experts who know they need exactly it. Last,
3611 if the clients are susceptible of sending keep-alive requests, it will be
Cyril Bonté2409e682010-12-14 22:47:51 +01003612 needed to add "option httpclose" to ensure that all requests will correctly
Willy Tarreau55165fe2009-05-10 12:02:55 +02003613 be analyzed.
3614
3615 If this option has been enabled in a "defaults" section, it can be disabled
3616 in a specific instance by prepending the "no" keyword before it.
3617
3618 Example :
3619 # this backend understands HTTP proxy requests and forwards them directly.
3620 backend direct_forward
3621 option httpclose
3622 option http_proxy
3623
3624 See also : "option httpclose"
3625
Willy Tarreau211ad242009-10-03 21:45:07 +02003626
Jamie Gloudon801a0a32012-08-25 00:18:33 -04003627option independent-streams
3628no option independent-streams
3629 Enable or disable independent timeout processing for both directions
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02003630 May be used in sections : defaults | frontend | listen | backend
3631 yes | yes | yes | yes
3632 Arguments : none
3633
3634 By default, when data is sent over a socket, both the write timeout and the
3635 read timeout for that socket are refreshed, because we consider that there is
3636 activity on that socket, and we have no other means of guessing if we should
3637 receive data or not.
3638
3639 While this default behaviour is desirable for almost all applications, there
3640 exists a situation where it is desirable to disable it, and only refresh the
3641 read timeout if there are incoming data. This happens on sessions with large
3642 timeouts and low amounts of exchanged data such as telnet session. If the
3643 server suddenly disappears, the output data accumulates in the system's
3644 socket buffers, both timeouts are correctly refreshed, and there is no way
3645 to know the server does not receive them, so we don't timeout. However, when
3646 the underlying protocol always echoes sent data, it would be enough by itself
3647 to detect the issue using the read timeout. Note that this problem does not
3648 happen with more verbose protocols because data won't accumulate long in the
3649 socket buffers.
3650
3651 When this option is set on the frontend, it will disable read timeout updates
3652 on data sent to the client. There probably is little use of this case. When
3653 the option is set on the backend, it will disable read timeout updates on
3654 data sent to the server. Doing so will typically break large HTTP posts from
3655 slow lines, so use it with caution.
3656
Jamie Gloudon801a0a32012-08-25 00:18:33 -04003657 Note: older versions used to call this setting "option independant-streams"
3658 with a spelling mistake. This spelling is still supported but
3659 deprecated.
3660
Willy Tarreauce887fd2012-05-12 12:50:00 +02003661 See also : "timeout client", "timeout server" and "timeout tunnel"
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02003662
3663
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02003664option ldap-check
3665 Use LDAPv3 health checks for server testing
3666 May be used in sections : defaults | frontend | listen | backend
3667 yes | no | yes | yes
3668 Arguments : none
3669
3670 It is possible to test that the server correctly talks LDAPv3 instead of just
3671 testing that it accepts the TCP connection. When this option is set, an
3672 LDAPv3 anonymous simple bind message is sent to the server, and the response
3673 is analyzed to find an LDAPv3 bind response message.
3674
3675 The server is considered valid only when the LDAP response contains success
3676 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
3677
3678 Logging of bind requests is server dependent see your documentation how to
3679 configure it.
3680
3681 Example :
3682 option ldap-check
3683
3684 See also : "option httpchk"
3685
3686
Willy Tarreau211ad242009-10-03 21:45:07 +02003687option log-health-checks
3688no option log-health-checks
3689 Enable or disable logging of health checks
3690 May be used in sections : defaults | frontend | listen | backend
3691 yes | no | yes | yes
3692 Arguments : none
3693
3694 Enable health checks logging so it possible to check for example what
3695 was happening before a server crash. Failed health check are logged if
3696 server is UP and succeeded health checks if server is DOWN, so the amount
3697 of additional information is limited.
3698
3699 If health check logging is enabled no health check status is printed
3700 when servers is set up UP/DOWN/ENABLED/DISABLED.
3701
3702 See also: "log" and section 8 about logging.
3703
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003704
3705option log-separate-errors
3706no option log-separate-errors
3707 Change log level for non-completely successful connections
3708 May be used in sections : defaults | frontend | listen | backend
3709 yes | yes | yes | no
3710 Arguments : none
3711
3712 Sometimes looking for errors in logs is not easy. This option makes haproxy
3713 raise the level of logs containing potentially interesting information such
3714 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
3715 level changes from "info" to "err". This makes it possible to log them
3716 separately to a different file with most syslog daemons. Be careful not to
3717 remove them from the original file, otherwise you would lose ordering which
3718 provides very important information.
3719
3720 Using this option, large sites dealing with several thousand connections per
3721 second may log normal traffic to a rotating buffer and only archive smaller
3722 error logs.
3723
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003724 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003725 logging.
3726
Willy Tarreauc27debf2008-01-06 08:57:02 +01003727
3728option logasap
3729no option logasap
3730 Enable or disable early logging of HTTP requests
3731 May be used in sections : defaults | frontend | listen | backend
3732 yes | yes | yes | no
3733 Arguments : none
3734
3735 By default, HTTP requests are logged upon termination so that the total
3736 transfer time and the number of bytes appear in the logs. When large objects
3737 are being transferred, it may take a while before the request appears in the
3738 logs. Using "option logasap", the request gets logged as soon as the server
3739 sends the complete headers. The only missing information in the logs will be
3740 the total number of bytes which will indicate everything except the amount
3741 of data transferred, and the total time which will not take the transfer
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003742 time into account. In such a situation, it's a good practice to capture the
Willy Tarreauc27debf2008-01-06 08:57:02 +01003743 "Content-Length" response header so that the logs at least indicate how many
3744 bytes are expected to be transferred.
3745
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003746 Examples :
3747 listen http_proxy 0.0.0.0:80
3748 mode http
3749 option httplog
3750 option logasap
3751 log 192.168.2.200 local3
3752
3753 >>> Feb 6 12:14:14 localhost \
3754 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
3755 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
3756 "GET /image.iso HTTP/1.0"
3757
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003758 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01003759 logging.
3760
3761
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003762option mysql-check [ user <username> ]
3763 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003764 May be used in sections : defaults | frontend | listen | backend
3765 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003766 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003767 <username> This is the username which will be used when connecting to MySQL
3768 server.
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003769
3770 If you specify a username, the check consists of sending two MySQL packet,
3771 one Client Authentication packet, and one QUIT packet, to correctly close
3772 MySQL session. We then parse the MySQL Handshake Initialisation packet and/or
3773 Error packet. It is a basic but useful test which does not produce error nor
3774 aborted connect on the server. However, it requires adding an authorization
3775 in the MySQL table, like this :
3776
3777 USE mysql;
3778 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
3779 FLUSH PRIVILEGES;
3780
3781 If you don't specify a username (it is deprecated and not recommended), the
3782 check only consists in parsing the Mysql Handshake Initialisation packet or
3783 Error packet, we don't send anything in this mode. It was reported that it
3784 can generate lockout if check is too frequent and/or if there is not enough
3785 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
3786 value as if a connection is established successfully within fewer than MySQL
3787 "max_connect_errors" attempts after a previous connection was interrupted,
3788 the error count for the host is cleared to zero. If HAProxy's server get
3789 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
3790
3791 Remember that this does not check database presence nor database consistency.
3792 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003793
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02003794 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003795
3796 Most often, an incoming MySQL server needs to see the client's IP address for
3797 various purposes, including IP privilege matching and connection logging.
3798 When possible, it is often wise to masquerade the client's IP address when
3799 connecting to the server using the "usesrc" argument of the "source" keyword,
3800 which requires the cttproxy feature to be compiled in, and the MySQL server
3801 to route the client via the machine hosting haproxy.
3802
3803 See also: "option httpchk"
3804
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003805option pgsql-check [ user <username> ]
3806 Use PostgreSQL health checks for server testing
3807 May be used in sections : defaults | frontend | listen | backend
3808 yes | no | yes | yes
3809 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003810 <username> This is the username which will be used when connecting to
3811 PostgreSQL server.
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003812
3813 The check sends a PostgreSQL StartupMessage and waits for either
3814 Authentication request or ErrorResponse message. It is a basic but useful
3815 test which does not produce error nor aborted connect on the server.
3816 This check is identical with the "mysql-check".
3817
3818 See also: "option httpchk"
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003819
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003820option nolinger
3821no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003822 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003823 May be used in sections: defaults | frontend | listen | backend
3824 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003825 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003826
3827 When clients or servers abort connections in a dirty way (eg: they are
3828 physically disconnected), the session timeouts triggers and the session is
3829 closed. But it will remain in FIN_WAIT1 state for some time in the system,
3830 using some resources and possibly limiting the ability to establish newer
3831 connections.
3832
3833 When this happens, it is possible to activate "option nolinger" which forces
3834 the system to immediately remove any socket's pending data on close. Thus,
3835 the session is instantly purged from the system's tables. This usually has
3836 side effects such as increased number of TCP resets due to old retransmits
3837 getting immediately rejected. Some firewalls may sometimes complain about
3838 this too.
3839
3840 For this reason, it is not recommended to use this option when not absolutely
3841 needed. You know that you need it when you have thousands of FIN_WAIT1
3842 sessions on your system (TIME_WAIT ones do not count).
3843
3844 This option may be used both on frontends and backends, depending on the side
3845 where it is required. Use it on the frontend for clients, and on the backend
3846 for servers.
3847
3848 If this option has been enabled in a "defaults" section, it can be disabled
3849 in a specific instance by prepending the "no" keyword before it.
3850
3851
Willy Tarreau55165fe2009-05-10 12:02:55 +02003852option originalto [ except <network> ] [ header <name> ]
3853 Enable insertion of the X-Original-To header to requests sent to servers
3854 May be used in sections : defaults | frontend | listen | backend
3855 yes | yes | yes | yes
3856 Arguments :
3857 <network> is an optional argument used to disable this option for sources
3858 matching <network>
3859 <name> an optional argument to specify a different "X-Original-To"
3860 header name.
3861
3862 Since HAProxy can work in transparent mode, every request from a client can
3863 be redirected to the proxy and HAProxy itself can proxy every request to a
3864 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
3865 be lost. This is annoying when you want access rules based on destination ip
3866 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
3867 added by HAProxy to all requests sent to the server. This header contains a
3868 value representing the original destination IP address. Since this must be
3869 configured to always use the last occurrence of this header only. Note that
3870 only the last occurrence of the header must be used, since it is really
3871 possible that the client has already brought one.
3872
3873 The keyword "header" may be used to supply a different header name to replace
3874 the default "X-Original-To". This can be useful where you might already
3875 have a "X-Original-To" header from a different application, and you need
3876 preserve it. Also if your backend server doesn't use the "X-Original-To"
3877 header and requires different one.
3878
3879 Sometimes, a same HAProxy instance may be shared between a direct client
3880 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
3881 used to decrypt HTTPS traffic). It is possible to disable the addition of the
3882 header for a known source address or network by adding the "except" keyword
3883 followed by the network address. In this case, any source IP matching the
3884 network will not cause an addition of this header. Most common uses are with
3885 private networks or 127.0.0.1.
3886
3887 This option may be specified either in the frontend or in the backend. If at
3888 least one of them uses it, the header will be added. Note that the backend's
3889 setting of the header subargument takes precedence over the frontend's if
3890 both are defined.
3891
Willy Tarreau87cf5142011-08-19 22:57:24 +02003892 It is important to note that by default, HAProxy works in tunnel mode and
3893 only inspects the first request of a connection, meaning that only the first
3894 request will have the header appended, which is certainly not what you want.
3895 In order to fix this, ensure that any of the "httpclose", "forceclose" or
3896 "http-server-close" options is set when using this option.
Willy Tarreau55165fe2009-05-10 12:02:55 +02003897
3898 Examples :
3899 # Original Destination address
3900 frontend www
3901 mode http
3902 option originalto except 127.0.0.1
3903
3904 # Those servers want the IP Address in X-Client-Dst
3905 backend www
3906 mode http
3907 option originalto header X-Client-Dst
3908
Willy Tarreau87cf5142011-08-19 22:57:24 +02003909 See also : "option httpclose", "option http-server-close",
3910 "option forceclose"
Willy Tarreau55165fe2009-05-10 12:02:55 +02003911
3912
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003913option persist
3914no option persist
3915 Enable or disable forced persistence on down servers
3916 May be used in sections: defaults | frontend | listen | backend
3917 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003918 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003919
3920 When an HTTP request reaches a backend with a cookie which references a dead
3921 server, by default it is redispatched to another server. It is possible to
3922 force the request to be sent to the dead server first using "option persist"
3923 if absolutely needed. A common use case is when servers are under extreme
3924 load and spend their time flapping. In this case, the users would still be
3925 directed to the server they opened the session on, in the hope they would be
3926 correctly served. It is recommended to use "option redispatch" in conjunction
3927 with this option so that in the event it would not be possible to connect to
3928 the server at all (server definitely dead), the client would finally be
3929 redirected to another valid server.
3930
3931 If this option has been enabled in a "defaults" section, it can be disabled
3932 in a specific instance by prepending the "no" keyword before it.
3933
Willy Tarreau4de91492010-01-22 19:10:05 +01003934 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003935
3936
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003937option redispatch
3938no option redispatch
3939 Enable or disable session redistribution in case of connection failure
3940 May be used in sections: defaults | frontend | listen | backend
3941 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003942 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003943
3944 In HTTP mode, if a server designated by a cookie is down, clients may
3945 definitely stick to it because they cannot flush the cookie, so they will not
3946 be able to access the service anymore.
3947
3948 Specifying "option redispatch" will allow the proxy to break their
3949 persistence and redistribute them to a working server.
3950
3951 It also allows to retry last connection to another server in case of multiple
3952 connection failures. Of course, it requires having "retries" set to a nonzero
3953 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01003954
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003955 This form is the preferred form, which replaces both the "redispatch" and
3956 "redisp" keywords.
3957
3958 If this option has been enabled in a "defaults" section, it can be disabled
3959 in a specific instance by prepending the "no" keyword before it.
3960
Willy Tarreau4de91492010-01-22 19:10:05 +01003961 See also : "redispatch", "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01003962
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003963
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02003964option redis-check
3965 Use redis health checks for server testing
3966 May be used in sections : defaults | frontend | listen | backend
3967 yes | no | yes | yes
3968 Arguments : none
3969
3970 It is possible to test that the server correctly talks REDIS protocol instead
3971 of just testing that it accepts the TCP connection. When this option is set,
3972 a PING redis command is sent to the server, and the response is analyzed to
3973 find the "+PONG" response message.
3974
3975 Example :
3976 option redis-check
3977
3978 See also : "option httpchk"
3979
3980
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003981option smtpchk
3982option smtpchk <hello> <domain>
3983 Use SMTP health checks for server testing
3984 May be used in sections : defaults | frontend | listen | backend
3985 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01003986 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003987 <hello> is an optional argument. It is the "hello" command to use. It can
3988 be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other
3989 values will be turned into the default command ("HELO").
3990
3991 <domain> is the domain name to present to the server. It may only be
3992 specified (and is mandatory) if the hello command has been
3993 specified. By default, "localhost" is used.
3994
3995 When "option smtpchk" is set, the health checks will consist in TCP
3996 connections followed by an SMTP command. By default, this command is
3997 "HELO localhost". The server's return code is analyzed and only return codes
3998 starting with a "2" will be considered as valid. All other responses,
3999 including a lack of response will constitute an error and will indicate a
4000 dead server.
4001
4002 This test is meant to be used with SMTP servers or relays. Depending on the
4003 request, it is possible that some servers do not log each connection attempt,
4004 so you may want to experiment to improve the behaviour. Using telnet on port
4005 25 is often easier than adjusting the configuration.
4006
4007 Most often, an incoming SMTP server needs to see the client's IP address for
4008 various purposes, including spam filtering, anti-spoofing and logging. When
4009 possible, it is often wise to masquerade the client's IP address when
4010 connecting to the server using the "usesrc" argument of the "source" keyword,
4011 which requires the cttproxy feature to be compiled in.
4012
4013 Example :
4014 option smtpchk HELO mydomain.org
4015
4016 See also : "option httpchk", "source"
4017
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004018
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02004019option socket-stats
4020no option socket-stats
4021
4022 Enable or disable collecting & providing separate statistics for each socket.
4023 May be used in sections : defaults | frontend | listen | backend
4024 yes | yes | yes | no
4025
4026 Arguments : none
4027
4028
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004029option splice-auto
4030no option splice-auto
4031 Enable or disable automatic kernel acceleration on sockets in both directions
4032 May be used in sections : defaults | frontend | listen | backend
4033 yes | yes | yes | yes
4034 Arguments : none
4035
4036 When this option is enabled either on a frontend or on a backend, haproxy
4037 will automatically evaluate the opportunity to use kernel tcp splicing to
4038 forward data between the client and the server, in either direction. Haproxy
4039 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004040 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004041 are not much aggressive in order to limit excessive use of splicing. This
4042 option requires splicing to be enabled at compile time, and may be globally
4043 disabled with the global option "nosplice". Since splice uses pipes, using it
4044 requires that there are enough spare pipes.
4045
4046 Important note: kernel-based TCP splicing is a Linux-specific feature which
4047 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
4048 transfer data between sockets without copying these data to user-space, thus
4049 providing noticeable performance gains and CPU cycles savings. Since many
4050 early implementations are buggy, corrupt data and/or are inefficient, this
4051 feature is not enabled by default, and it should be used with extreme care.
4052 While it is not possible to detect the correctness of an implementation,
4053 2.6.29 is the first version offering a properly working implementation. In
4054 case of doubt, splicing may be globally disabled using the global "nosplice"
4055 keyword.
4056
4057 Example :
4058 option splice-auto
4059
4060 If this option has been enabled in a "defaults" section, it can be disabled
4061 in a specific instance by prepending the "no" keyword before it.
4062
4063 See also : "option splice-request", "option splice-response", and global
4064 options "nosplice" and "maxpipes"
4065
4066
4067option splice-request
4068no option splice-request
4069 Enable or disable automatic kernel acceleration on sockets for requests
4070 May be used in sections : defaults | frontend | listen | backend
4071 yes | yes | yes | yes
4072 Arguments : none
4073
4074 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004075 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004076 the client to the server. It might still use the recv/send scheme if there
4077 are no spare pipes left. This option requires splicing to be enabled at
4078 compile time, and may be globally disabled with the global option "nosplice".
4079 Since splice uses pipes, using it requires that there are enough spare pipes.
4080
4081 Important note: see "option splice-auto" for usage limitations.
4082
4083 Example :
4084 option splice-request
4085
4086 If this option has been enabled in a "defaults" section, it can be disabled
4087 in a specific instance by prepending the "no" keyword before it.
4088
4089 See also : "option splice-auto", "option splice-response", and global options
4090 "nosplice" and "maxpipes"
4091
4092
4093option splice-response
4094no option splice-response
4095 Enable or disable automatic kernel acceleration on sockets for responses
4096 May be used in sections : defaults | frontend | listen | backend
4097 yes | yes | yes | yes
4098 Arguments : none
4099
4100 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004101 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004102 the server to the client. It might still use the recv/send scheme if there
4103 are no spare pipes left. This option requires splicing to be enabled at
4104 compile time, and may be globally disabled with the global option "nosplice".
4105 Since splice uses pipes, using it requires that there are enough spare pipes.
4106
4107 Important note: see "option splice-auto" for usage limitations.
4108
4109 Example :
4110 option splice-response
4111
4112 If this option has been enabled in a "defaults" section, it can be disabled
4113 in a specific instance by prepending the "no" keyword before it.
4114
4115 See also : "option splice-auto", "option splice-request", and global options
4116 "nosplice" and "maxpipes"
4117
4118
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004119option srvtcpka
4120no option srvtcpka
4121 Enable or disable the sending of TCP keepalive packets on the server side
4122 May be used in sections : defaults | frontend | listen | backend
4123 yes | no | yes | yes
4124 Arguments : none
4125
4126 When there is a firewall or any session-aware component between a client and
4127 a server, and when the protocol involves very long sessions with long idle
4128 periods (eg: remote desktops), there is a risk that one of the intermediate
4129 components decides to expire a session which has remained idle for too long.
4130
4131 Enabling socket-level TCP keep-alives makes the system regularly send packets
4132 to the other end of the connection, leaving it active. The delay between
4133 keep-alive probes is controlled by the system only and depends both on the
4134 operating system and its tuning parameters.
4135
4136 It is important to understand that keep-alive packets are neither emitted nor
4137 received at the application level. It is only the network stacks which sees
4138 them. For this reason, even if one side of the proxy already uses keep-alives
4139 to maintain its connection alive, those keep-alive packets will not be
4140 forwarded to the other side of the proxy.
4141
4142 Please note that this has nothing to do with HTTP keep-alive.
4143
4144 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
4145 server side of a connection, which should help when session expirations are
4146 noticed between HAProxy and a server.
4147
4148 If this option has been enabled in a "defaults" section, it can be disabled
4149 in a specific instance by prepending the "no" keyword before it.
4150
4151 See also : "option clitcpka", "option tcpka"
4152
4153
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004154option ssl-hello-chk
4155 Use SSLv3 client hello health checks for server testing
4156 May be used in sections : defaults | frontend | listen | backend
4157 yes | no | yes | yes
4158 Arguments : none
4159
4160 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
4161 possible to test that the server correctly talks SSL instead of just testing
4162 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
4163 SSLv3 client hello messages are sent once the connection is established to
4164 the server, and the response is analyzed to find an SSL server hello message.
4165 The server is considered valid only when the response contains this server
4166 hello message.
4167
4168 All servers tested till there correctly reply to SSLv3 client hello messages,
4169 and most servers tested do not even log the requests containing only hello
4170 messages, which is appreciable.
4171
Willy Tarreau763a95b2012-10-04 23:15:39 +02004172 Note that this check works even when SSL support was not built into haproxy
4173 because it forges the SSL message. When SSL support is available, it is best
4174 to use native SSL health checks instead of this one.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004175
Willy Tarreau763a95b2012-10-04 23:15:39 +02004176 See also: "option httpchk", "check-ssl"
4177
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004178
Willy Tarreau9ea05a72009-06-14 12:07:01 +02004179option tcp-smart-accept
4180no option tcp-smart-accept
4181 Enable or disable the saving of one ACK packet during the accept sequence
4182 May be used in sections : defaults | frontend | listen | backend
4183 yes | yes | yes | no
4184 Arguments : none
4185
4186 When an HTTP connection request comes in, the system acknowledges it on
4187 behalf of HAProxy, then the client immediately sends its request, and the
4188 system acknowledges it too while it is notifying HAProxy about the new
4189 connection. HAProxy then reads the request and responds. This means that we
4190 have one TCP ACK sent by the system for nothing, because the request could
4191 very well be acknowledged by HAProxy when it sends its response.
4192
4193 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
4194 sending this useless ACK on platforms which support it (currently at least
4195 Linux). It must not cause any problem, because the system will send it anyway
4196 after 40 ms if the response takes more time than expected to come.
4197
4198 During complex network debugging sessions, it may be desirable to disable
4199 this optimization because delayed ACKs can make troubleshooting more complex
4200 when trying to identify where packets are delayed. It is then possible to
4201 fall back to normal behaviour by specifying "no option tcp-smart-accept".
4202
4203 It is also possible to force it for non-HTTP proxies by simply specifying
4204 "option tcp-smart-accept". For instance, it can make sense with some services
4205 such as SMTP where the server speaks first.
4206
4207 It is recommended to avoid forcing this option in a defaults section. In case
4208 of doubt, consider setting it back to automatic values by prepending the
4209 "default" keyword before it, or disabling it using the "no" keyword.
4210
Willy Tarreaud88edf22009-06-14 15:48:17 +02004211 See also : "option tcp-smart-connect"
4212
4213
4214option tcp-smart-connect
4215no option tcp-smart-connect
4216 Enable or disable the saving of one ACK packet during the connect sequence
4217 May be used in sections : defaults | frontend | listen | backend
4218 yes | no | yes | yes
4219 Arguments : none
4220
4221 On certain systems (at least Linux), HAProxy can ask the kernel not to
4222 immediately send an empty ACK upon a connection request, but to directly
4223 send the buffer request instead. This saves one packet on the network and
4224 thus boosts performance. It can also be useful for some servers, because they
4225 immediately get the request along with the incoming connection.
4226
4227 This feature is enabled when "option tcp-smart-connect" is set in a backend.
4228 It is not enabled by default because it makes network troubleshooting more
4229 complex.
4230
4231 It only makes sense to enable it with protocols where the client speaks first
4232 such as HTTP. In other situations, if there is no data to send in place of
4233 the ACK, a normal ACK is sent.
4234
4235 If this option has been enabled in a "defaults" section, it can be disabled
4236 in a specific instance by prepending the "no" keyword before it.
4237
4238 See also : "option tcp-smart-accept"
4239
Willy Tarreau9ea05a72009-06-14 12:07:01 +02004240
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004241option tcpka
4242 Enable or disable the sending of TCP keepalive packets on both sides
4243 May be used in sections : defaults | frontend | listen | backend
4244 yes | yes | yes | yes
4245 Arguments : none
4246
4247 When there is a firewall or any session-aware component between a client and
4248 a server, and when the protocol involves very long sessions with long idle
4249 periods (eg: remote desktops), there is a risk that one of the intermediate
4250 components decides to expire a session which has remained idle for too long.
4251
4252 Enabling socket-level TCP keep-alives makes the system regularly send packets
4253 to the other end of the connection, leaving it active. The delay between
4254 keep-alive probes is controlled by the system only and depends both on the
4255 operating system and its tuning parameters.
4256
4257 It is important to understand that keep-alive packets are neither emitted nor
4258 received at the application level. It is only the network stacks which sees
4259 them. For this reason, even if one side of the proxy already uses keep-alives
4260 to maintain its connection alive, those keep-alive packets will not be
4261 forwarded to the other side of the proxy.
4262
4263 Please note that this has nothing to do with HTTP keep-alive.
4264
4265 Using option "tcpka" enables the emission of TCP keep-alive probes on both
4266 the client and server sides of a connection. Note that this is meaningful
4267 only in "defaults" or "listen" sections. If this option is used in a
4268 frontend, only the client side will get keep-alives, and if this option is
4269 used in a backend, only the server side will get keep-alives. For this
4270 reason, it is strongly recommended to explicitly use "option clitcpka" and
4271 "option srvtcpka" when the configuration is split between frontends and
4272 backends.
4273
4274 See also : "option clitcpka", "option srvtcpka"
4275
Willy Tarreau844e3c52008-01-11 16:28:18 +01004276
4277option tcplog
4278 Enable advanced logging of TCP connections with session state and timers
4279 May be used in sections : defaults | frontend | listen | backend
4280 yes | yes | yes | yes
4281 Arguments : none
4282
4283 By default, the log output format is very poor, as it only contains the
4284 source and destination addresses, and the instance name. By specifying
4285 "option tcplog", each log line turns into a much richer format including, but
4286 not limited to, the connection timers, the session status, the connections
4287 numbers, the frontend, backend and server name, and of course the source
4288 address and ports. This option is useful for pure TCP proxies in order to
4289 find which of the client or server disconnects or times out. For normal HTTP
4290 proxies, it's better to use "option httplog" which is even more complete.
4291
4292 This option may be set either in the frontend or the backend.
4293
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004294 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004295
4296
Willy Tarreau844e3c52008-01-11 16:28:18 +01004297option transparent
4298no option transparent
4299 Enable client-side transparent proxying
4300 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01004301 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01004302 Arguments : none
4303
4304 This option was introduced in order to provide layer 7 persistence to layer 3
4305 load balancers. The idea is to use the OS's ability to redirect an incoming
4306 connection for a remote address to a local process (here HAProxy), and let
4307 this process know what address was initially requested. When this option is
4308 used, sessions without cookies will be forwarded to the original destination
4309 IP address of the incoming request (which should match that of another
4310 equipment), while requests with cookies will still be forwarded to the
4311 appropriate server.
4312
4313 Note that contrary to a common belief, this option does NOT make HAProxy
4314 present the client's IP to the server when establishing the connection.
4315
Willy Tarreaua1146052011-03-01 09:51:54 +01004316 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004317 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004318
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004319
Emeric Brun647caf12009-06-30 17:57:00 +02004320persist rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02004321persist rdp-cookie(<name>)
Emeric Brun647caf12009-06-30 17:57:00 +02004322 Enable RDP cookie-based persistence
4323 May be used in sections : defaults | frontend | listen | backend
4324 yes | no | yes | yes
4325 Arguments :
4326 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02004327 default cookie name "msts" will be used. There currently is no
4328 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02004329
4330 This statement enables persistence based on an RDP cookie. The RDP cookie
4331 contains all information required to find the server in the list of known
4332 servers. So when this option is set in the backend, the request is analysed
4333 and if an RDP cookie is found, it is decoded. If it matches a known server
4334 which is still UP (or if "option persist" is set), then the connection is
4335 forwarded to this server.
4336
4337 Note that this only makes sense in a TCP backend, but for this to work, the
4338 frontend must have waited long enough to ensure that an RDP cookie is present
4339 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004340 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02004341 a single "listen" section.
4342
Willy Tarreau61e28f22010-05-16 22:31:05 +02004343 Also, it is important to understand that the terminal server will emit this
4344 RDP cookie only if it is configured for "token redirection mode", which means
4345 that the "IP address redirection" option is disabled.
4346
Emeric Brun647caf12009-06-30 17:57:00 +02004347 Example :
4348 listen tse-farm
4349 bind :3389
4350 # wait up to 5s for an RDP cookie in the request
4351 tcp-request inspect-delay 5s
4352 tcp-request content accept if RDP_COOKIE
4353 # apply RDP cookie persistence
4354 persist rdp-cookie
4355 # if server is unknown, let's balance on the same cookie.
Cyril Bontédc4d9032012-04-08 21:57:39 +02004356 # alternatively, "balance leastconn" may be useful too.
Emeric Brun647caf12009-06-30 17:57:00 +02004357 balance rdp-cookie
4358 server srv1 1.1.1.1:3389
4359 server srv2 1.1.1.2:3389
4360
Simon Hormanab814e02011-06-24 14:50:20 +09004361 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
4362 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02004363
4364
Willy Tarreau3a7d2072009-03-05 23:48:25 +01004365rate-limit sessions <rate>
4366 Set a limit on the number of new sessions accepted per second on a frontend
4367 May be used in sections : defaults | frontend | listen | backend
4368 yes | yes | yes | no
4369 Arguments :
4370 <rate> The <rate> parameter is an integer designating the maximum number
4371 of new sessions per second to accept on the frontend.
4372
4373 When the frontend reaches the specified number of new sessions per second, it
4374 stops accepting new connections until the rate drops below the limit again.
4375 During this time, the pending sessions will be kept in the socket's backlog
4376 (in system buffers) and haproxy will not even be aware that sessions are
4377 pending. When applying very low limit on a highly loaded service, it may make
4378 sense to increase the socket's backlog using the "backlog" keyword.
4379
4380 This feature is particularly efficient at blocking connection-based attacks
4381 or service abuse on fragile servers. Since the session rate is measured every
4382 millisecond, it is extremely accurate. Also, the limit applies immediately,
4383 no delay is needed at all to detect the threshold.
4384
4385 Example : limit the connection rate on SMTP to 10 per second max
4386 listen smtp
4387 mode tcp
4388 bind :25
4389 rate-limit sessions 10
4390 server 127.0.0.1:1025
4391
Willy Tarreaua17c2d92011-07-25 08:16:20 +02004392 Note : when the maximum rate is reached, the frontend's status is not changed
4393 but its sockets appear as "WAITING" in the statistics if the
4394 "socket-stats" option is enabled.
Willy Tarreau3a7d2072009-03-05 23:48:25 +01004395
4396 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
4397
4398
Willy Tarreau2e1dca82012-09-12 08:43:15 +02004399redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
4400redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
4401redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004402 Return an HTTP redirection if/unless a condition is matched
4403 May be used in sections : defaults | frontend | listen | backend
4404 no | yes | yes | yes
4405
4406 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01004407 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004408
Willy Tarreau0140f252008-11-19 21:07:09 +01004409 Arguments :
Willy Tarreau2e1dca82012-09-12 08:43:15 +02004410 <loc> With "redirect location", the exact value in <loc> is placed into
4411 the HTTP "Location" header.
4412
4413 <pfx> With "redirect prefix", the "Location" header is built from the
4414 concatenation of <pfx> and the complete URI path, including the
4415 query string, unless the "drop-query" option is specified (see
4416 below). As a special case, if <pfx> equals exactly "/", then
4417 nothing is inserted before the original URI. It allows one to
4418 redirect to the same URL (for instance, to insert a cookie).
4419
4420 <sch> With "redirect scheme", then the "Location" header is built by
4421 concatenating <sch> with "://" then the first occurrence of the
4422 "Host" header, and then the URI path, including the query string
4423 unless the "drop-query" option is specified (see below). If no
4424 path is found or if the path is "*", then "/" is used instead. If
4425 no "Host" header is found, then an empty host component will be
4426 returned, which most recent browsers interprete as redirecting to
4427 the same host. This directive is mostly used to redirect HTTP to
4428 HTTPS.
Willy Tarreau0140f252008-11-19 21:07:09 +01004429
4430 <code> The code is optional. It indicates which type of HTTP redirection
4431 is desired. Only codes 301, 302 and 303 are supported, and 302 is
4432 used if no code is specified. 301 means "Moved permanently", and
4433 a browser may cache the Location. 302 means "Moved permanently"
4434 and means that the browser should not cache the redirection. 303
4435 is equivalent to 302 except that the browser will fetch the
4436 location with a GET method.
4437
4438 <option> There are several options which can be specified to adjust the
4439 expected behaviour of a redirection :
4440
4441 - "drop-query"
4442 When this keyword is used in a prefix-based redirection, then the
4443 location will be set without any possible query-string, which is useful
4444 for directing users to a non-secure page for instance. It has no effect
4445 with a location-type redirect.
4446
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01004447 - "append-slash"
4448 This keyword may be used in conjunction with "drop-query" to redirect
4449 users who use a URL not ending with a '/' to the same one with the '/'.
4450 It can be useful to ensure that search engines will only see one URL.
4451 For this, a return code 301 is preferred.
4452
Willy Tarreau0140f252008-11-19 21:07:09 +01004453 - "set-cookie NAME[=value]"
4454 A "Set-Cookie" header will be added with NAME (and optionally "=value")
4455 to the response. This is sometimes used to indicate that a user has
4456 been seen, for instance to protect against some types of DoS. No other
4457 cookie option is added, so the cookie will be a session cookie. Note
4458 that for a browser, a sole cookie name without an equal sign is
4459 different from a cookie with an equal sign.
4460
4461 - "clear-cookie NAME[=]"
4462 A "Set-Cookie" header will be added with NAME (and optionally "="), but
4463 with the "Max-Age" attribute set to zero. This will tell the browser to
4464 delete this cookie. It is useful for instance on logout pages. It is
4465 important to note that clearing the cookie "NAME" will not remove a
4466 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
4467 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004468
4469 Example: move the login URL only to HTTPS.
4470 acl clear dst_port 80
4471 acl secure dst_port 8080
4472 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01004473 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01004474 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01004475 acl cookie_set hdr_sub(cookie) SEEN=1
4476
4477 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01004478 redirect prefix https://mysite.com if login_page !secure
4479 redirect prefix http://mysite.com drop-query if login_page !uid_given
4480 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01004481 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004482
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01004483 Example: send redirects for request for articles without a '/'.
4484 acl missing_slash path_reg ^/article/[^/]*$
4485 redirect code 301 prefix / drop-query append-slash if missing_slash
4486
Willy Tarreau2e1dca82012-09-12 08:43:15 +02004487 Example: redirect all HTTP traffic to HTTPS when SSL is handled by haproxy.
David BERARDe7153042012-11-03 00:11:31 +01004488 redirect scheme https if !{ ssl_fc }
Willy Tarreau2e1dca82012-09-12 08:43:15 +02004489
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004490 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004491
4492
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004493redisp (deprecated)
4494redispatch (deprecated)
4495 Enable or disable session redistribution in case of connection failure
4496 May be used in sections: defaults | frontend | listen | backend
4497 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004498 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004499
4500 In HTTP mode, if a server designated by a cookie is down, clients may
4501 definitely stick to it because they cannot flush the cookie, so they will not
4502 be able to access the service anymore.
4503
4504 Specifying "redispatch" will allow the proxy to break their persistence and
4505 redistribute them to a working server.
4506
4507 It also allows to retry last connection to another server in case of multiple
4508 connection failures. Of course, it requires having "retries" set to a nonzero
4509 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01004510
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004511 This form is deprecated, do not use it in any new configuration, use the new
4512 "option redispatch" instead.
4513
4514 See also : "option redispatch"
4515
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004516
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004517reqadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01004518 Add a header at the end of the HTTP request
4519 May be used in sections : defaults | frontend | listen | backend
4520 no | yes | yes | yes
4521 Arguments :
4522 <string> is the complete line to be added. Any space or known delimiter
4523 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004524 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004525
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004526 <cond> is an optional matching condition built from ACLs. It makes it
4527 possible to ignore this rule when other conditions are not met.
4528
Willy Tarreau303c0352008-01-17 19:01:39 +01004529 A new line consisting in <string> followed by a line feed will be added after
4530 the last header of an HTTP request.
4531
4532 Header transformations only apply to traffic which passes through HAProxy,
4533 and not to traffic generated by HAProxy, such as health-checks or error
4534 responses.
4535
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004536 Example : add "X-Proto: SSL" to requests coming via port 81
4537 acl is-ssl dst_port 81
4538 reqadd X-Proto:\ SSL if is-ssl
4539
4540 See also: "rspadd", section 6 about HTTP header manipulation, and section 7
4541 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004542
4543
Willy Tarreau5321c422010-01-28 20:35:13 +01004544reqallow <search> [{if | unless} <cond>]
4545reqiallow <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004546 Definitely allow an HTTP request if a line matches a regular expression
4547 May be used in sections : defaults | frontend | listen | backend
4548 no | yes | yes | yes
4549 Arguments :
4550 <search> is the regular expression applied to HTTP headers and to the
4551 request line. This is an extended regular expression. Parenthesis
4552 grouping is supported and no preliminary backslash is required.
4553 Any space or known delimiter must be escaped using a backslash
4554 ('\'). The pattern applies to a full line at a time. The
4555 "reqallow" keyword strictly matches case while "reqiallow"
4556 ignores case.
4557
Willy Tarreau5321c422010-01-28 20:35:13 +01004558 <cond> is an optional matching condition built from ACLs. It makes it
4559 possible to ignore this rule when other conditions are not met.
4560
Willy Tarreau303c0352008-01-17 19:01:39 +01004561 A request containing any line which matches extended regular expression
4562 <search> will mark the request as allowed, even if any later test would
4563 result in a deny. The test applies both to the request line and to request
4564 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01004565 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01004566
4567 It is easier, faster and more powerful to use ACLs to write access policies.
4568 Reqdeny, reqallow and reqpass should be avoided in new designs.
4569
4570 Example :
4571 # allow www.* but refuse *.local
4572 reqiallow ^Host:\ www\.
4573 reqideny ^Host:\ .*\.local
4574
Willy Tarreau5321c422010-01-28 20:35:13 +01004575 See also: "reqdeny", "block", section 6 about HTTP header manipulation, and
4576 section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004577
4578
Willy Tarreau5321c422010-01-28 20:35:13 +01004579reqdel <search> [{if | unless} <cond>]
4580reqidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004581 Delete all headers matching a regular expression in an HTTP request
4582 May be used in sections : defaults | frontend | listen | backend
4583 no | yes | yes | yes
4584 Arguments :
4585 <search> is the regular expression applied to HTTP headers and to the
4586 request line. This is an extended regular expression. Parenthesis
4587 grouping is supported and no preliminary backslash is required.
4588 Any space or known delimiter must be escaped using a backslash
4589 ('\'). The pattern applies to a full line at a time. The "reqdel"
4590 keyword strictly matches case while "reqidel" ignores case.
4591
Willy Tarreau5321c422010-01-28 20:35:13 +01004592 <cond> is an optional matching condition built from ACLs. It makes it
4593 possible to ignore this rule when other conditions are not met.
4594
Willy Tarreau303c0352008-01-17 19:01:39 +01004595 Any header line matching extended regular expression <search> in the request
4596 will be completely deleted. Most common use of this is to remove unwanted
4597 and/or dangerous headers or cookies from a request before passing it to the
4598 next servers.
4599
4600 Header transformations only apply to traffic which passes through HAProxy,
4601 and not to traffic generated by HAProxy, such as health-checks or error
4602 responses. Keep in mind that header names are not case-sensitive.
4603
4604 Example :
4605 # remove X-Forwarded-For header and SERVER cookie
4606 reqidel ^X-Forwarded-For:.*
4607 reqidel ^Cookie:.*SERVER=
4608
Willy Tarreau5321c422010-01-28 20:35:13 +01004609 See also: "reqadd", "reqrep", "rspdel", section 6 about HTTP header
4610 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004611
4612
Willy Tarreau5321c422010-01-28 20:35:13 +01004613reqdeny <search> [{if | unless} <cond>]
4614reqideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004615 Deny an HTTP request if a line matches a regular expression
4616 May be used in sections : defaults | frontend | listen | backend
4617 no | yes | yes | yes
4618 Arguments :
4619 <search> is the regular expression applied to HTTP headers and to the
4620 request line. This is an extended regular expression. Parenthesis
4621 grouping is supported and no preliminary backslash is required.
4622 Any space or known delimiter must be escaped using a backslash
4623 ('\'). The pattern applies to a full line at a time. The
4624 "reqdeny" keyword strictly matches case while "reqideny" ignores
4625 case.
4626
Willy Tarreau5321c422010-01-28 20:35:13 +01004627 <cond> is an optional matching condition built from ACLs. It makes it
4628 possible to ignore this rule when other conditions are not met.
4629
Willy Tarreau303c0352008-01-17 19:01:39 +01004630 A request containing any line which matches extended regular expression
4631 <search> will mark the request as denied, even if any later test would
4632 result in an allow. The test applies both to the request line and to request
4633 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01004634 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01004635
Willy Tarreauced27012008-01-17 20:35:34 +01004636 A denied request will generate an "HTTP 403 forbidden" response once the
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004637 complete request has been parsed. This is consistent with what is practiced
Willy Tarreaud72758d2010-01-12 10:42:19 +01004638 using ACLs.
Willy Tarreauced27012008-01-17 20:35:34 +01004639
Willy Tarreau303c0352008-01-17 19:01:39 +01004640 It is easier, faster and more powerful to use ACLs to write access policies.
4641 Reqdeny, reqallow and reqpass should be avoided in new designs.
4642
4643 Example :
4644 # refuse *.local, then allow www.*
4645 reqideny ^Host:\ .*\.local
4646 reqiallow ^Host:\ www\.
4647
Willy Tarreau5321c422010-01-28 20:35:13 +01004648 See also: "reqallow", "rspdeny", "block", section 6 about HTTP header
4649 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004650
4651
Willy Tarreau5321c422010-01-28 20:35:13 +01004652reqpass <search> [{if | unless} <cond>]
4653reqipass <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004654 Ignore any HTTP request line matching a regular expression in next rules
4655 May be used in sections : defaults | frontend | listen | backend
4656 no | yes | yes | yes
4657 Arguments :
4658 <search> is the regular expression applied to HTTP headers and to the
4659 request line. This is an extended regular expression. Parenthesis
4660 grouping is supported and no preliminary backslash is required.
4661 Any space or known delimiter must be escaped using a backslash
4662 ('\'). The pattern applies to a full line at a time. The
4663 "reqpass" keyword strictly matches case while "reqipass" ignores
4664 case.
4665
Willy Tarreau5321c422010-01-28 20:35:13 +01004666 <cond> is an optional matching condition built from ACLs. It makes it
4667 possible to ignore this rule when other conditions are not met.
4668
Willy Tarreau303c0352008-01-17 19:01:39 +01004669 A request containing any line which matches extended regular expression
4670 <search> will skip next rules, without assigning any deny or allow verdict.
4671 The test applies both to the request line and to request headers. Keep in
4672 mind that URLs in request line are case-sensitive while header names are not.
4673
4674 It is easier, faster and more powerful to use ACLs to write access policies.
4675 Reqdeny, reqallow and reqpass should be avoided in new designs.
4676
4677 Example :
4678 # refuse *.local, then allow www.*, but ignore "www.private.local"
4679 reqipass ^Host:\ www.private\.local
4680 reqideny ^Host:\ .*\.local
4681 reqiallow ^Host:\ www\.
4682
Willy Tarreau5321c422010-01-28 20:35:13 +01004683 See also: "reqallow", "reqdeny", "block", section 6 about HTTP header
4684 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004685
4686
Willy Tarreau5321c422010-01-28 20:35:13 +01004687reqrep <search> <string> [{if | unless} <cond>]
4688reqirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004689 Replace a regular expression with a string in an HTTP request line
4690 May be used in sections : defaults | frontend | listen | backend
4691 no | yes | yes | yes
4692 Arguments :
4693 <search> is the regular expression applied to HTTP headers and to the
4694 request line. This is an extended regular expression. Parenthesis
4695 grouping is supported and no preliminary backslash is required.
4696 Any space or known delimiter must be escaped using a backslash
4697 ('\'). The pattern applies to a full line at a time. The "reqrep"
4698 keyword strictly matches case while "reqirep" ignores case.
4699
4700 <string> is the complete line to be added. Any space or known delimiter
4701 must be escaped using a backslash ('\'). References to matched
4702 pattern groups are possible using the common \N form, with N
4703 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004704 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004705
Willy Tarreau5321c422010-01-28 20:35:13 +01004706 <cond> is an optional matching condition built from ACLs. It makes it
4707 possible to ignore this rule when other conditions are not met.
4708
Willy Tarreau303c0352008-01-17 19:01:39 +01004709 Any line matching extended regular expression <search> in the request (both
4710 the request line and header lines) will be completely replaced with <string>.
4711 Most common use of this is to rewrite URLs or domain names in "Host" headers.
4712
4713 Header transformations only apply to traffic which passes through HAProxy,
4714 and not to traffic generated by HAProxy, such as health-checks or error
4715 responses. Note that for increased readability, it is suggested to add enough
4716 spaces between the request and the response. Keep in mind that URLs in
4717 request line are case-sensitive while header names are not.
4718
4719 Example :
4720 # replace "/static/" with "/" at the beginning of any request path.
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04004721 reqrep ^([^\ :]*)\ /static/(.*) \1\ /\2
Willy Tarreau303c0352008-01-17 19:01:39 +01004722 # replace "www.mydomain.com" with "www" in the host name.
4723 reqirep ^Host:\ www.mydomain.com Host:\ www
4724
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +04004725 See also: "reqadd", "reqdel", "rsprep", "tune.bufsize", section 6 about
4726 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004727
4728
Willy Tarreau5321c422010-01-28 20:35:13 +01004729reqtarpit <search> [{if | unless} <cond>]
4730reqitarpit <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004731 Tarpit an HTTP request containing a line matching a regular expression
4732 May be used in sections : defaults | frontend | listen | backend
4733 no | yes | yes | yes
4734 Arguments :
4735 <search> is the regular expression applied to HTTP headers and to the
4736 request line. This is an extended regular expression. Parenthesis
4737 grouping is supported and no preliminary backslash is required.
4738 Any space or known delimiter must be escaped using a backslash
4739 ('\'). The pattern applies to a full line at a time. The
4740 "reqtarpit" keyword strictly matches case while "reqitarpit"
4741 ignores case.
4742
Willy Tarreau5321c422010-01-28 20:35:13 +01004743 <cond> is an optional matching condition built from ACLs. It makes it
4744 possible to ignore this rule when other conditions are not met.
4745
Willy Tarreau303c0352008-01-17 19:01:39 +01004746 A request containing any line which matches extended regular expression
4747 <search> will be tarpitted, which means that it will connect to nowhere, will
Willy Tarreauced27012008-01-17 20:35:34 +01004748 be kept open for a pre-defined time, then will return an HTTP error 500 so
4749 that the attacker does not suspect it has been tarpitted. The status 500 will
4750 be reported in the logs, but the completion flags will indicate "PT". The
Willy Tarreau303c0352008-01-17 19:01:39 +01004751 delay is defined by "timeout tarpit", or "timeout connect" if the former is
4752 not set.
4753
4754 The goal of the tarpit is to slow down robots attacking servers with
4755 identifiable requests. Many robots limit their outgoing number of connections
4756 and stay connected waiting for a reply which can take several minutes to
4757 come. Depending on the environment and attack, it may be particularly
4758 efficient at reducing the load on the network and firewalls.
4759
Willy Tarreau5321c422010-01-28 20:35:13 +01004760 Examples :
Willy Tarreau303c0352008-01-17 19:01:39 +01004761 # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but
4762 # block all others.
4763 reqipass ^User-Agent:\.*(Mozilla|MSIE)
4764 reqitarpit ^User-Agent:
4765
Willy Tarreau5321c422010-01-28 20:35:13 +01004766 # block bad guys
4767 acl badguys src 10.1.0.3 172.16.13.20/28
4768 reqitarpit . if badguys
4769
4770 See also: "reqallow", "reqdeny", "reqpass", section 6 about HTTP header
4771 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004772
4773
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02004774retries <value>
4775 Set the number of retries to perform on a server after a connection failure
4776 May be used in sections: defaults | frontend | listen | backend
4777 yes | no | yes | yes
4778 Arguments :
4779 <value> is the number of times a connection attempt should be retried on
4780 a server when a connection either is refused or times out. The
4781 default value is 3.
4782
4783 It is important to understand that this value applies to the number of
4784 connection attempts, not full requests. When a connection has effectively
4785 been established to a server, there will be no more retry.
4786
4787 In order to avoid immediate reconnections to a server which is restarting,
4788 a turn-around timer of 1 second is applied before a retry occurs.
4789
4790 When "option redispatch" is set, the last retry may be performed on another
4791 server even if a cookie references a different server.
4792
4793 See also : "option redispatch"
4794
4795
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004796rspadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01004797 Add a header at the end of the HTTP response
4798 May be used in sections : defaults | frontend | listen | backend
4799 no | yes | yes | yes
4800 Arguments :
4801 <string> is the complete line to be added. Any space or known delimiter
4802 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004803 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004804
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004805 <cond> is an optional matching condition built from ACLs. It makes it
4806 possible to ignore this rule when other conditions are not met.
4807
Willy Tarreau303c0352008-01-17 19:01:39 +01004808 A new line consisting in <string> followed by a line feed will be added after
4809 the last header of an HTTP response.
4810
4811 Header transformations only apply to traffic which passes through HAProxy,
4812 and not to traffic generated by HAProxy, such as health-checks or error
4813 responses.
4814
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004815 See also: "reqadd", section 6 about HTTP header manipulation, and section 7
4816 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004817
4818
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004819rspdel <search> [{if | unless} <cond>]
4820rspidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004821 Delete all headers matching a regular expression in an HTTP response
4822 May be used in sections : defaults | frontend | listen | backend
4823 no | yes | yes | yes
4824 Arguments :
4825 <search> is the regular expression applied to HTTP headers and to the
4826 response line. This is an extended regular expression, so
4827 parenthesis grouping is supported and no preliminary backslash
4828 is required. Any space or known delimiter must be escaped using
4829 a backslash ('\'). The pattern applies to a full line at a time.
4830 The "rspdel" keyword strictly matches case while "rspidel"
4831 ignores case.
4832
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004833 <cond> is an optional matching condition built from ACLs. It makes it
4834 possible to ignore this rule when other conditions are not met.
4835
Willy Tarreau303c0352008-01-17 19:01:39 +01004836 Any header line matching extended regular expression <search> in the response
4837 will be completely deleted. Most common use of this is to remove unwanted
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02004838 and/or sensitive headers or cookies from a response before passing it to the
Willy Tarreau303c0352008-01-17 19:01:39 +01004839 client.
4840
4841 Header transformations only apply to traffic which passes through HAProxy,
4842 and not to traffic generated by HAProxy, such as health-checks or error
4843 responses. Keep in mind that header names are not case-sensitive.
4844
4845 Example :
4846 # remove the Server header from responses
4847 reqidel ^Server:.*
4848
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004849 See also: "rspadd", "rsprep", "reqdel", section 6 about HTTP header
4850 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004851
4852
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004853rspdeny <search> [{if | unless} <cond>]
4854rspideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004855 Block an HTTP response if a line matches a regular expression
4856 May be used in sections : defaults | frontend | listen | backend
4857 no | yes | yes | yes
4858 Arguments :
4859 <search> is the regular expression applied to HTTP headers and to the
4860 response line. This is an extended regular expression, so
4861 parenthesis grouping is supported and no preliminary backslash
4862 is required. Any space or known delimiter must be escaped using
4863 a backslash ('\'). The pattern applies to a full line at a time.
4864 The "rspdeny" keyword strictly matches case while "rspideny"
4865 ignores case.
4866
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004867 <cond> is an optional matching condition built from ACLs. It makes it
4868 possible to ignore this rule when other conditions are not met.
4869
Willy Tarreau303c0352008-01-17 19:01:39 +01004870 A response containing any line which matches extended regular expression
4871 <search> will mark the request as denied. The test applies both to the
4872 response line and to response headers. Keep in mind that header names are not
4873 case-sensitive.
4874
4875 Main use of this keyword is to prevent sensitive information leak and to
Willy Tarreauced27012008-01-17 20:35:34 +01004876 block the response before it reaches the client. If a response is denied, it
4877 will be replaced with an HTTP 502 error so that the client never retrieves
4878 any sensitive data.
Willy Tarreau303c0352008-01-17 19:01:39 +01004879
4880 It is easier, faster and more powerful to use ACLs to write access policies.
4881 Rspdeny should be avoided in new designs.
4882
4883 Example :
4884 # Ensure that no content type matching ms-word will leak
4885 rspideny ^Content-type:\.*/ms-word
4886
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004887 See also: "reqdeny", "acl", "block", section 6 about HTTP header manipulation
4888 and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004889
4890
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004891rsprep <search> <string> [{if | unless} <cond>]
4892rspirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004893 Replace a regular expression with a string in an HTTP response line
4894 May be used in sections : defaults | frontend | listen | backend
4895 no | yes | yes | yes
4896 Arguments :
4897 <search> is the regular expression applied to HTTP headers and to the
4898 response line. This is an extended regular expression, so
4899 parenthesis grouping is supported and no preliminary backslash
4900 is required. Any space or known delimiter must be escaped using
4901 a backslash ('\'). The pattern applies to a full line at a time.
4902 The "rsprep" keyword strictly matches case while "rspirep"
4903 ignores case.
4904
4905 <string> is the complete line to be added. Any space or known delimiter
4906 must be escaped using a backslash ('\'). References to matched
4907 pattern groups are possible using the common \N form, with N
4908 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004909 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004910
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004911 <cond> is an optional matching condition built from ACLs. It makes it
4912 possible to ignore this rule when other conditions are not met.
4913
Willy Tarreau303c0352008-01-17 19:01:39 +01004914 Any line matching extended regular expression <search> in the response (both
4915 the response line and header lines) will be completely replaced with
4916 <string>. Most common use of this is to rewrite Location headers.
4917
4918 Header transformations only apply to traffic which passes through HAProxy,
4919 and not to traffic generated by HAProxy, such as health-checks or error
4920 responses. Note that for increased readability, it is suggested to add enough
4921 spaces between the request and the response. Keep in mind that header names
4922 are not case-sensitive.
4923
4924 Example :
4925 # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com"
4926 rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com
4927
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004928 See also: "rspadd", "rspdel", "reqrep", section 6 about HTTP header
4929 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004930
4931
David du Colombier486df472011-03-17 10:40:26 +01004932server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004933 Declare a server in a backend
4934 May be used in sections : defaults | frontend | listen | backend
4935 no | no | yes | yes
4936 Arguments :
4937 <name> is the internal name assigned to this server. This name will
Cyril Bonté941a0c62012-10-15 19:44:24 +02004938 appear in logs and alerts. If "http-send-name-header" is
Mark Lamourinec2247f02012-01-04 13:02:01 -05004939 set, it will be added to the request header sent to the server.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004940
David du Colombier486df472011-03-17 10:40:26 +01004941 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
4942 resolvable hostname is supported, but this name will be resolved
4943 during start-up. Address "0.0.0.0" or "*" has a special meaning.
4944 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +02004945 address as the one from the client connection. This is useful in
4946 transparent proxy architectures where the client's connection is
4947 intercepted and haproxy must forward to the original destination
4948 address. This is more or less what the "transparent" keyword does
4949 except that with a server it's possible to limit concurrency and
4950 to report statistics.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004951
Willy Tarreaub6205fd2012-09-24 12:27:33 +02004952 <port> is an optional port specification. If set, all connections will
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004953 be sent to this port. If unset, the same port the client
4954 connected to will be used. The port may also be prefixed by a "+"
4955 or a "-". In this case, the server's port will be determined by
4956 adding this value to the client's port.
4957
4958 <param*> is a list of parameters for this server. The "server" keywords
4959 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004960 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004961
4962 Examples :
4963 server first 10.1.1.1:1080 cookie first check inter 1000
4964 server second 10.1.1.2:1080 cookie second check inter 1000
4965
Mark Lamourinec2247f02012-01-04 13:02:01 -05004966 See also: "default-server", "http-send-name-header" and section 5 about
4967 server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004968
4969
4970source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02004971source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01004972source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004973 Set the source address for outgoing connections
4974 May be used in sections : defaults | frontend | listen | backend
4975 yes | no | yes | yes
4976 Arguments :
4977 <addr> is the IPv4 address HAProxy will bind to before connecting to a
4978 server. This address is also used as a source for health checks.
4979 The default value of 0.0.0.0 means that the system will select
4980 the most appropriate address to reach its destination.
4981
4982 <port> is an optional port. It is normally not needed but may be useful
4983 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02004984 the system will select a free port. Note that port ranges are not
4985 supported in the backend. If you want to force port ranges, you
4986 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004987
4988 <addr2> is the IP address to present to the server when connections are
4989 forwarded in full transparent proxy mode. This is currently only
4990 supported on some patched Linux kernels. When this address is
4991 specified, clients connecting to the server will be presented
4992 with this address, while health checks will still use the address
4993 <addr>.
4994
4995 <port2> is the optional port to present to the server when connections
4996 are forwarded in full transparent proxy mode (see <addr2> above).
4997 The default value of zero means the system will select a free
4998 port.
4999
Willy Tarreaubce70882009-09-07 11:51:47 +02005000 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
5001 This is the name of a comma-separated header list which can
5002 contain multiple IP addresses. By default, the last occurrence is
5003 used. This is designed to work with the X-Forwarded-For header
5004 and to automatically bind to the the client's IP address as seen
5005 by previous proxy, typically Stunnel. In order to use another
5006 occurrence from the last one, please see the <occ> parameter
5007 below. When the header (or occurrence) is not found, no binding
5008 is performed so that the proxy's default IP address is used. Also
5009 keep in mind that the header name is case insensitive, as for any
5010 HTTP header.
5011
5012 <occ> is the occurrence number of a value to be used in a multi-value
5013 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04005014 in order to specify which occurrence to use for the source IP
Willy Tarreaubce70882009-09-07 11:51:47 +02005015 address. Positive values indicate a position from the first
5016 occurrence, 1 being the first one. Negative values indicate
5017 positions relative to the last one, -1 being the last one. This
5018 is helpful for situations where an X-Forwarded-For header is set
5019 at the entry point of an infrastructure and must be used several
5020 proxy layers away. When this value is not specified, -1 is
5021 assumed. Passing a zero here disables the feature.
5022
Willy Tarreaud53f96b2009-02-04 18:46:54 +01005023 <name> is an optional interface name to which to bind to for outgoing
5024 traffic. On systems supporting this features (currently, only
5025 Linux), this allows one to bind all traffic to the server to
5026 this interface even if it is not the one the system would select
5027 based on routing tables. This should be used with extreme care.
5028 Note that using this option requires root privileges.
5029
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005030 The "source" keyword is useful in complex environments where a specific
5031 address only is allowed to connect to the servers. It may be needed when a
5032 private address must be used through a public gateway for instance, and it is
5033 known that the system cannot determine the adequate source address by itself.
5034
5035 An extension which is available on certain patched Linux kernels may be used
5036 through the "usesrc" optional keyword. It makes it possible to connect to the
5037 servers with an IP address which does not belong to the system itself. This
5038 is called "full transparent proxy mode". For this to work, the destination
5039 servers have to route their traffic back to this address through the machine
5040 running HAProxy, and IP forwarding must generally be enabled on this machine.
5041
5042 In this "full transparent proxy" mode, it is possible to force a specific IP
5043 address to be presented to the servers. This is not much used in fact. A more
5044 common use is to tell HAProxy to present the client's IP address. For this,
5045 there are two methods :
5046
5047 - present the client's IP and port addresses. This is the most transparent
5048 mode, but it can cause problems when IP connection tracking is enabled on
5049 the machine, because a same connection may be seen twice with different
5050 states. However, this solution presents the huge advantage of not
5051 limiting the system to the 64k outgoing address+port couples, because all
5052 of the client ranges may be used.
5053
5054 - present only the client's IP address and select a spare port. This
5055 solution is still quite elegant but slightly less transparent (downstream
5056 firewalls logs will not match upstream's). It also presents the downside
5057 of limiting the number of concurrent connections to the usual 64k ports.
5058 However, since the upstream and downstream ports are different, local IP
5059 connection tracking on the machine will not be upset by the reuse of the
5060 same session.
5061
5062 Note that depending on the transparent proxy technology used, it may be
5063 required to force the source address. In fact, cttproxy version 2 requires an
5064 IP address in <addr> above, and does not support setting of "0.0.0.0" as the
5065 IP address because it creates NAT entries which much match the exact outgoing
5066 address. Tproxy version 4 and some other kernel patches which work in pure
5067 forwarding mode generally will not have this limitation.
5068
5069 This option sets the default source for all servers in the backend. It may
5070 also be specified in a "defaults" section. Finer source address specification
5071 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005072 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005073
5074 Examples :
5075 backend private
5076 # Connect to the servers using our 192.168.1.200 source address
5077 source 192.168.1.200
5078
5079 backend transparent_ssl1
5080 # Connect to the SSL farm from the client's source address
5081 source 192.168.1.200 usesrc clientip
5082
5083 backend transparent_ssl2
5084 # Connect to the SSL farm from the client's source address and port
5085 # not recommended if IP conntrack is present on the local machine.
5086 source 192.168.1.200 usesrc client
5087
5088 backend transparent_ssl3
5089 # Connect to the SSL farm from the client's source address. It
5090 # is more conntrack-friendly.
5091 source 192.168.1.200 usesrc clientip
5092
5093 backend transparent_smtp
5094 # Connect to the SMTP farm from the client's source address/port
5095 # with Tproxy version 4.
5096 source 0.0.0.0 usesrc clientip
5097
Willy Tarreaubce70882009-09-07 11:51:47 +02005098 backend transparent_http
5099 # Connect to the servers using the client's IP as seen by previous
5100 # proxy.
5101 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
5102
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005103 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005104 the Linux kernel on www.balabit.com, the "bind" keyword.
5105
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005106
Willy Tarreau844e3c52008-01-11 16:28:18 +01005107srvtimeout <timeout> (deprecated)
5108 Set the maximum inactivity time on the server side.
5109 May be used in sections : defaults | frontend | listen | backend
5110 yes | no | yes | yes
5111 Arguments :
5112 <timeout> is the timeout value specified in milliseconds by default, but
5113 can be in any other unit if the number is suffixed by the unit,
5114 as explained at the top of this document.
5115
5116 The inactivity timeout applies when the server is expected to acknowledge or
5117 send data. In HTTP mode, this timeout is particularly important to consider
5118 during the first phase of the server's response, when it has to send the
5119 headers, as it directly represents the server's processing time for the
5120 request. To find out what value to put there, it's often good to start with
5121 what would be considered as unacceptable response times, then check the logs
5122 to observe the response time distribution, and adjust the value accordingly.
5123
5124 The value is specified in milliseconds by default, but can be in any other
5125 unit if the number is suffixed by the unit, as specified at the top of this
5126 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
5127 recommended that the client timeout remains equal to the server timeout in
5128 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01005129 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01005130 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreaud72758d2010-01-12 10:42:19 +01005131 seconds (eg: 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01005132
5133 This parameter is specific to backends, but can be specified once for all in
5134 "defaults" sections. This is in fact one of the easiest solutions not to
5135 forget about it. An unspecified timeout results in an infinite timeout, which
5136 is not recommended. Such a usage is accepted and works but reports a warning
5137 during startup because it may results in accumulation of expired sessions in
5138 the system if the system's timeouts are not configured either.
5139
5140 This parameter is provided for compatibility but is currently deprecated.
5141 Please use "timeout server" instead.
5142
Willy Tarreauce887fd2012-05-12 12:50:00 +02005143 See also : "timeout server", "timeout tunnel", "timeout client" and
5144 "clitimeout".
Willy Tarreau844e3c52008-01-11 16:28:18 +01005145
5146
Cyril Bonté66c327d2010-10-12 00:14:37 +02005147stats admin { if | unless } <cond>
5148 Enable statistics admin level if/unless a condition is matched
5149 May be used in sections : defaults | frontend | listen | backend
5150 no | no | yes | yes
5151
5152 This statement enables the statistics admin level if/unless a condition is
5153 matched.
5154
5155 The admin level allows to enable/disable servers from the web interface. By
5156 default, statistics page is read-only for security reasons.
5157
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005158 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5159 unless you know what you do : memory is not shared between the
5160 processes, which can result in random behaviours.
5161
Cyril Bonté23b39d92011-02-10 22:54:44 +01005162 Currently, the POST request is limited to the buffer size minus the reserved
5163 buffer space, which means that if the list of servers is too long, the
5164 request won't be processed. It is recommended to alter few servers at a
5165 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02005166
5167 Example :
5168 # statistics admin level only for localhost
5169 backend stats_localhost
5170 stats enable
5171 stats admin if LOCALHOST
5172
5173 Example :
5174 # statistics admin level always enabled because of the authentication
5175 backend stats_auth
5176 stats enable
5177 stats auth admin:AdMiN123
5178 stats admin if TRUE
5179
5180 Example :
5181 # statistics admin level depends on the authenticated user
5182 userlist stats-auth
5183 group admin users admin
5184 user admin insecure-password AdMiN123
5185 group readonly users haproxy
5186 user haproxy insecure-password haproxy
5187
5188 backend stats_auth
5189 stats enable
5190 acl AUTH http_auth(stats-auth)
5191 acl AUTH_ADMIN http_auth_group(stats-auth) admin
5192 stats http-request auth unless AUTH
5193 stats admin if AUTH_ADMIN
5194
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005195 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
5196 "bind-process", section 3.4 about userlists and section 7 about
5197 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02005198
5199
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005200stats auth <user>:<passwd>
5201 Enable statistics with authentication and grant access to an account
5202 May be used in sections : defaults | frontend | listen | backend
5203 yes | no | yes | yes
5204 Arguments :
5205 <user> is a user name to grant access to
5206
5207 <passwd> is the cleartext password associated to this user
5208
5209 This statement enables statistics with default settings, and restricts access
5210 to declared users only. It may be repeated as many times as necessary to
5211 allow as many users as desired. When a user tries to access the statistics
5212 without a valid account, a "401 Forbidden" response will be returned so that
5213 the browser asks the user to provide a valid user and password. The real
5214 which will be returned to the browser is configurable using "stats realm".
5215
5216 Since the authentication method is HTTP Basic Authentication, the passwords
5217 circulate in cleartext on the network. Thus, it was decided that the
5218 configuration file would also use cleartext passwords to remind the users
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02005219 that those ones should not be sensitive and not shared with any other account.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005220
5221 It is also possible to reduce the scope of the proxies which appear in the
5222 report using "stats scope".
5223
5224 Though this statement alone is enough to enable statistics reporting, it is
5225 recommended to set all other settings in order to avoid relying on default
5226 unobvious parameters.
5227
5228 Example :
5229 # public access (limited to this backend only)
5230 backend public_www
5231 server srv1 192.168.0.1:80
5232 stats enable
5233 stats hide-version
5234 stats scope .
5235 stats uri /admin?stats
5236 stats realm Haproxy\ Statistics
5237 stats auth admin1:AdMiN123
5238 stats auth admin2:AdMiN321
5239
5240 # internal monitoring access (unlimited)
5241 backend private_monitoring
5242 stats enable
5243 stats uri /admin?stats
5244 stats refresh 5s
5245
5246 See also : "stats enable", "stats realm", "stats scope", "stats uri"
5247
5248
5249stats enable
5250 Enable statistics reporting with default settings
5251 May be used in sections : defaults | frontend | listen | backend
5252 yes | no | yes | yes
5253 Arguments : none
5254
5255 This statement enables statistics reporting with default settings defined
5256 at build time. Unless stated otherwise, these settings are used :
5257 - stats uri : /haproxy?stats
5258 - stats realm : "HAProxy Statistics"
5259 - stats auth : no authentication
5260 - stats scope : no restriction
5261
5262 Though this statement alone is enough to enable statistics reporting, it is
5263 recommended to set all other settings in order to avoid relying on default
5264 unobvious parameters.
5265
5266 Example :
5267 # public access (limited to this backend only)
5268 backend public_www
5269 server srv1 192.168.0.1:80
5270 stats enable
5271 stats hide-version
5272 stats scope .
5273 stats uri /admin?stats
5274 stats realm Haproxy\ Statistics
5275 stats auth admin1:AdMiN123
5276 stats auth admin2:AdMiN321
5277
5278 # internal monitoring access (unlimited)
5279 backend private_monitoring
5280 stats enable
5281 stats uri /admin?stats
5282 stats refresh 5s
5283
5284 See also : "stats auth", "stats realm", "stats uri"
5285
5286
Willy Tarreaud63335a2010-02-26 12:56:52 +01005287stats hide-version
5288 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005289 May be used in sections : defaults | frontend | listen | backend
5290 yes | no | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01005291 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005292
Willy Tarreaud63335a2010-02-26 12:56:52 +01005293 By default, the stats page reports some useful status information along with
5294 the statistics. Among them is HAProxy's version. However, it is generally
5295 considered dangerous to report precise version to anyone, as it can help them
5296 target known weaknesses with specific attacks. The "stats hide-version"
5297 statement removes the version from the statistics report. This is recommended
5298 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005299
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02005300 Though this statement alone is enough to enable statistics reporting, it is
5301 recommended to set all other settings in order to avoid relying on default
5302 unobvious parameters.
5303
Willy Tarreaud63335a2010-02-26 12:56:52 +01005304 Example :
5305 # public access (limited to this backend only)
5306 backend public_www
5307 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02005308 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01005309 stats hide-version
5310 stats scope .
5311 stats uri /admin?stats
5312 stats realm Haproxy\ Statistics
5313 stats auth admin1:AdMiN123
5314 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005315
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005316 # internal monitoring access (unlimited)
5317 backend private_monitoring
5318 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01005319 stats uri /admin?stats
5320 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01005321
Willy Tarreaud63335a2010-02-26 12:56:52 +01005322 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005323
Willy Tarreau983e01e2010-01-11 18:42:06 +01005324
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02005325stats http-request { allow | deny | auth [realm <realm>] }
5326 [ { if | unless } <condition> ]
5327 Access control for statistics
5328
5329 May be used in sections: defaults | frontend | listen | backend
5330 no | no | yes | yes
5331
5332 As "http-request", these set of options allow to fine control access to
5333 statistics. Each option may be followed by if/unless and acl.
5334 First option with matched condition (or option without condition) is final.
5335 For "deny" a 403 error will be returned, for "allow" normal processing is
5336 performed, for "auth" a 401/407 error code is returned so the client
5337 should be asked to enter a username and password.
5338
5339 There is no fixed limit to the number of http-request statements per
5340 instance.
5341
5342 See also : "http-request", section 3.4 about userlists and section 7
5343 about ACL usage.
5344
5345
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005346stats realm <realm>
5347 Enable statistics and set authentication realm
5348 May be used in sections : defaults | frontend | listen | backend
5349 yes | no | yes | yes
5350 Arguments :
5351 <realm> is the name of the HTTP Basic Authentication realm reported to
5352 the browser. The browser uses it to display it in the pop-up
5353 inviting the user to enter a valid username and password.
5354
5355 The realm is read as a single word, so any spaces in it should be escaped
5356 using a backslash ('\').
5357
5358 This statement is useful only in conjunction with "stats auth" since it is
5359 only related to authentication.
5360
5361 Though this statement alone is enough to enable statistics reporting, it is
5362 recommended to set all other settings in order to avoid relying on default
5363 unobvious parameters.
5364
5365 Example :
5366 # public access (limited to this backend only)
5367 backend public_www
5368 server srv1 192.168.0.1:80
5369 stats enable
5370 stats hide-version
5371 stats scope .
5372 stats uri /admin?stats
5373 stats realm Haproxy\ Statistics
5374 stats auth admin1:AdMiN123
5375 stats auth admin2:AdMiN321
5376
5377 # internal monitoring access (unlimited)
5378 backend private_monitoring
5379 stats enable
5380 stats uri /admin?stats
5381 stats refresh 5s
5382
5383 See also : "stats auth", "stats enable", "stats uri"
5384
5385
5386stats refresh <delay>
5387 Enable statistics with automatic refresh
5388 May be used in sections : defaults | frontend | listen | backend
5389 yes | no | yes | yes
5390 Arguments :
5391 <delay> is the suggested refresh delay, specified in seconds, which will
5392 be returned to the browser consulting the report page. While the
5393 browser is free to apply any delay, it will generally respect it
5394 and refresh the page this every seconds. The refresh interval may
5395 be specified in any other non-default time unit, by suffixing the
5396 unit after the value, as explained at the top of this document.
5397
5398 This statement is useful on monitoring displays with a permanent page
5399 reporting the load balancer's activity. When set, the HTML report page will
5400 include a link "refresh"/"stop refresh" so that the user can select whether
5401 he wants automatic refresh of the page or not.
5402
5403 Though this statement alone is enough to enable statistics reporting, it is
5404 recommended to set all other settings in order to avoid relying on default
5405 unobvious parameters.
5406
5407 Example :
5408 # public access (limited to this backend only)
5409 backend public_www
5410 server srv1 192.168.0.1:80
5411 stats enable
5412 stats hide-version
5413 stats scope .
5414 stats uri /admin?stats
5415 stats realm Haproxy\ Statistics
5416 stats auth admin1:AdMiN123
5417 stats auth admin2:AdMiN321
5418
5419 # internal monitoring access (unlimited)
5420 backend private_monitoring
5421 stats enable
5422 stats uri /admin?stats
5423 stats refresh 5s
5424
5425 See also : "stats auth", "stats enable", "stats realm", "stats uri"
5426
5427
5428stats scope { <name> | "." }
5429 Enable statistics and limit access scope
5430 May be used in sections : defaults | frontend | listen | backend
5431 yes | no | yes | yes
5432 Arguments :
5433 <name> is the name of a listen, frontend or backend section to be
5434 reported. The special name "." (a single dot) designates the
5435 section in which the statement appears.
5436
5437 When this statement is specified, only the sections enumerated with this
5438 statement will appear in the report. All other ones will be hidden. This
5439 statement may appear as many times as needed if multiple sections need to be
5440 reported. Please note that the name checking is performed as simple string
5441 comparisons, and that it is never checked that a give section name really
5442 exists.
5443
5444 Though this statement alone is enough to enable statistics reporting, it is
5445 recommended to set all other settings in order to avoid relying on default
5446 unobvious parameters.
5447
5448 Example :
5449 # public access (limited to this backend only)
5450 backend public_www
5451 server srv1 192.168.0.1:80
5452 stats enable
5453 stats hide-version
5454 stats scope .
5455 stats uri /admin?stats
5456 stats realm Haproxy\ Statistics
5457 stats auth admin1:AdMiN123
5458 stats auth admin2:AdMiN321
5459
5460 # internal monitoring access (unlimited)
5461 backend private_monitoring
5462 stats enable
5463 stats uri /admin?stats
5464 stats refresh 5s
5465
5466 See also : "stats auth", "stats enable", "stats realm", "stats uri"
5467
Willy Tarreaud63335a2010-02-26 12:56:52 +01005468
Willy Tarreauc9705a12010-07-27 20:05:50 +02005469stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01005470 Enable reporting of a description on the statistics page.
5471 May be used in sections : defaults | frontend | listen | backend
5472 yes | no | yes | yes
5473
Willy Tarreauc9705a12010-07-27 20:05:50 +02005474 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01005475 description from global section is automatically used instead.
5476
5477 This statement is useful for users that offer shared services to their
5478 customers, where node or description should be different for each customer.
5479
5480 Though this statement alone is enough to enable statistics reporting, it is
5481 recommended to set all other settings in order to avoid relying on default
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04005482 unobvious parameters. By default description is not shown.
Willy Tarreaud63335a2010-02-26 12:56:52 +01005483
5484 Example :
5485 # internal monitoring access (unlimited)
5486 backend private_monitoring
5487 stats enable
5488 stats show-desc Master node for Europe, Asia, Africa
5489 stats uri /admin?stats
5490 stats refresh 5s
5491
5492 See also: "show-node", "stats enable", "stats uri" and "description" in
5493 global section.
5494
5495
5496stats show-legends
5497 Enable reporting additional informations on the statistics page :
5498 - cap: capabilities (proxy)
5499 - mode: one of tcp, http or health (proxy)
5500 - id: SNMP ID (proxy, socket, server)
5501 - IP (socket, server)
5502 - cookie (backend, server)
5503
5504 Though this statement alone is enough to enable statistics reporting, it is
5505 recommended to set all other settings in order to avoid relying on default
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04005506 unobvious parameters. Default behaviour is not to show this information.
Willy Tarreaud63335a2010-02-26 12:56:52 +01005507
5508 See also: "stats enable", "stats uri".
5509
5510
5511stats show-node [ <name> ]
5512 Enable reporting of a host name on the statistics page.
5513 May be used in sections : defaults | frontend | listen | backend
5514 yes | no | yes | yes
5515 Arguments:
5516 <name> is an optional name to be reported. If unspecified, the
5517 node name from global section is automatically used instead.
5518
5519 This statement is useful for users that offer shared services to their
5520 customers, where node or description might be different on a stats page
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04005521 provided for each customer. Default behaviour is not to show host name.
Willy Tarreaud63335a2010-02-26 12:56:52 +01005522
5523 Though this statement alone is enough to enable statistics reporting, it is
5524 recommended to set all other settings in order to avoid relying on default
5525 unobvious parameters.
5526
5527 Example:
5528 # internal monitoring access (unlimited)
5529 backend private_monitoring
5530 stats enable
5531 stats show-node Europe-1
5532 stats uri /admin?stats
5533 stats refresh 5s
5534
5535 See also: "show-desc", "stats enable", "stats uri", and "node" in global
5536 section.
5537
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005538
5539stats uri <prefix>
5540 Enable statistics and define the URI prefix to access them
5541 May be used in sections : defaults | frontend | listen | backend
5542 yes | no | yes | yes
5543 Arguments :
5544 <prefix> is the prefix of any URI which will be redirected to stats. This
5545 prefix may contain a question mark ('?') to indicate part of a
5546 query string.
5547
5548 The statistics URI is intercepted on the relayed traffic, so it appears as a
5549 page within the normal application. It is strongly advised to ensure that the
5550 selected URI will never appear in the application, otherwise it will never be
5551 possible to reach it in the application.
5552
5553 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005554 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005555 It is generally a good idea to include a question mark in the URI so that
5556 intermediate proxies refrain from caching the results. Also, since any string
5557 beginning with the prefix will be accepted as a stats request, the question
5558 mark helps ensuring that no valid URI will begin with the same words.
5559
5560 It is sometimes very convenient to use "/" as the URI prefix, and put that
5561 statement in a "listen" instance of its own. That makes it easy to dedicate
5562 an address or a port to statistics only.
5563
5564 Though this statement alone is enough to enable statistics reporting, it is
5565 recommended to set all other settings in order to avoid relying on default
5566 unobvious parameters.
5567
5568 Example :
5569 # public access (limited to this backend only)
5570 backend public_www
5571 server srv1 192.168.0.1:80
5572 stats enable
5573 stats hide-version
5574 stats scope .
5575 stats uri /admin?stats
5576 stats realm Haproxy\ Statistics
5577 stats auth admin1:AdMiN123
5578 stats auth admin2:AdMiN321
5579
5580 # internal monitoring access (unlimited)
5581 backend private_monitoring
5582 stats enable
5583 stats uri /admin?stats
5584 stats refresh 5s
5585
5586 See also : "stats auth", "stats enable", "stats realm"
5587
5588
Willy Tarreaud63335a2010-02-26 12:56:52 +01005589stick match <pattern> [table <table>] [{if | unless} <cond>]
5590 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005591 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +01005592 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005593
5594 Arguments :
5595 <pattern> is a pattern extraction rule as described in section 7.8. It
5596 describes what elements of the incoming request or connection
5597 will be analysed in the hope to find a matching entry in a
5598 stickiness table. This rule is mandatory.
5599
5600 <table> is an optional stickiness table name. If unspecified, the same
5601 backend's table is used. A stickiness table is declared using
5602 the "stick-table" statement.
5603
5604 <cond> is an optional matching condition. It makes it possible to match
5605 on a certain criterion only when other conditions are met (or
5606 not met). For instance, it could be used to match on a source IP
5607 address except when a request passes through a known proxy, in
5608 which case we'd match on a header containing that IP address.
5609
5610 Some protocols or applications require complex stickiness rules and cannot
5611 always simply rely on cookies nor hashing. The "stick match" statement
5612 describes a rule to extract the stickiness criterion from an incoming request
5613 or connection. See section 7 for a complete list of possible patterns and
5614 transformation rules.
5615
5616 The table has to be declared using the "stick-table" statement. It must be of
5617 a type compatible with the pattern. By default it is the one which is present
5618 in the same backend. It is possible to share a table with other backends by
5619 referencing it using the "table" keyword. If another table is referenced,
5620 the server's ID inside the backends are used. By default, all server IDs
5621 start at 1 in each backend, so the server ordering is enough. But in case of
5622 doubt, it is highly recommended to force server IDs using their "id" setting.
5623
5624 It is possible to restrict the conditions where a "stick match" statement
5625 will apply, using "if" or "unless" followed by a condition. See section 7 for
5626 ACL based conditions.
5627
5628 There is no limit on the number of "stick match" statements. The first that
5629 applies and matches will cause the request to be directed to the same server
5630 as was used for the request which created the entry. That way, multiple
5631 matches can be used as fallbacks.
5632
5633 The stick rules are checked after the persistence cookies, so they will not
5634 affect stickiness if a cookie has already been used to select a server. That
5635 way, it becomes very easy to insert cookies and match on IP addresses in
5636 order to maintain stickiness between HTTP and HTTPS.
5637
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005638 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5639 unless you know what you do : memory is not shared between the
5640 processes, which can result in random behaviours.
5641
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005642 Example :
5643 # forward SMTP users to the same server they just used for POP in the
5644 # last 30 minutes
5645 backend pop
5646 mode tcp
5647 balance roundrobin
5648 stick store-request src
5649 stick-table type ip size 200k expire 30m
5650 server s1 192.168.1.1:110
5651 server s2 192.168.1.1:110
5652
5653 backend smtp
5654 mode tcp
5655 balance roundrobin
5656 stick match src table pop
5657 server s1 192.168.1.1:25
5658 server s2 192.168.1.1:25
5659
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005660 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
5661 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005662
5663
5664stick on <pattern> [table <table>] [{if | unless} <condition>]
5665 Define a request pattern to associate a user to a server
5666 May be used in sections : defaults | frontend | listen | backend
5667 no | no | yes | yes
5668
5669 Note : This form is exactly equivalent to "stick match" followed by
5670 "stick store-request", all with the same arguments. Please refer
5671 to both keywords for details. It is only provided as a convenience
5672 for writing more maintainable configurations.
5673
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005674 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5675 unless you know what you do : memory is not shared between the
5676 processes, which can result in random behaviours.
5677
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005678 Examples :
5679 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +01005680 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005681
5682 # ...is strictly equivalent to this one :
5683 stick match src table pop if !localhost
5684 stick store-request src table pop if !localhost
5685
5686
5687 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
5688 # well as HTTP without cookie. Share the same table between both accesses.
5689 backend http
5690 mode http
5691 balance roundrobin
5692 stick on src table https
5693 cookie SRV insert indirect nocache
5694 server s1 192.168.1.1:80 cookie s1
5695 server s2 192.168.1.1:80 cookie s2
5696
5697 backend https
5698 mode tcp
5699 balance roundrobin
5700 stick-table type ip size 200k expire 30m
5701 stick on src
5702 server s1 192.168.1.1:443
5703 server s2 192.168.1.1:443
5704
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005705 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005706
5707
5708stick store-request <pattern> [table <table>] [{if | unless} <condition>]
5709 Define a request pattern used to create an entry in a stickiness table
5710 May be used in sections : defaults | frontend | listen | backend
5711 no | no | yes | yes
5712
5713 Arguments :
5714 <pattern> is a pattern extraction rule as described in section 7.8. It
5715 describes what elements of the incoming request or connection
5716 will be analysed, extracted and stored in the table once a
5717 server is selected.
5718
5719 <table> is an optional stickiness table name. If unspecified, the same
5720 backend's table is used. A stickiness table is declared using
5721 the "stick-table" statement.
5722
5723 <cond> is an optional storage condition. It makes it possible to store
5724 certain criteria only when some conditions are met (or not met).
5725 For instance, it could be used to store the source IP address
5726 except when the request passes through a known proxy, in which
5727 case we'd store a converted form of a header containing that IP
5728 address.
5729
5730 Some protocols or applications require complex stickiness rules and cannot
5731 always simply rely on cookies nor hashing. The "stick store-request" statement
5732 describes a rule to decide what to extract from the request and when to do
5733 it, in order to store it into a stickiness table for further requests to
5734 match it using the "stick match" statement. Obviously the extracted part must
5735 make sense and have a chance to be matched in a further request. Storing a
5736 client's IP address for instance often makes sense. Storing an ID found in a
5737 URL parameter also makes sense. Storing a source port will almost never make
5738 any sense because it will be randomly matched. See section 7 for a complete
5739 list of possible patterns and transformation rules.
5740
5741 The table has to be declared using the "stick-table" statement. It must be of
5742 a type compatible with the pattern. By default it is the one which is present
5743 in the same backend. It is possible to share a table with other backends by
5744 referencing it using the "table" keyword. If another table is referenced,
5745 the server's ID inside the backends are used. By default, all server IDs
5746 start at 1 in each backend, so the server ordering is enough. But in case of
5747 doubt, it is highly recommended to force server IDs using their "id" setting.
5748
5749 It is possible to restrict the conditions where a "stick store-request"
5750 statement will apply, using "if" or "unless" followed by a condition. This
5751 condition will be evaluated while parsing the request, so any criteria can be
5752 used. See section 7 for ACL based conditions.
5753
5754 There is no limit on the number of "stick store-request" statements, but
5755 there is a limit of 8 simultaneous stores per request or response. This
5756 makes it possible to store up to 8 criteria, all extracted from either the
5757 request or the response, regardless of the number of rules. Only the 8 first
5758 ones which match will be kept. Using this, it is possible to feed multiple
5759 tables at once in the hope to increase the chance to recognize a user on
5760 another protocol or access method.
5761
5762 The "store-request" rules are evaluated once the server connection has been
5763 established, so that the table will contain the real server that processed
5764 the request.
5765
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005766 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5767 unless you know what you do : memory is not shared between the
5768 processes, which can result in random behaviours.
5769
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005770 Example :
5771 # forward SMTP users to the same server they just used for POP in the
5772 # last 30 minutes
5773 backend pop
5774 mode tcp
5775 balance roundrobin
5776 stick store-request src
5777 stick-table type ip size 200k expire 30m
5778 server s1 192.168.1.1:110
5779 server s2 192.168.1.1:110
5780
5781 backend smtp
5782 mode tcp
5783 balance roundrobin
5784 stick match src table pop
5785 server s1 192.168.1.1:25
5786 server s2 192.168.1.1:25
5787
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005788 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
5789 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005790
5791
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005792stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +02005793 size <size> [expire <expire>] [nopurge] [peers <peersect>]
5794 [store <data_type>]*
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005795 Configure the stickiness table for the current backend
5796 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +02005797 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005798
5799 Arguments :
5800 ip a table declared with "type ip" will only store IPv4 addresses.
5801 This form is very compact (about 50 bytes per entry) and allows
5802 very fast entry lookup and stores with almost no overhead. This
5803 is mainly used to store client source IP addresses.
5804
David du Colombier9a6d3c92011-03-17 10:40:24 +01005805 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
5806 This form is very compact (about 60 bytes per entry) and allows
5807 very fast entry lookup and stores with almost no overhead. This
5808 is mainly used to store client source IP addresses.
5809
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005810 integer a table declared with "type integer" will store 32bit integers
5811 which can represent a client identifier found in a request for
5812 instance.
5813
5814 string a table declared with "type string" will store substrings of up
5815 to <len> characters. If the string provided by the pattern
5816 extractor is larger than <len>, it will be truncated before
5817 being stored. During matching, at most <len> characters will be
5818 compared between the string in the table and the extracted
5819 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005820 to 32 characters.
5821
5822 binary a table declared with "type binary" will store binary blocks
5823 of <len> bytes. If the block provided by the pattern
5824 extractor is larger than <len>, it will be truncated before
5825 being stored. If the block provided by the pattern extractor
5826 is shorter than <len>, it will be padded by 0. When not
5827 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005828
5829 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005830 "string" type table (See type "string" above). Or the number
5831 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005832 changing this parameter as memory usage will proportionally
5833 increase.
5834
5835 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +01005836 value directly impacts memory usage. Count approximately
5837 50 bytes per entry, plus the size of a string if any. The size
5838 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005839
5840 [nopurge] indicates that we refuse to purge older entries when the table
5841 is full. When not specified and the table is full when haproxy
5842 wants to store an entry in it, it will flush a few of the oldest
5843 entries in order to release some space for the new ones. This is
5844 most often the desired behaviour. In some specific cases, it
5845 be desirable to refuse new entries instead of purging the older
5846 ones. That may be the case when the amount of data to store is
5847 far above the hardware limits and we prefer not to offer access
5848 to new clients than to reject the ones already connected. When
5849 using this parameter, be sure to properly set the "expire"
5850 parameter (see below).
5851
Emeric Brunf099e792010-09-27 12:05:28 +02005852 <peersect> is the name of the peers section to use for replication. Entries
5853 which associate keys to server IDs are kept synchronized with
5854 the remote peers declared in this section. All entries are also
5855 automatically learned from the local peer (old process) during a
5856 soft restart.
5857
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005858 NOTE : peers can't be used in multi-process mode.
5859
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005860 <expire> defines the maximum duration of an entry in the table since it
5861 was last created, refreshed or matched. The expiration delay is
5862 defined using the standard time format, similarly as the various
5863 timeouts. The maximum duration is slightly above 24 days. See
5864 section 2.2 for more information. If this delay is not specified,
Cyril Bontédc4d9032012-04-08 21:57:39 +02005865 the session won't automatically expire, but older entries will
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005866 be removed once full. Be sure not to use the "nopurge" parameter
5867 if not expiration delay is specified.
5868
Willy Tarreau08d5f982010-06-06 13:34:54 +02005869 <data_type> is used to store additional information in the stick-table. This
5870 may be used by ACLs in order to control various criteria related
5871 to the activity of the client matching the stick-table. For each
5872 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +02005873 that the additional data can fit. Several data types may be
5874 stored with an entry. Multiple data types may be specified after
5875 the "store" keyword, as a comma-separated list. Alternatively,
5876 it is possible to repeat the "store" keyword followed by one or
5877 several data types. Except for the "server_id" type which is
5878 automatically detected and enabled, all data types must be
5879 explicitly declared to be stored. If an ACL references a data
5880 type which is not stored, the ACL will simply not match. Some
5881 data types require an argument which must be passed just after
5882 the type between parenthesis. See below for the supported data
5883 types and their arguments.
5884
5885 The data types that can be stored with an entry are the following :
5886 - server_id : this is an integer which holds the numeric ID of the server a
5887 request was assigned to. It is used by the "stick match", "stick store",
5888 and "stick on" rules. It is automatically enabled when referenced.
5889
5890 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
5891 integer which may be used for anything. Most of the time it will be used
5892 to put a special tag on some entries, for instance to note that a
5893 specific behaviour was detected and must be known for future matches.
5894
5895 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
5896 the absolute number of connections received from clients which matched
5897 this entry. It does not mean the connections were accepted, just that
5898 they were received.
5899
5900 - conn_cur : Current Connections. It is a positive 32-bit integer which
5901 stores the concurrent connection counts for the entry. It is incremented
5902 once an incoming connection matches the entry, and decremented once the
5903 connection leaves. That way it is possible to know at any time the exact
5904 number of concurrent connections for an entry.
5905
5906 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5907 integer parameter <period> which indicates in milliseconds the length
5908 of the period over which the average is measured. It reports the average
5909 incoming connection rate over that period, in connections per period. The
5910 result is an integer which can be matched using ACLs.
5911
5912 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
5913 the absolute number of sessions received from clients which matched this
5914 entry. A session is a connection that was accepted by the layer 4 rules.
5915
5916 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5917 integer parameter <period> which indicates in milliseconds the length
5918 of the period over which the average is measured. It reports the average
5919 incoming session rate over that period, in sessions per period. The
5920 result is an integer which can be matched using ACLs.
5921
5922 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
5923 counts the absolute number of HTTP requests received from clients which
5924 matched this entry. It does not matter whether they are valid requests or
5925 not. Note that this is different from sessions when keep-alive is used on
5926 the client side.
5927
5928 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5929 integer parameter <period> which indicates in milliseconds the length
5930 of the period over which the average is measured. It reports the average
5931 HTTP request rate over that period, in requests per period. The result is
5932 an integer which can be matched using ACLs. It does not matter whether
5933 they are valid requests or not. Note that this is different from sessions
5934 when keep-alive is used on the client side.
5935
5936 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
5937 counts the absolute number of HTTP requests errors induced by clients
5938 which matched this entry. Errors are counted on invalid and truncated
5939 requests, as well as on denied or tarpitted requests, and on failed
5940 authentications. If the server responds with 4xx, then the request is
5941 also counted as an error since it's an error triggered by the client
5942 (eg: vulnerability scan).
5943
5944 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5945 integer parameter <period> which indicates in milliseconds the length
5946 of the period over which the average is measured. It reports the average
5947 HTTP request error rate over that period, in requests per period (see
5948 http_err_cnt above for what is accounted as an error). The result is an
5949 integer which can be matched using ACLs.
5950
5951 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
5952 integer which counts the cumulated amount of bytes received from clients
5953 which matched this entry. Headers are included in the count. This may be
5954 used to limit abuse of upload features on photo or video servers.
5955
5956 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
5957 integer parameter <period> which indicates in milliseconds the length
5958 of the period over which the average is measured. It reports the average
5959 incoming bytes rate over that period, in bytes per period. It may be used
5960 to detect users which upload too much and too fast. Warning: with large
5961 uploads, it is possible that the amount of uploaded data will be counted
5962 once upon termination, thus causing spikes in the average transfer speed
5963 instead of having a smooth one. This may partially be smoothed with
5964 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
5965 recommended for better fairness.
5966
5967 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
5968 integer which counts the cumulated amount of bytes sent to clients which
5969 matched this entry. Headers are included in the count. This may be used
5970 to limit abuse of bots sucking the whole site.
5971
5972 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
5973 an integer parameter <period> which indicates in milliseconds the length
5974 of the period over which the average is measured. It reports the average
5975 outgoing bytes rate over that period, in bytes per period. It may be used
5976 to detect users which download too much and too fast. Warning: with large
5977 transfers, it is possible that the amount of transferred data will be
5978 counted once upon termination, thus causing spikes in the average
5979 transfer speed instead of having a smooth one. This may partially be
5980 smoothed with "option contstats" though this is not perfect yet. Use of
5981 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +02005982
Willy Tarreauc00cdc22010-06-06 16:48:26 +02005983 There is only one stick-table per proxy. At the moment of writing this doc,
5984 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005985 to be required, simply create a dummy backend with a stick-table in it and
5986 reference it.
5987
5988 It is important to understand that stickiness based on learning information
5989 has some limitations, including the fact that all learned associations are
5990 lost upon restart. In general it can be good as a complement but not always
5991 as an exclusive stickiness.
5992
Willy Tarreauc9705a12010-07-27 20:05:50 +02005993 Last, memory requirements may be important when storing many data types.
5994 Indeed, storing all indicators above at once in each entry requires 116 bytes
5995 per entry, or 116 MB for a 1-million entries table. This is definitely not
5996 something that can be ignored.
5997
5998 Example:
5999 # Keep track of counters of up to 1 million IP addresses over 5 minutes
6000 # and store a general purpose counter and the average connection rate
6001 # computed over a sliding window of 30 seconds.
6002 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
6003
6004 See also : "stick match", "stick on", "stick store-request", section 2.2
David du Colombiera13d1b92011-03-17 10:40:22 +01006005 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006006
6007
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006008stick store-response <pattern> [table <table>] [{if | unless} <condition>]
6009 Define a request pattern used to create an entry in a stickiness table
6010 May be used in sections : defaults | frontend | listen | backend
6011 no | no | yes | yes
6012
6013 Arguments :
6014 <pattern> is a pattern extraction rule as described in section 7.8. It
6015 describes what elements of the response or connection will
6016 be analysed, extracted and stored in the table once a
6017 server is selected.
6018
6019 <table> is an optional stickiness table name. If unspecified, the same
6020 backend's table is used. A stickiness table is declared using
6021 the "stick-table" statement.
6022
6023 <cond> is an optional storage condition. It makes it possible to store
6024 certain criteria only when some conditions are met (or not met).
6025 For instance, it could be used to store the SSL session ID only
6026 when the response is a SSL server hello.
6027
6028 Some protocols or applications require complex stickiness rules and cannot
6029 always simply rely on cookies nor hashing. The "stick store-response"
6030 statement describes a rule to decide what to extract from the response and
6031 when to do it, in order to store it into a stickiness table for further
6032 requests to match it using the "stick match" statement. Obviously the
6033 extracted part must make sense and have a chance to be matched in a further
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006034 request. Storing an ID found in a header of a response makes sense.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006035 See section 7 for a complete list of possible patterns and transformation
6036 rules.
6037
6038 The table has to be declared using the "stick-table" statement. It must be of
6039 a type compatible with the pattern. By default it is the one which is present
6040 in the same backend. It is possible to share a table with other backends by
6041 referencing it using the "table" keyword. If another table is referenced,
6042 the server's ID inside the backends are used. By default, all server IDs
6043 start at 1 in each backend, so the server ordering is enough. But in case of
6044 doubt, it is highly recommended to force server IDs using their "id" setting.
6045
6046 It is possible to restrict the conditions where a "stick store-response"
6047 statement will apply, using "if" or "unless" followed by a condition. This
6048 condition will be evaluated while parsing the response, so any criteria can
6049 be used. See section 7 for ACL based conditions.
6050
6051 There is no limit on the number of "stick store-response" statements, but
6052 there is a limit of 8 simultaneous stores per request or response. This
6053 makes it possible to store up to 8 criteria, all extracted from either the
6054 request or the response, regardless of the number of rules. Only the 8 first
6055 ones which match will be kept. Using this, it is possible to feed multiple
6056 tables at once in the hope to increase the chance to recognize a user on
6057 another protocol or access method.
6058
6059 The table will contain the real server that processed the request.
6060
6061 Example :
6062 # Learn SSL session ID from both request and response and create affinity.
6063 backend https
6064 mode tcp
6065 balance roundrobin
Cyril Bontédc4d9032012-04-08 21:57:39 +02006066 # maximum SSL session ID length is 32 bytes.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006067 stick-table type binary len 32 size 30k expire 30m
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006068
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006069 acl clienthello req_ssl_hello_type 1
6070 acl serverhello rep_ssl_hello_type 2
6071
6072 # use tcp content accepts to detects ssl client and server hello.
6073 tcp-request inspect-delay 5s
6074 tcp-request content accept if clienthello
6075
6076 # no timeout on response inspect delay by default.
6077 tcp-response content accept if serverhello
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006078
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006079 # SSL session ID (SSLID) may be present on a client or server hello.
6080 # Its length is coded on 1 byte at offset 43 and its value starts
6081 # at offset 44.
6082
6083 # Match and learn on request if client hello.
6084 stick on payload_lv(43,1) if clienthello
6085
6086 # Learn on response if server hello.
6087 stick store-response payload_lv(43,1) if serverhello
Cyril Bontédc4d9032012-04-08 21:57:39 +02006088
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006089 server s1 192.168.1.1:443
6090 server s2 192.168.1.1:443
6091
6092 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
6093 extraction.
6094
6095
Willy Tarreaue9656522010-08-17 15:40:09 +02006096tcp-request connection <action> [{if | unless} <condition>]
6097 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +02006098 May be used in sections : defaults | frontend | listen | backend
6099 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +02006100 Arguments :
6101 <action> defines the action to perform if the condition applies. Valid
6102 actions include : "accept", "reject", "track-sc1", "track-sc2".
6103 See below for more details.
Willy Tarreau1a687942010-05-23 22:40:30 +02006104
Willy Tarreaue9656522010-08-17 15:40:09 +02006105 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006106
6107 Immediately after acceptance of a new incoming connection, it is possible to
6108 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +02006109 or dropped or have its counters tracked. Those conditions cannot make use of
6110 any data contents because the connection has not been read from yet, and the
6111 buffers are not yet allocated. This is used to selectively and very quickly
6112 accept or drop connections from various sources with a very low overhead. If
6113 some contents need to be inspected in order to take the decision, the
6114 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006115
Willy Tarreaue9656522010-08-17 15:40:09 +02006116 The "tcp-request connection" rules are evaluated in their exact declaration
6117 order. If no rule matches or if there is no rule, the default action is to
6118 accept the incoming connection. There is no specific limit to the number of
6119 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006120
Willy Tarreaue9656522010-08-17 15:40:09 +02006121 Three types of actions are supported :
6122 - accept :
6123 accepts the connection if the condition is true (when used with "if")
6124 or false (when used with "unless"). The first such rule executed ends
6125 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006126
Willy Tarreaue9656522010-08-17 15:40:09 +02006127 - reject :
6128 rejects the connection if the condition is true (when used with "if")
6129 or false (when used with "unless"). The first such rule executed ends
6130 the rules evaluation. Rejected connections do not even become a
6131 session, which is why they are accounted separately for in the stats,
6132 as "denied connections". They are not considered for the session
6133 rate-limit and are not logged either. The reason is that these rules
6134 should only be used to filter extremely high connection rates such as
6135 the ones encountered during a massive DDoS attack. Under these extreme
6136 conditions, the simple action of logging each event would make the
6137 system collapse and would considerably lower the filtering capacity. If
6138 logging is absolutely desired, then "tcp-request content" rules should
6139 be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006140
Willy Tarreaue9656522010-08-17 15:40:09 +02006141 - { track-sc1 | track-sc2 } <key> [table <table>] :
6142 enables tracking of sticky counters from current connection. These
6143 rules do not stop evaluation and do not change default action. Two sets
6144 of counters may be simultaneously tracked by the same connection. The
6145 first "track-sc1" rule executed enables tracking of the counters of the
6146 specified table as the first set. The first "track-sc2" rule executed
6147 enables tracking of the counters of the specified table as the second
6148 set. It is a recommended practice to use the first set of counters for
6149 the per-frontend counters and the second set for the per-backend ones.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006150
Willy Tarreaue9656522010-08-17 15:40:09 +02006151 These actions take one or two arguments :
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01006152 <key> is mandatory, and is a pattern extraction rule as described
6153 in section 7.8. It describes what elements of the incoming
6154 request or connection will be analysed, extracted, combined,
6155 and used to select which table entry to update the counters.
6156 Note that "tcp-request connection" cannot use content-based
6157 fetches.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006158
Willy Tarreaue9656522010-08-17 15:40:09 +02006159 <table> is an optional table to be used instead of the default one,
6160 which is the stick-table declared in the current proxy. All
6161 the counters for the matches and updates for the key will
6162 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006163
Willy Tarreaue9656522010-08-17 15:40:09 +02006164 Once a "track-sc*" rule is executed, the key is looked up in the table
6165 and if it is not found, an entry is allocated for it. Then a pointer to
6166 that entry is kept during all the session's life, and this entry's
6167 counters are updated as often as possible, every time the session's
6168 counters are updated, and also systematically when the session ends.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01006169 Counters are only updated for events that happen after the tracking has
6170 been started. For example, connection counters will not be updated when
6171 tracking layer 7 information, since the connection event happens before
6172 layer7 information is extracted.
6173
Willy Tarreaue9656522010-08-17 15:40:09 +02006174 If the entry tracks concurrent connection counters, one connection is
6175 counted for as long as the entry is tracked, and the entry will not
6176 expire during that time. Tracking counters also provides a performance
6177 advantage over just checking the keys, because only one table lookup is
6178 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006179
Willy Tarreaue9656522010-08-17 15:40:09 +02006180 Note that the "if/unless" condition is optional. If no condition is set on
6181 the action, it is simply performed unconditionally. That can be useful for
6182 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006183
Willy Tarreaue9656522010-08-17 15:40:09 +02006184 Example: accept all connections from white-listed hosts, reject too fast
6185 connection without counting them, and track accepted connections.
6186 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006187
Willy Tarreaue9656522010-08-17 15:40:09 +02006188 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006189 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaue9656522010-08-17 15:40:09 +02006190 tcp-request connection track-sc1 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006191
Willy Tarreaue9656522010-08-17 15:40:09 +02006192 Example: accept all connections from white-listed hosts, count all other
6193 connections and reject too fast ones. This results in abusive ones
6194 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006195
Willy Tarreaue9656522010-08-17 15:40:09 +02006196 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
6197 tcp-request connection track-sc1 src
6198 tcp-request connection reject if { sc1_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006199
6200 See section 7 about ACL usage.
6201
Willy Tarreaue9656522010-08-17 15:40:09 +02006202 See also : "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006203
6204
Willy Tarreaue9656522010-08-17 15:40:09 +02006205tcp-request content <action> [{if | unless} <condition>]
6206 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +02006207 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02006208 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +02006209 Arguments :
6210 <action> defines the action to perform if the condition applies. Valid
6211 actions include : "accept", "reject", "track-sc1", "track-sc2".
6212 See "tcp-request connection" above for their signification.
Willy Tarreau62644772008-07-16 18:36:06 +02006213
Willy Tarreaue9656522010-08-17 15:40:09 +02006214 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +02006215
Willy Tarreaue9656522010-08-17 15:40:09 +02006216 A request's contents can be analysed at an early stage of request processing
6217 called "TCP content inspection". During this stage, ACL-based rules are
6218 evaluated every time the request contents are updated, until either an
6219 "accept" or a "reject" rule matches, or the TCP request inspection delay
6220 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +02006221
Willy Tarreaue9656522010-08-17 15:40:09 +02006222 The first difference between these rules and "tcp-request connection" rules
6223 is that "tcp-request content" rules can make use of contents to take a
6224 decision. Most often, these decisions will consider a protocol recognition or
6225 validity. The second difference is that content-based rules can be used in
6226 both frontends and backends. In frontends, they will be evaluated upon new
6227 connections. In backends, they will be evaluated once a session is assigned
6228 a backend. This means that a single frontend connection may be evaluated
6229 several times by one or multiple backends when a session gets reassigned
6230 (for instance after a client-side HTTP keep-alive request).
Willy Tarreau62644772008-07-16 18:36:06 +02006231
Willy Tarreaue9656522010-08-17 15:40:09 +02006232 Content-based rules are evaluated in their exact declaration order. If no
6233 rule matches or if there is no rule, the default action is to accept the
6234 contents. There is no specific limit to the number of rules which may be
6235 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +02006236
Willy Tarreaue9656522010-08-17 15:40:09 +02006237 Three types of actions are supported :
6238 - accept :
6239 - reject :
6240 - { track-sc1 | track-sc2 } <key> [table <table>]
Willy Tarreau62644772008-07-16 18:36:06 +02006241
Willy Tarreaue9656522010-08-17 15:40:09 +02006242 They have the same meaning as their counter-parts in "tcp-request connection"
6243 so please refer to that section for a complete description.
Willy Tarreau62644772008-07-16 18:36:06 +02006244
Willy Tarreaue9656522010-08-17 15:40:09 +02006245 Also, it is worth noting that if sticky counters are tracked from a rule
6246 defined in a backend, this tracking will automatically end when the session
6247 releases the backend. That allows per-backend counter tracking even in case
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01006248 of HTTP keep-alive requests when the backend changes. This makes a subtle
6249 difference because tracking rules in "frontend" and "listen" section last for
6250 all the session, as opposed to the backend rules. The difference appears when
6251 some layer 7 information is tracked. While there is nothing mandatory about
6252 it, it is recommended to use the track-sc1 pointer to track per-frontend
6253 counters and track-sc2 to track per-backend counters.
Willy Tarreau62644772008-07-16 18:36:06 +02006254
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006255 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +02006256 the action, it is simply performed unconditionally. That can be useful for
6257 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +02006258
Willy Tarreaue9656522010-08-17 15:40:09 +02006259 It is perfectly possible to match layer 7 contents with "tcp-request content"
Willy Tarreauc0239e02012-04-16 14:42:55 +02006260 rules, since HTTP-specific ACL matches are able to preliminarily parse the
6261 contents of a buffer before extracting the required data. If the buffered
6262 contents do not parse as a valid HTTP message, then the ACL does not match.
6263 The parser which is involved there is exactly the same as for all other HTTP
6264 processing, so there is no risk of parsing something differently.
Willy Tarreau62644772008-07-16 18:36:06 +02006265
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01006266 Tracking layer7 information is also possible provided that the information
6267 are present when the rule is processed. The current solution for making the
6268 rule engine wait for such information is to set an inspect delay and to
6269 condition its execution with an ACL relying on such information.
6270
Willy Tarreau62644772008-07-16 18:36:06 +02006271 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +02006272 # Accept HTTP requests containing a Host header saying "example.com"
6273 # and reject everything else.
6274 acl is_host_com hdr(Host) -i example.com
6275 tcp-request inspect-delay 30s
Willy Tarreauc0239e02012-04-16 14:42:55 +02006276 tcp-request content accept if is_host_com
Willy Tarreaue9656522010-08-17 15:40:09 +02006277 tcp-request content reject
6278
6279 Example:
Willy Tarreau62644772008-07-16 18:36:06 +02006280 # reject SMTP connection if client speaks first
6281 tcp-request inspect-delay 30s
6282 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006283 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +02006284
6285 # Forward HTTPS connection only if client speaks
6286 tcp-request inspect-delay 30s
6287 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006288 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +02006289 tcp-request content reject
6290
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01006291 Example:
6292 # Track the last IP from X-Forwarded-For
6293 tcp-request inspect-delay 10s
6294 tcp-request content track-sc1 hdr(x-forwarded-for,-1) if HTTP
6295
6296 Example:
6297 # track request counts per "base" (concatenation of Host+URL)
6298 tcp-request inspect-delay 10s
6299 tcp-request content track-sc1 base table req-rate if HTTP
6300
Willy Tarreaue9656522010-08-17 15:40:09 +02006301 Example: track per-frontend and per-backend counters, block abusers at the
6302 frontend when the backend detects abuse.
6303
6304 frontend http
6305 # Use General Purpose Couter 0 in SC1 as a global abuse counter
6306 # protecting all our sites
6307 stick-table type ip size 1m expire 5m store gpc0
6308 tcp-request connection track-sc1 src
6309 tcp-request connection reject if { sc1_get_gpc0 gt 0 }
6310 ...
6311 use_backend http_dynamic if { path_end .php }
6312
6313 backend http_dynamic
6314 # if a source makes too fast requests to this dynamic site (tracked
6315 # by SC2), block it globally in the frontend.
6316 stick-table type ip size 1m expire 5m store http_req_rate(10s)
6317 acl click_too_fast sc2_http_req_rate gt 10
6318 acl mark_as_abuser sc1_inc_gpc0
6319 tcp-request content track-sc2 src
6320 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +02006321
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006322 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02006323
Willy Tarreaue9656522010-08-17 15:40:09 +02006324 See also : "tcp-request connection", "tcp-request inspect-delay"
Willy Tarreau62644772008-07-16 18:36:06 +02006325
6326
6327tcp-request inspect-delay <timeout>
6328 Set the maximum allowed time to wait for data during content inspection
6329 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02006330 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +02006331 Arguments :
6332 <timeout> is the timeout value specified in milliseconds by default, but
6333 can be in any other unit if the number is suffixed by the unit,
6334 as explained at the top of this document.
6335
6336 People using haproxy primarily as a TCP relay are often worried about the
6337 risk of passing any type of protocol to a server without any analysis. In
6338 order to be able to analyze the request contents, we must first withhold
6339 the data then analyze them. This statement simply enables withholding of
6340 data for at most the specified amount of time.
6341
Willy Tarreaufb356202010-08-03 14:02:05 +02006342 TCP content inspection applies very early when a connection reaches a
6343 frontend, then very early when the connection is forwarded to a backend. This
6344 means that a connection may experience a first delay in the frontend and a
6345 second delay in the backend if both have tcp-request rules.
6346
Willy Tarreau62644772008-07-16 18:36:06 +02006347 Note that when performing content inspection, haproxy will evaluate the whole
6348 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006349 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +02006350 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +01006351 contents are definitive. If no delay is set, haproxy will not wait at all
6352 and will immediately apply a verdict based on the available information.
6353 Obviously this is unlikely to be very useful and might even be racy, so such
6354 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +02006355
6356 As soon as a rule matches, the request is released and continues as usual. If
6357 the timeout is reached and no rule matches, the default policy will be to let
6358 it pass through unaffected.
6359
6360 For most protocols, it is enough to set it to a few seconds, as most clients
6361 send the full request immediately upon connection. Add 3 or more seconds to
6362 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +01006363 to use large values, for instance to ensure that the client never talks
Willy Tarreau62644772008-07-16 18:36:06 +02006364 before the server (eg: SMTP), or to wait for a client to talk before passing
6365 data to the server (eg: SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +02006366 least the inspection delay, otherwise it will expire first. If the client
6367 closes the connection or if the buffer is full, the delay immediately expires
6368 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +02006369
Willy Tarreau55165fe2009-05-10 12:02:55 +02006370 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +02006371 "timeout client".
6372
6373
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006374tcp-response content <action> [{if | unless} <condition>]
6375 Perform an action on a session response depending on a layer 4-7 condition
6376 May be used in sections : defaults | frontend | listen | backend
6377 no | no | yes | yes
6378 Arguments :
6379 <action> defines the action to perform if the condition applies. Valid
6380 actions include : "accept", "reject".
6381 See "tcp-request connection" above for their signification.
6382
6383 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
6384
6385 Response contents can be analysed at an early stage of response processing
6386 called "TCP content inspection". During this stage, ACL-based rules are
6387 evaluated every time the response contents are updated, until either an
6388 "accept" or a "reject" rule matches, or a TCP response inspection delay is
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006389 set and expires with no matching rule.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006390
6391 Most often, these decisions will consider a protocol recognition or validity.
6392
6393 Content-based rules are evaluated in their exact declaration order. If no
6394 rule matches or if there is no rule, the default action is to accept the
6395 contents. There is no specific limit to the number of rules which may be
6396 inserted.
6397
6398 Two types of actions are supported :
6399 - accept :
6400 accepts the response if the condition is true (when used with "if")
6401 or false (when used with "unless"). The first such rule executed ends
6402 the rules evaluation.
6403
6404 - reject :
6405 rejects the response if the condition is true (when used with "if")
6406 or false (when used with "unless"). The first such rule executed ends
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006407 the rules evaluation. Rejected session are immediately closed.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006408
6409 Note that the "if/unless" condition is optional. If no condition is set on
6410 the action, it is simply performed unconditionally. That can be useful for
6411 for changing the default action to a reject.
6412
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006413 It is perfectly possible to match layer 7 contents with "tcp-response
6414 content" rules, but then it is important to ensure that a full response has
6415 been buffered, otherwise no contents will match. In order to achieve this,
6416 the best solution involves detecting the HTTP protocol during the inspection
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006417 period.
6418
6419 See section 7 about ACL usage.
6420
6421 See also : "tcp-request content", "tcp-response inspect-delay"
6422
6423
6424tcp-response inspect-delay <timeout>
6425 Set the maximum allowed time to wait for a response during content inspection
6426 May be used in sections : defaults | frontend | listen | backend
6427 no | no | yes | yes
6428 Arguments :
6429 <timeout> is the timeout value specified in milliseconds by default, but
6430 can be in any other unit if the number is suffixed by the unit,
6431 as explained at the top of this document.
6432
6433 See also : "tcp-response content", "tcp-request inspect-delay".
6434
6435
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006436timeout check <timeout>
6437 Set additional check timeout, but only after a connection has been already
6438 established.
6439
6440 May be used in sections: defaults | frontend | listen | backend
6441 yes | no | yes | yes
6442 Arguments:
6443 <timeout> is the timeout value specified in milliseconds by default, but
6444 can be in any other unit if the number is suffixed by the unit,
6445 as explained at the top of this document.
6446
6447 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
6448 for check and "timeout check" as an additional read timeout. The "min" is
6449 used so that people running with *very* long "timeout connect" (eg. those
6450 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +01006451 (Please also note that there is no valid reason to have such long connect
6452 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
6453 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006454
6455 If "timeout check" is not set haproxy uses "inter" for complete check
6456 timeout (connect + read) exactly like all <1.3.15 version.
6457
6458 In most cases check request is much simpler and faster to handle than normal
6459 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +01006460 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006461
6462 This parameter is specific to backends, but can be specified once for all in
6463 "defaults" sections. This is in fact one of the easiest solutions not to
6464 forget about it.
6465
Willy Tarreau41a340d2008-01-22 12:25:31 +01006466 See also: "timeout connect", "timeout queue", "timeout server",
6467 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006468
6469
Willy Tarreau0ba27502007-12-24 16:55:16 +01006470timeout client <timeout>
6471timeout clitimeout <timeout> (deprecated)
6472 Set the maximum inactivity time on the client side.
6473 May be used in sections : defaults | frontend | listen | backend
6474 yes | yes | yes | no
6475 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006476 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01006477 can be in any other unit if the number is suffixed by the unit,
6478 as explained at the top of this document.
6479
6480 The inactivity timeout applies when the client is expected to acknowledge or
6481 send data. In HTTP mode, this timeout is particularly important to consider
6482 during the first phase, when the client sends the request, and during the
6483 response while it is reading data sent by the server. The value is specified
6484 in milliseconds by default, but can be in any other unit if the number is
6485 suffixed by the unit, as specified at the top of this document. In TCP mode
6486 (and to a lesser extent, in HTTP mode), it is highly recommended that the
6487 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006488 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01006489 losses by specifying timeouts that are slightly above multiples of 3 seconds
Willy Tarreauce887fd2012-05-12 12:50:00 +02006490 (eg: 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
6491 sessions (eg: WebSocket and HTTP), it's worth considering "timeout tunnel",
6492 which overrides "timeout client" and "timeout server" for tunnels.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006493
6494 This parameter is specific to frontends, but can be specified once for all in
6495 "defaults" sections. This is in fact one of the easiest solutions not to
6496 forget about it. An unspecified timeout results in an infinite timeout, which
6497 is not recommended. Such a usage is accepted and works but reports a warning
6498 during startup because it may results in accumulation of expired sessions in
6499 the system if the system's timeouts are not configured either.
6500
6501 This parameter replaces the old, deprecated "clitimeout". It is recommended
6502 to use it to write new configurations. The form "timeout clitimeout" is
6503 provided only by backwards compatibility but its use is strongly discouraged.
6504
Willy Tarreauce887fd2012-05-12 12:50:00 +02006505 See also : "clitimeout", "timeout server", "timeout tunnel".
Willy Tarreau0ba27502007-12-24 16:55:16 +01006506
6507
6508timeout connect <timeout>
6509timeout contimeout <timeout> (deprecated)
6510 Set the maximum time to wait for a connection attempt to a server to succeed.
6511 May be used in sections : defaults | frontend | listen | backend
6512 yes | no | yes | yes
6513 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006514 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01006515 can be in any other unit if the number is suffixed by the unit,
6516 as explained at the top of this document.
6517
6518 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006519 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01006520 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01006521 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006522 connect timeout also presets both queue and tarpit timeouts to the same value
6523 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006524
6525 This parameter is specific to backends, but can be specified once for all in
6526 "defaults" sections. This is in fact one of the easiest solutions not to
6527 forget about it. An unspecified timeout results in an infinite timeout, which
6528 is not recommended. Such a usage is accepted and works but reports a warning
6529 during startup because it may results in accumulation of failed sessions in
6530 the system if the system's timeouts are not configured either.
6531
6532 This parameter replaces the old, deprecated "contimeout". It is recommended
6533 to use it to write new configurations. The form "timeout contimeout" is
6534 provided only by backwards compatibility but its use is strongly discouraged.
6535
Willy Tarreau41a340d2008-01-22 12:25:31 +01006536 See also: "timeout check", "timeout queue", "timeout server", "contimeout",
6537 "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +01006538
6539
Willy Tarreaub16a5742010-01-10 14:46:16 +01006540timeout http-keep-alive <timeout>
6541 Set the maximum allowed time to wait for a new HTTP request to appear
6542 May be used in sections : defaults | frontend | listen | backend
6543 yes | yes | yes | yes
6544 Arguments :
6545 <timeout> is the timeout value specified in milliseconds by default, but
6546 can be in any other unit if the number is suffixed by the unit,
6547 as explained at the top of this document.
6548
6549 By default, the time to wait for a new request in case of keep-alive is set
6550 by "timeout http-request". However this is not always convenient because some
6551 people want very short keep-alive timeouts in order to release connections
6552 faster, and others prefer to have larger ones but still have short timeouts
6553 once the request has started to present itself.
6554
6555 The "http-keep-alive" timeout covers these needs. It will define how long to
6556 wait for a new HTTP request to start coming after a response was sent. Once
6557 the first byte of request has been seen, the "http-request" timeout is used
6558 to wait for the complete request to come. Note that empty lines prior to a
6559 new request do not refresh the timeout and are not counted as a new request.
6560
6561 There is also another difference between the two timeouts : when a connection
6562 expires during timeout http-keep-alive, no error is returned, the connection
6563 just closes. If the connection expires in "http-request" while waiting for a
6564 connection to complete, a HTTP 408 error is returned.
6565
6566 In general it is optimal to set this value to a few tens to hundreds of
6567 milliseconds, to allow users to fetch all objects of a page at once but
6568 without waiting for further clicks. Also, if set to a very small value (eg:
6569 1 millisecond) it will probably only accept pipelined requests but not the
6570 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +02006571 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +01006572
6573 If this parameter is not set, the "http-request" timeout applies, and if both
6574 are not set, "timeout client" still applies at the lower level. It should be
6575 set in the frontend to take effect, unless the frontend is in TCP mode, in
6576 which case the HTTP backend's timeout will be used.
6577
6578 See also : "timeout http-request", "timeout client".
6579
6580
Willy Tarreau036fae02008-01-06 13:24:40 +01006581timeout http-request <timeout>
6582 Set the maximum allowed time to wait for a complete HTTP request
6583 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +02006584 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +01006585 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006586 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +01006587 can be in any other unit if the number is suffixed by the unit,
6588 as explained at the top of this document.
6589
6590 In order to offer DoS protection, it may be required to lower the maximum
6591 accepted time to receive a complete HTTP request without affecting the client
6592 timeout. This helps protecting against established connections on which
6593 nothing is sent. The client timeout cannot offer a good protection against
6594 this abuse because it is an inactivity timeout, which means that if the
6595 attacker sends one character every now and then, the timeout will not
6596 trigger. With the HTTP request timeout, no matter what speed the client
6597 types, the request will be aborted if it does not complete in time.
6598
6599 Note that this timeout only applies to the header part of the request, and
6600 not to any data. As soon as the empty line is received, this timeout is not
Willy Tarreaub16a5742010-01-10 14:46:16 +01006601 used anymore. It is used again on keep-alive connections to wait for a second
6602 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +01006603
6604 Generally it is enough to set it to a few seconds, as most clients send the
6605 full request immediately upon connection. Add 3 or more seconds to cover TCP
6606 retransmits but that's all. Setting it to very low values (eg: 50 ms) will
6607 generally work on local networks as long as there are no packet losses. This
6608 will prevent people from sending bare HTTP requests using telnet.
6609
6610 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +02006611 chunk of the incoming request. It should be set in the frontend to take
6612 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
6613 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +01006614
Willy Tarreaub16a5742010-01-10 14:46:16 +01006615 See also : "timeout http-keep-alive", "timeout client".
Willy Tarreau036fae02008-01-06 13:24:40 +01006616
Willy Tarreau844e3c52008-01-11 16:28:18 +01006617
6618timeout queue <timeout>
6619 Set the maximum time to wait in the queue for a connection slot to be free
6620 May be used in sections : defaults | frontend | listen | backend
6621 yes | no | yes | yes
6622 Arguments :
6623 <timeout> is the timeout value specified in milliseconds by default, but
6624 can be in any other unit if the number is suffixed by the unit,
6625 as explained at the top of this document.
6626
6627 When a server's maxconn is reached, connections are left pending in a queue
6628 which may be server-specific or global to the backend. In order not to wait
6629 indefinitely, a timeout is applied to requests pending in the queue. If the
6630 timeout is reached, it is considered that the request will almost never be
6631 served, so it is dropped and a 503 error is returned to the client.
6632
6633 The "timeout queue" statement allows to fix the maximum time for a request to
6634 be left pending in a queue. If unspecified, the same value as the backend's
6635 connection timeout ("timeout connect") is used, for backwards compatibility
6636 with older versions with no "timeout queue" parameter.
6637
6638 See also : "timeout connect", "contimeout".
6639
6640
6641timeout server <timeout>
6642timeout srvtimeout <timeout> (deprecated)
6643 Set the maximum inactivity time on the server side.
6644 May be used in sections : defaults | frontend | listen | backend
6645 yes | no | yes | yes
6646 Arguments :
6647 <timeout> is the timeout value specified in milliseconds by default, but
6648 can be in any other unit if the number is suffixed by the unit,
6649 as explained at the top of this document.
6650
6651 The inactivity timeout applies when the server is expected to acknowledge or
6652 send data. In HTTP mode, this timeout is particularly important to consider
6653 during the first phase of the server's response, when it has to send the
6654 headers, as it directly represents the server's processing time for the
6655 request. To find out what value to put there, it's often good to start with
6656 what would be considered as unacceptable response times, then check the logs
6657 to observe the response time distribution, and adjust the value accordingly.
6658
6659 The value is specified in milliseconds by default, but can be in any other
6660 unit if the number is suffixed by the unit, as specified at the top of this
6661 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
6662 recommended that the client timeout remains equal to the server timeout in
6663 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006664 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01006665 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreauce887fd2012-05-12 12:50:00 +02006666 seconds (eg: 4 or 5 seconds minimum). If some long-lived sessions are mixed
6667 with short-lived sessions (eg: WebSocket and HTTP), it's worth considering
6668 "timeout tunnel", which overrides "timeout client" and "timeout server" for
6669 tunnels.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006670
6671 This parameter is specific to backends, but can be specified once for all in
6672 "defaults" sections. This is in fact one of the easiest solutions not to
6673 forget about it. An unspecified timeout results in an infinite timeout, which
6674 is not recommended. Such a usage is accepted and works but reports a warning
6675 during startup because it may results in accumulation of expired sessions in
6676 the system if the system's timeouts are not configured either.
6677
6678 This parameter replaces the old, deprecated "srvtimeout". It is recommended
6679 to use it to write new configurations. The form "timeout srvtimeout" is
6680 provided only by backwards compatibility but its use is strongly discouraged.
6681
Willy Tarreauce887fd2012-05-12 12:50:00 +02006682 See also : "srvtimeout", "timeout client" and "timeout tunnel".
Willy Tarreau844e3c52008-01-11 16:28:18 +01006683
6684
6685timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +01006686 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +01006687 May be used in sections : defaults | frontend | listen | backend
6688 yes | yes | yes | yes
6689 Arguments :
6690 <timeout> is the tarpit duration specified in milliseconds by default, but
6691 can be in any other unit if the number is suffixed by the unit,
6692 as explained at the top of this document.
6693
6694 When a connection is tarpitted using "reqtarpit", it is maintained open with
6695 no activity for a certain amount of time, then closed. "timeout tarpit"
6696 defines how long it will be maintained open.
6697
6698 The value is specified in milliseconds by default, but can be in any other
6699 unit if the number is suffixed by the unit, as specified at the top of this
6700 document. If unspecified, the same value as the backend's connection timeout
6701 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +01006702 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006703
6704 See also : "timeout connect", "contimeout".
6705
6706
Willy Tarreauce887fd2012-05-12 12:50:00 +02006707timeout tunnel <timeout>
6708 Set the maximum inactivity time on the client and server side for tunnels.
6709 May be used in sections : defaults | frontend | listen | backend
6710 yes | no | yes | yes
6711 Arguments :
6712 <timeout> is the timeout value specified in milliseconds by default, but
6713 can be in any other unit if the number is suffixed by the unit,
6714 as explained at the top of this document.
6715
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006716 The tunnel timeout applies when a bidirectional connection is established
Willy Tarreauce887fd2012-05-12 12:50:00 +02006717 between a client and a server, and the connection remains inactive in both
6718 directions. This timeout supersedes both the client and server timeouts once
6719 the connection becomes a tunnel. In TCP, this timeout is used as soon as no
6720 analyser remains attached to either connection (eg: tcp content rules are
6721 accepted). In HTTP, this timeout is used when a connection is upgraded (eg:
6722 when switching to the WebSocket protocol, or forwarding a CONNECT request
6723 to a proxy), or after the first response when no keepalive/close option is
6724 specified.
6725
6726 The value is specified in milliseconds by default, but can be in any other
6727 unit if the number is suffixed by the unit, as specified at the top of this
6728 document. Whatever the expected normal idle time, it is a good practice to
6729 cover at least one or several TCP packet losses by specifying timeouts that
6730 are slightly above multiples of 3 seconds (eg: 4 or 5 seconds minimum).
6731
6732 This parameter is specific to backends, but can be specified once for all in
6733 "defaults" sections. This is in fact one of the easiest solutions not to
6734 forget about it.
6735
6736 Example :
6737 defaults http
6738 option http-server-close
6739 timeout connect 5s
6740 timeout client 30s
6741 timeout client 30s
6742 timeout server 30s
6743 timeout tunnel 1h # timeout to use with WebSocket and CONNECT
6744
6745 See also : "timeout client", "timeout server".
6746
6747
Willy Tarreau844e3c52008-01-11 16:28:18 +01006748transparent (deprecated)
6749 Enable client-side transparent proxying
6750 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01006751 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01006752 Arguments : none
6753
6754 This keyword was introduced in order to provide layer 7 persistence to layer
6755 3 load balancers. The idea is to use the OS's ability to redirect an incoming
6756 connection for a remote address to a local process (here HAProxy), and let
6757 this process know what address was initially requested. When this option is
6758 used, sessions without cookies will be forwarded to the original destination
6759 IP address of the incoming request (which should match that of another
6760 equipment), while requests with cookies will still be forwarded to the
6761 appropriate server.
6762
6763 The "transparent" keyword is deprecated, use "option transparent" instead.
6764
6765 Note that contrary to a common belief, this option does NOT make HAProxy
6766 present the client's IP to the server when establishing the connection.
6767
Willy Tarreau844e3c52008-01-11 16:28:18 +01006768 See also: "option transparent"
6769
William Lallemanda73203e2012-03-12 12:48:57 +01006770unique-id-format <string>
6771 Generate a unique ID for each request.
6772 May be used in sections : defaults | frontend | listen | backend
6773 yes | yes | yes | no
6774 Arguments :
6775 <string> is a log-format string.
6776
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006777 This keyword creates a ID for each request using the custom log format. A
6778 unique ID is useful to trace a request passing through many components of
6779 a complex infrastructure. The newly created ID may also be logged using the
6780 %ID tag the log-format string.
William Lallemanda73203e2012-03-12 12:48:57 +01006781
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006782 The format should be composed from elements that are guaranteed to be
6783 unique when combined together. For instance, if multiple haproxy instances
6784 are involved, it might be important to include the node name. It is often
6785 needed to log the incoming connection's source and destination addresses
6786 and ports. Note that since multiple requests may be performed over the same
6787 connection, including a request counter may help differentiate them.
6788 Similarly, a timestamp may protect against a rollover of the counter.
6789 Logging the process ID will avoid collisions after a service restart.
William Lallemanda73203e2012-03-12 12:48:57 +01006790
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006791 It is recommended to use hexadecimal notation for many fields since it
6792 makes them more compact and saves space in logs.
William Lallemanda73203e2012-03-12 12:48:57 +01006793
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006794 Example:
William Lallemanda73203e2012-03-12 12:48:57 +01006795
6796 unique-id-format %{+X}o\ %Ci:%Cp_%Fi:%Fp_%Ts_%rt:%pid
6797
6798 will generate:
6799
6800 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
6801
6802 See also: "unique-id-header"
6803
6804unique-id-header <name>
6805 Add a unique ID header in the HTTP request.
6806 May be used in sections : defaults | frontend | listen | backend
6807 yes | yes | yes | no
6808 Arguments :
6809 <name> is the name of the header.
6810
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006811 Add a unique-id header in the HTTP request sent to the server, using the
6812 unique-id-format. It can't work if the unique-id-format doesn't exist.
William Lallemanda73203e2012-03-12 12:48:57 +01006813
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006814 Example:
William Lallemanda73203e2012-03-12 12:48:57 +01006815
6816 unique-id-format %{+X}o\ %Ci:%Cp_%Fi:%Fp_%Ts_%rt:%pid
6817 unique-id-header X-Unique-ID
6818
6819 will generate:
6820
6821 X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
6822
6823 See also: "unique-id-format"
Willy Tarreau844e3c52008-01-11 16:28:18 +01006824
6825use_backend <backend> if <condition>
6826use_backend <backend> unless <condition>
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006827 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006828 May be used in sections : defaults | frontend | listen | backend
6829 no | yes | yes | no
6830 Arguments :
6831 <backend> is the name of a valid backend or "listen" section.
6832
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006833 <condition> is a condition composed of ACLs, as described in section 7.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006834
6835 When doing content-switching, connections arrive on a frontend and are then
6836 dispatched to various backends depending on a number of conditions. The
6837 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006838 "use_backend" keyword. While it is normally used with HTTP processing, it can
6839 also be used in pure TCP, either without content using stateless ACLs (eg:
6840 source address validation) or combined with a "tcp-request" rule to wait for
6841 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006842
6843 There may be as many "use_backend" rules as desired. All of these rules are
6844 evaluated in their declaration order, and the first one which matches will
6845 assign the backend.
6846
6847 In the first form, the backend will be used if the condition is met. In the
6848 second form, the backend will be used if the condition is not met. If no
6849 condition is valid, the backend defined with "default_backend" will be used.
6850 If no default backend is defined, either the servers in the same section are
6851 used (in case of a "listen" section) or, in case of a frontend, no server is
6852 used and a 503 service unavailable response is returned.
6853
Willy Tarreau51aecc72009-07-12 09:47:04 +02006854 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006855 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +02006856 and backend processing will immediately follow, or the backend will wait for
6857 a complete HTTP request to get in. This feature is useful when a frontend
6858 must decode several protocols on a unique port, one of them being HTTP.
6859
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02006860 See also: "default_backend", "tcp-request", and section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +01006861
Willy Tarreau036fae02008-01-06 13:24:40 +01006862
Willy Tarreau4a5cade2012-04-05 21:09:48 +02006863use-server <server> if <condition>
6864use-server <server> unless <condition>
6865 Only use a specific server if/unless an ACL-based condition is matched.
6866 May be used in sections : defaults | frontend | listen | backend
6867 no | no | yes | yes
6868 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006869 <server> is the name of a valid server in the same backend section.
Willy Tarreau4a5cade2012-04-05 21:09:48 +02006870
6871 <condition> is a condition composed of ACLs, as described in section 7.
6872
6873 By default, connections which arrive to a backend are load-balanced across
6874 the available servers according to the configured algorithm, unless a
6875 persistence mechanism such as a cookie is used and found in the request.
6876
6877 Sometimes it is desirable to forward a particular request to a specific
6878 server without having to declare a dedicated backend for this server. This
6879 can be achieved using the "use-server" rules. These rules are evaluated after
6880 the "redirect" rules and before evaluating cookies, and they have precedence
6881 on them. There may be as many "use-server" rules as desired. All of these
6882 rules are evaluated in their declaration order, and the first one which
6883 matches will assign the server.
6884
6885 If a rule designates a server which is down, and "option persist" is not used
6886 and no force-persist rule was validated, it is ignored and evaluation goes on
6887 with the next rules until one matches.
6888
6889 In the first form, the server will be used if the condition is met. In the
6890 second form, the server will be used if the condition is not met. If no
6891 condition is valid, the processing continues and the server will be assigned
6892 according to other persistence mechanisms.
6893
6894 Note that even if a rule is matched, cookie processing is still performed but
6895 does not assign the server. This allows prefixed cookies to have their prefix
6896 stripped.
6897
6898 The "use-server" statement works both in HTTP and TCP mode. This makes it
6899 suitable for use with content-based inspection. For instance, a server could
6900 be selected in a farm according to the TLS SNI field. And if these servers
6901 have their weight set to zero, they will not be used for other traffic.
6902
6903 Example :
6904 # intercept incoming TLS requests based on the SNI field
6905 use-server www if { req_ssl_sni -i www.example.com }
6906 server www 192.168.0.1:443 weight 0
6907 use-server mail if { req_ssl_sni -i mail.example.com }
6908 server mail 192.168.0.1:587 weight 0
6909 use-server imap if { req_ssl_sni -i imap.example.com }
6910 server mail 192.168.0.1:993 weight 0
6911 # all the rest is forwarded to this server
6912 server default 192.168.0.2:443 check
6913
6914 See also: "use_backend", serction 5 about server and section 7 about ACLs.
6915
Willy Tarreaub6205fd2012-09-24 12:27:33 +02006916
69175. Bind and Server options
6918--------------------------
6919
6920The "bind", "server" and "default-server" keywords support a number of settings
6921depending on some build options and on the system HAProxy was built on. These
6922settings generally each consist in one word sometimes followed by a value,
6923written on the same line as the "bind" or "server" line. All these options are
6924described in this section.
6925
6926
69275.1. Bind options
6928-----------------
6929
6930The "bind" keyword supports a certain number of settings which are all passed
6931as arguments on the same line. The order in which those arguments appear makes
6932no importance, provided that they appear after the bind address. All of these
6933parameters are optional. Some of them consist in a single words (booleans),
6934while other ones expect a value after them. In this case, the value must be
6935provided immediately after the setting name.
6936
6937The currently supported settings are the following ones.
6938
6939accept-proxy
6940 Enforces the use of the PROXY protocol over any connection accepted by any of
6941 the sockets declared on the same line. The PROXY protocol dictates the layer
6942 3/4 addresses of the incoming connection to be used everywhere an address is
6943 used, with the only exception of "tcp-request connection" rules which will
6944 only see the real connection address. Logs will reflect the addresses
6945 indicated in the protocol, unless it is violated, in which case the real
6946 address will still be used. This keyword combined with support from external
6947 components can be used as an efficient and reliable alternative to the
6948 X-Forwarded-For mechanism which is not always reliable and not even always
6949 usable.
6950
6951backlog <backlog>
6952 Sets the socket's backlog to this value. If unspecified, the frontend's
6953 backlog is used instead, which generally defaults to the maxconn value.
6954
Emeric Brun7fb34422012-09-28 15:26:15 +02006955ecdhe <named curve>
6956 This setting is only available when support for OpenSSL was built in. It sets
6957 the named curve (RFC 4492) used to generate ECDH ephemeral keys and makes
6958 ECDHE cipher suites usable.
6959
Emeric Brunfd33a262012-10-11 16:28:27 +02006960ca-file <cafile>
Emeric Brun1a073b42012-09-28 17:07:34 +02006961 This setting is only available when support for OpenSSL was built in. It
6962 designates a PEM file from which to load CA certificates used to verify
6963 client's certificate.
6964
Emeric Brunb6dc9342012-09-28 17:55:37 +02006965ca-ignore-err [all|<errorID>,...]
6966 This setting is only available when support for OpenSSL was built in.
6967 Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
6968 If set to 'all', all errors are ignored. SSL handshake is not aborted if an
6969 error is ignored.
6970
Willy Tarreaub6205fd2012-09-24 12:27:33 +02006971ciphers <ciphers>
6972 This setting is only available when support for OpenSSL was built in. It sets
6973 the string describing the list of cipher algorithms ("cipher suite") that are
6974 negociated during the SSL/TLS handshake. The format of the string is defined
6975 in "man 1 ciphers" from OpenSSL man pages, and can be for instance a string
6976 such as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes).
6977
Emeric Brunfd33a262012-10-11 16:28:27 +02006978crl-file <crlfile>
Emeric Brun1a073b42012-09-28 17:07:34 +02006979 This setting is only available when support for OpenSSL was built in. It
6980 designates a PEM file from which to load certificate revocation list used
6981 to verify client's certificate.
6982
Willy Tarreaub6205fd2012-09-24 12:27:33 +02006983crt <cert>
6984 This setting is only available when support for OpenSSL was built in.
6985 It designates a PEM file from which to load both a certificate and the
6986 associated private key. This file can be built by concatenating both PEM
Emeric Brune032bfa2012-09-28 13:01:45 +02006987 files into one. If the OpenSSL used supports Diffie-Hellman, parameters
6988 present in this file are also loaded. If a directory name is used instead of a
6989 PEM file, then all files found in that directory will be loaded. This
6990 directive may be specified multiple times in order to load certificates from
6991 multiple files or directories. The certificates will be presented to clients
6992 who provide a valid TLS Server Name Indication field matching one of their CN
6993 or alt subjects. Wildcards are supported, where a wildcard character '*' is
6994 used instead of the first hostname component (eg: *.example.org matches
Willy Tarreaub6205fd2012-09-24 12:27:33 +02006995 www.example.org but not www.sub.example.org). If no SNI is provided by the
Emeric Brune032bfa2012-09-28 13:01:45 +02006996 client or if the SSL library does not support TLS extensions, or if the client
6997 provides and SNI which does not match any certificate, then the first loaded
6998 certificate will be presented. This means that when loading certificates from
6999 a directory, it is highly recommended to load the default one first as a file.
7000 Note that the same cert may be loaded multiple times without side effects.
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007001
Emeric Brunb6dc9342012-09-28 17:55:37 +02007002crt-ignore-err <errors>
7003 This setting is only available when support for OpenSSL was built in.
7004 Sets a comma separated list of errorIDs to ignore during verify at depth == 0.
7005 If set to 'all', all errors are ignored. SSL handshake is not abored if an
7006 error is ignored.
7007
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007008defer-accept
7009 Is an optional keyword which is supported only on certain Linux kernels. It
7010 states that a connection will only be accepted once some data arrive on it,
7011 or at worst after the first retransmit. This should be used only on protocols
7012 for which the client talks first (eg: HTTP). It can slightly improve
7013 performance by ensuring that most of the request is already available when
7014 the connection is accepted. On the other hand, it will not be able to detect
7015 connections which don't talk. It is important to note that this option is
7016 broken in all kernels up to 2.6.31, as the connection is never accepted until
7017 the client talks. This can cause issues with front firewalls which would see
7018 an established connection while the proxy will only see it in SYN_RECV. This
7019 option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
7020
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007021force-sslv3
7022 This option enforces use of SSLv3 only on SSL connections instanciated from
7023 this listener. SSLv3 is generally less expensive than the TLS counterparts
7024 for high connection rates. See also "force-tls*", "no-sslv3", and "no-tls*".
7025
7026force-tlsv10
7027 This option enforces use of TLSv1.0 only on SSL connections instanciated from
7028 this listener. See also "force-tls*", "no-sslv3", and "no-tls*".
7029
7030force-tlsv11
7031 This option enforces use of TLSv1.1 only on SSL connections instanciated from
7032 this listener. See also "force-tls*", "no-sslv3", and "no-tls*".
7033
7034force-tlsv12
7035 This option enforces use of TLSv1.2 only on SSL connections instanciated from
7036 this listener. See also "force-tls*", "no-sslv3", and "no-tls*".
7037
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007038gid <gid>
7039 Sets the group of the UNIX sockets to the designated system gid. It can also
7040 be set by default in the global section's "unix-bind" statement. Note that
7041 some platforms simply ignore this. This setting is equivalent to the "group"
7042 setting except that the group ID is used instead of its name. This setting is
7043 ignored by non UNIX sockets.
7044
7045group <group>
7046 Sets the group of the UNIX sockets to the designated system group. It can
7047 also be set by default in the global section's "unix-bind" statement. Note
7048 that some platforms simply ignore this. This setting is equivalent to the
7049 "gid" setting except that the group name is used instead of its gid. This
7050 setting is ignored by non UNIX sockets.
7051
7052id <id>
7053 Fixes the socket ID. By default, socket IDs are automatically assigned, but
7054 sometimes it is more convenient to fix them to ease monitoring. This value
7055 must be strictly positive and unique within the listener/frontend. This
7056 option can only be used when defining only a single socket.
7057
7058interface <interface>
7059 Sets the name of the network interface to listen. This is currently only
7060 supported on Linux. The interface must be a primary system interface, not an
7061 aliased interface. When specified, all addresses on the same line will only
7062 be accepted if the incoming packets physically come through the designated
7063 interface. It is also possible to bind multiple frontends to the same address
7064 if they are bound to different interfaces. Note that binding to a network
7065 interface requires root privileges. This parameter is only compatible with
7066 TCPv4/TCPv6 sockets.
7067
Willy Tarreauabb175f2012-09-24 12:43:26 +02007068level <level>
7069 This setting is used with the stats sockets only to restrict the nature of
7070 the commands that can be issued on the socket. It is ignored by other
7071 sockets. <level> can be one of :
7072 - "user" is the least privileged level ; only non-sensitive stats can be
7073 read, and no change is allowed. It would make sense on systems where it
7074 is not easy to restrict access to the socket.
7075 - "operator" is the default level and fits most common uses. All data can
7076 be read, and only non-sensitive changes are permitted (eg: clear max
7077 counters).
7078 - "admin" should be used with care, as everything is permitted (eg: clear
7079 all counters).
7080
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007081maxconn <maxconn>
7082 Limits the sockets to this number of concurrent connections. Extraneous
7083 connections will remain in the system's backlog until a connection is
7084 released. If unspecified, the limit will be the same as the frontend's
7085 maxconn. Note that in case of port ranges or multiple addresses, the same
7086 value will be applied to each socket. This setting enables different
7087 limitations on expensive sockets, for instance SSL entries which may easily
7088 eat all memory.
7089
7090mode <mode>
7091 Sets the octal mode used to define access permissions on the UNIX socket. It
7092 can also be set by default in the global section's "unix-bind" statement.
7093 Note that some platforms simply ignore this. This setting is ignored by non
7094 UNIX sockets.
7095
7096mss <maxseg>
7097 Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming
7098 connections. This can be used to force a lower MSS for certain specific
7099 ports, for instance for connections passing through a VPN. Note that this
7100 relies on a kernel feature which is theoretically supported under Linux but
7101 was buggy in all versions prior to 2.6.28. It may or may not work on other
7102 operating systems. It may also not change the advertised value but change the
7103 effective size of outgoing segments. The commonly advertised value for TCPv4
7104 over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is
7105 positive, it will be used as the advertised MSS. If it is negative, it will
7106 indicate by how much to reduce the incoming connection's advertised MSS for
7107 outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.
7108
7109name <name>
7110 Sets an optional name for these sockets, which will be reported on the stats
7111 page.
7112
7113nice <nice>
7114 Sets the 'niceness' of connections initiated from the socket. Value must be
7115 in the range -1024..1024 inclusive, and defaults to zero. Positive values
7116 means that such connections are more friendly to others and easily offer
7117 their place in the scheduler. On the opposite, negative values mean that
7118 connections want to run with a higher priority than others. The difference
7119 only happens under high loads when the system is close to saturation.
7120 Negative values are appropriate for low-latency or administration services,
7121 and high values are generally recommended for CPU intensive tasks such as SSL
7122 processing or bulk transfers which are less sensible to latency. For example,
7123 it may make sense to use a positive value for an SMTP socket and a negative
7124 one for an RDP socket.
7125
Emeric Brun9b3009b2012-10-05 11:55:06 +02007126no-sslv3
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007127 This setting is only available when support for OpenSSL was built in. It
7128 disables support for SSLv3 on any sockets instanciated from the listener when
7129 SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007130 be enabled using any configuration option. See also "force-tls*",
7131 and "force-sslv3".
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007132
Emeric Brun90ad8722012-10-02 14:00:59 +02007133no-tls-tickets
7134 This setting is only available when support for OpenSSL was built in. It
7135 disables the stateless session resumption (RFC 5077 TLS Ticket
7136 extension) and force to use stateful session resumption. Stateless
7137 session resumption is more expensive in CPU usage.
7138
Emeric Brun9b3009b2012-10-05 11:55:06 +02007139no-tlsv10
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007140 This setting is only available when support for OpenSSL was built in. It
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007141 disables support for TLSv1.0 on any sockets instanciated from the listener
7142 when SSL is supported. Note that SSLv2 is forced disabled in the code and
7143 cannot be enabled using any configuration option. See also "force-tls*",
7144 and "force-sslv3".
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007145
Emeric Brun9b3009b2012-10-05 11:55:06 +02007146no-tlsv11
Emeric Brunf5da4932012-09-28 19:42:54 +02007147 This setting is only available when support for OpenSSL was built in. It
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007148 disables support for TLSv1.1 on any sockets instanciated from the listener
7149 when SSL is supported. Note that SSLv2 is forced disabled in the code and
7150 cannot be enabled using any configuration option. See also "force-tls*",
7151 and "force-sslv3".
Emeric Brunf5da4932012-09-28 19:42:54 +02007152
Emeric Brun9b3009b2012-10-05 11:55:06 +02007153no-tlsv12
Emeric Brunf5da4932012-09-28 19:42:54 +02007154 This setting is only available when support for OpenSSL was built in. It
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007155 disables support for TLSv1.2 on any sockets instanciated from the listener
7156 when SSL is supported. Note that SSLv2 is forced disabled in the code and
7157 cannot be enabled using any configuration option. See also "force-tls*",
7158 and "force-sslv3".
Emeric Brunf5da4932012-09-28 19:42:54 +02007159
Willy Tarreau6c9a3d52012-10-18 18:57:14 +02007160npn <protocols>
7161 This enables the NPN TLS extension and advertises the specified protocol list
7162 as supported on top of NPN. The protocol list consists in a comma-delimited
7163 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
7164 This requires that the SSL library is build with support for TLS extensions
7165 enabled (check with haproxy -vv).
7166
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007167ssl
7168 This setting is only available when support for OpenSSL was built in. It
7169 enables SSL deciphering on connections instanciated from this listener. A
7170 certificate is necessary (see "crt" above). All contents in the buffers will
7171 appear in clear text, so that ACLs and HTTP processing will only have access
7172 to deciphered contents.
7173
Willy Tarreau1c862c52012-10-05 16:21:00 +02007174tfo
7175 Is an optional keyword which is supported only on Linux kernels >= 3.6. It
7176 enables TCP Fast Open on the listening socket, which means that clients which
7177 support this feature will be able to send a request and receive a response
7178 during the 3-way handshake starting from second connection, thus saving one
7179 round-trip after the first connection. This only makes sense with protocols
7180 that use high connection rates and where each round trip matters. This can
7181 possibly cause issues with many firewalls which do not accept data on SYN
7182 packets, so this option should only be enabled once well tested. This option
7183 is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
7184
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007185transparent
7186 Is an optional keyword which is supported only on certain Linux kernels. It
7187 indicates that the addresses will be bound even if they do not belong to the
7188 local machine, and that packets targeting any of these addresses will be
7189 intercepted just as if the addresses were locally configured. This normally
7190 requires that IP forwarding is enabled. Caution! do not use this with the
7191 default address '*', as it would redirect any traffic for the specified port.
7192 This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1.
7193 This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on
7194 kernel version. Some distribution kernels include backports of the feature,
7195 so check for support with your vendor.
7196
Willy Tarreau77e3af92012-11-24 15:07:23 +01007197v4v6
7198 Is an optional keyword which is supported only on most recent systems
7199 including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4
7200 and IPv6 when it uses the default address. Doing so is sometimes necessary
7201 on systems which bind to IPv6 only by default. It has no effect on non-IPv6
7202 sockets, and is overriden by the "v6only" option.
7203
Willy Tarreau9b6700f2012-11-24 11:55:28 +01007204v6only
7205 Is an optional keyword which is supported only on most recent systems
7206 including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only
7207 when it uses the default address. Doing so is sometimes preferred to doing it
Willy Tarreau77e3af92012-11-24 15:07:23 +01007208 system-wide as it is per-listener. It has no effect on non-IPv6 sockets and
7209 has precedence over the "v4v6" option.
Willy Tarreau9b6700f2012-11-24 11:55:28 +01007210
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007211uid <uid>
7212 Sets the owner of the UNIX sockets to the designated system uid. It can also
7213 be set by default in the global section's "unix-bind" statement. Note that
7214 some platforms simply ignore this. This setting is equivalent to the "user"
7215 setting except that the user numeric ID is used instead of its name. This
7216 setting is ignored by non UNIX sockets.
7217
7218user <user>
7219 Sets the owner of the UNIX sockets to the designated system user. It can also
7220 be set by default in the global section's "unix-bind" statement. Note that
7221 some platforms simply ignore this. This setting is equivalent to the "uid"
7222 setting except that the user name is used instead of its uid. This setting is
7223 ignored by non UNIX sockets.
7224
Emeric Brun1a073b42012-09-28 17:07:34 +02007225verify [none|optional|required]
7226 This setting is only available when support for OpenSSL was built in. If set
7227 to 'none', client certificate is not requested. This is the default. In other
7228 cases, a client certificate is requested. If the client does not provide a
7229 certificate after the request and if 'verify' is set to 'required', then the
7230 handshake is aborted, while it would have succeeded if set to 'optional'. The
Emeric Brunfd33a262012-10-11 16:28:27 +02007231 certificate provided by the client is always verified using CAs from
7232 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
7233 is aborted, regardless of the 'verify' option, unless the error code exactly
7234 matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.
Willy Tarreau4a5cade2012-04-05 21:09:48 +02007235
Willy Tarreaub6205fd2012-09-24 12:27:33 +020072365.2. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +01007237------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007238
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01007239The "server" and "default-server" keywords support a certain number of settings
7240which are all passed as arguments on the server line. The order in which those
7241arguments appear does not count, and they are all optional. Some of those
7242settings are single words (booleans) while others expect one or several values
7243after them. In this case, the values must immediately follow the setting name.
7244Except default-server, all those settings must be specified after the server's
7245address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +02007246
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007247 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01007248 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +02007249
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007250The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +01007251
Willy Tarreauceb4ac92012-04-28 00:41:46 +02007252addr <ipv4|ipv6>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007253 Using the "addr" parameter, it becomes possible to use a different IP address
7254 to send health-checks. On some servers, it may be desirable to dedicate an IP
7255 address to specific component able to perform complex tests which are more
7256 suitable to health-checks than the application. This parameter is ignored if
7257 the "check" parameter is not set. See also the "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007258
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007259 Supported in default-server: No
7260
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007261backup
7262 When "backup" is present on a server line, the server is only used in load
7263 balancing when all other non-backup servers are unavailable. Requests coming
7264 with a persistence cookie referencing the server will always be served
7265 though. By default, only the first operational backup server is used, unless
7266 the "allbackups" option is set in the backend. See also the "allbackups"
7267 option.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007268
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007269 Supported in default-server: No
7270
Emeric Brunef42d922012-10-11 16:11:36 +02007271ca-file <cafile>
7272 This setting is only available when support for OpenSSL was built in. It
7273 designates a PEM file from which to load CA certificates used to verify
7274 server's certificate.
7275
7276 Supported in default-server: No
7277
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007278check
7279 This option enables health checks on the server. By default, a server is
Patrick Mézardb7aeec62012-01-22 16:01:22 +01007280 always considered available. If "check" is set, the server is available when
7281 accepting periodic TCP connections, to ensure that it is really able to serve
7282 requests. The default address and port to send the tests to are those of the
7283 server, and the default source is the same as the one defined in the
7284 backend. It is possible to change the address using the "addr" parameter, the
7285 port using the "port" parameter, the source address using the "source"
7286 address, and the interval and timers using the "inter", "rise" and "fall"
7287 parameters. The request method is define in the backend using the "httpchk",
7288 "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please
7289 refer to those options and parameters for more information.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007290
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007291 Supported in default-server: No
7292
Willy Tarreau6c16adc2012-10-05 00:04:16 +02007293check-send-proxy
7294 This option forces emission of a PROXY protocol line with outgoing health
7295 checks, regardless of whether the server uses send-proxy or not for the
7296 normal traffic. By default, the PROXY protocol is enabled for health checks
7297 if it is already enabled for normal traffic and if no "port" nor "addr"
7298 directive is present. However, if such a directive is present, the
7299 "check-send-proxy" option needs to be used to force the use of the
7300 protocol. See also the "send-proxy" option for more information.
7301
7302 Supported in default-server: No
7303
Willy Tarreau763a95b2012-10-04 23:15:39 +02007304check-ssl
7305 This option forces encryption of all health checks over SSL, regardless of
7306 whether the server uses SSL or not for the normal traffic. This is generally
7307 used when an explicit "port" or "addr" directive is specified and SSL health
7308 checks are not inherited. It is important to understand that this option
7309 inserts an SSL transport layer below the ckecks, so that a simple TCP connect
7310 check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
7311 common use is to send HTTPS checks by combining "httpchk" with SSL checks.
7312 All SSL settings are common to health checks and traffic (eg: ciphers).
7313 See the "ssl" option for more information.
7314
7315 Supported in default-server: No
7316
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007317ciphers <ciphers>
7318 This option sets the string describing the list of cipher algorithms that is
7319 is negociated during the SSL/TLS handshake with the server. The format of the
7320 string is defined in "man 1 ciphers". When SSL is used to communicate with
7321 servers on the local network, it is common to see a weaker set of algorithms
7322 than what is used over the internet. Doing so reduces CPU usage on both the
7323 server and haproxy while still keeping it compatible with deployed software.
7324 Some algorithms such as RC4-SHA1 are reasonably cheap. If no security at all
7325 is needed and just connectivity, using DES can be appropriate.
7326
Willy Tarreau763a95b2012-10-04 23:15:39 +02007327 Supported in default-server: No
7328
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007329cookie <value>
7330 The "cookie" parameter sets the cookie value assigned to the server to
7331 <value>. This value will be checked in incoming requests, and the first
7332 operational server possessing the same value will be selected. In return, in
7333 cookie insertion or rewrite modes, this value will be assigned to the cookie
7334 sent to the client. There is nothing wrong in having several servers sharing
7335 the same cookie value, and it is in fact somewhat common between normal and
7336 backup servers. See also the "cookie" keyword in backend section.
7337
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007338 Supported in default-server: No
7339
Emeric Brunef42d922012-10-11 16:11:36 +02007340crl-file <crlfile>
7341 This setting is only available when support for OpenSSL was built in. It
7342 designates a PEM file from which to load certificate revocation list used
7343 to verify server's certificate.
7344
7345 Supported in default-server: No
7346
Emeric Bruna7aa3092012-10-26 12:58:00 +02007347crt <cert>
7348 This setting is only available when support for OpenSSL was built in.
7349 It designates a PEM file from which to load both a certificate and the
7350 associated private key. This file can be built by concatenating both PEM
7351 files into one. This certificate will be sent if the server send a client
7352 certificate request.
7353
7354 Supported in default-server: No
7355
Willy Tarreau96839092010-03-29 10:02:24 +02007356disabled
7357 The "disabled" keyword starts the server in the "disabled" state. That means
7358 that it is marked down in maintenance mode, and no connection other than the
7359 ones allowed by persist mode will reach it. It is very well suited to setup
7360 new servers, because normal traffic will never reach them, while it is still
7361 possible to test the service by making use of the force-persist mechanism.
7362
7363 Supported in default-server: No
7364
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007365error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +01007366 If health observing is enabled, the "error-limit" parameter specifies the
7367 number of consecutive errors that triggers event selected by the "on-error"
7368 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007369
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007370 Supported in default-server: Yes
7371
7372 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007373
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007374fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007375 The "fall" parameter states that a server will be considered as dead after
7376 <count> consecutive unsuccessful health checks. This value defaults to 3 if
7377 unspecified. See also the "check", "inter" and "rise" parameters.
7378
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007379 Supported in default-server: Yes
7380
Emeric Brun8694b9a2012-10-05 14:39:07 +02007381force-sslv3
7382 This option enforces use of SSLv3 only when SSL is used to communicate with
7383 the server. SSLv3 is generally less expensive than the TLS counterparts for
7384 high connection rates. See also "no-tlsv*", "no-sslv3".
7385
7386 Supported in default-server: No
7387
7388force-tlsv10
7389 This option enforces use of TLSv1.0 only when SSL is used to communicate with
7390 the server. See also "no-tlsv*", "no-sslv3".
7391
7392 Supported in default-server: No
7393
7394force-tlsv11
7395 This option enforces use of TLSv1.1 only when SSL is used to communicate with
7396 the server. See also "no-tlsv*", "no-sslv3".
7397
7398 Supported in default-server: No
7399
7400force-tlsv12
7401 This option enforces use of TLSv1.2 only when SSL is used to communicate with
7402 the server. See also "no-tlsv*", "no-sslv3".
7403
7404 Supported in default-server: No
7405
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007406id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02007407 Set a persistent ID for the server. This ID must be positive and unique for
7408 the proxy. An unused ID will automatically be assigned if unset. The first
7409 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007410
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007411 Supported in default-server: No
7412
7413inter <delay>
7414fastinter <delay>
7415downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007416 The "inter" parameter sets the interval between two consecutive health checks
7417 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
7418 It is also possible to use "fastinter" and "downinter" to optimize delays
7419 between checks depending on the server state :
7420
7421 Server state | Interval used
7422 ---------------------------------+-----------------------------------------
7423 UP 100% (non-transitional) | "inter"
7424 ---------------------------------+-----------------------------------------
7425 Transitionally UP (going down), |
7426 Transitionally DOWN (going up), | "fastinter" if set, "inter" otherwise.
7427 or yet unchecked. |
7428 ---------------------------------+-----------------------------------------
7429 DOWN 100% (non-transitional) | "downinter" if set, "inter" otherwise.
7430 ---------------------------------+-----------------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +01007431
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007432 Just as with every other time-based parameter, they can be entered in any
7433 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
7434 serves as a timeout for health checks sent to servers if "timeout check" is
7435 not set. In order to reduce "resonance" effects when multiple servers are
7436 hosted on the same hardware, the health-checks of all servers are started
7437 with a small time offset between them. It is also possible to add some random
7438 noise in the health checks interval using the global "spread-checks"
7439 keyword. This makes sense for instance when a lot of backends use the same
7440 servers.
7441
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007442 Supported in default-server: Yes
7443
7444maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007445 The "maxconn" parameter specifies the maximal number of concurrent
7446 connections that will be sent to this server. If the number of incoming
7447 concurrent requests goes higher than this value, they will be queued, waiting
7448 for a connection to be released. This parameter is very important as it can
7449 save fragile servers from going down under extreme loads. If a "minconn"
7450 parameter is specified, the limit becomes dynamic. The default value is "0"
7451 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
7452 the backend's "fullconn" keyword.
7453
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007454 Supported in default-server: Yes
7455
7456maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007457 The "maxqueue" parameter specifies the maximal number of connections which
7458 will wait in the queue for this server. If this limit is reached, next
7459 requests will be redispatched to other servers instead of indefinitely
7460 waiting to be served. This will break persistence but may allow people to
7461 quickly re-log in when the server they try to connect to is dying. The
7462 default value is "0" which means the queue is unlimited. See also the
7463 "maxconn" and "minconn" parameters.
7464
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007465 Supported in default-server: Yes
7466
7467minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007468 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
7469 limit following the backend's load. The server will always accept at least
7470 <minconn> connections, never more than <maxconn>, and the limit will be on
7471 the ramp between both values when the backend has less than <fullconn>
7472 concurrent connections. This makes it possible to limit the load on the
7473 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007474 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007475 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007476
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007477 Supported in default-server: Yes
7478
Emeric Brun9b3009b2012-10-05 11:55:06 +02007479no-sslv3
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007480 This option disables support for SSLv3 when SSL is used to communicate with
7481 the server. Note that SSLv2 is disabled in the code and cannot be enabled
Emeric Brun8694b9a2012-10-05 14:39:07 +02007482 using any configuration option. See also "force-sslv3", "force-tlsv*".
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007483
Willy Tarreau763a95b2012-10-04 23:15:39 +02007484 Supported in default-server: No
7485
Emeric Brunf9c5c472012-10-11 15:28:34 +02007486no-tls-tickets
7487 This setting is only available when support for OpenSSL was built in. It
7488 disables the stateless session resumption (RFC 5077 TLS Ticket
7489 extension) and force to use stateful session resumption. Stateless
7490 session resumption is more expensive in CPU usage for servers.
7491
7492 Supported in default-server: No
7493
Emeric Brun9b3009b2012-10-05 11:55:06 +02007494no-tlsv10
Emeric Brun8694b9a2012-10-05 14:39:07 +02007495 This option disables support for TLSv1.0 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +02007496 the server. Note that SSLv2 is disabled in the code and cannot be enabled
7497 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun8694b9a2012-10-05 14:39:07 +02007498 often makes sense to disable it when communicating with local servers. See
7499 also "force-sslv3", "force-tlsv*".
Emeric Brunf5da4932012-09-28 19:42:54 +02007500
Willy Tarreau763a95b2012-10-04 23:15:39 +02007501 Supported in default-server: No
7502
Emeric Brun9b3009b2012-10-05 11:55:06 +02007503no-tlsv11
Emeric Brun8694b9a2012-10-05 14:39:07 +02007504 This option disables support for TLSv1.1 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +02007505 the server. Note that SSLv2 is disabled in the code and cannot be enabled
7506 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun8694b9a2012-10-05 14:39:07 +02007507 often makes sense to disable it when communicating with local servers. See
7508 also "force-sslv3", "force-tlsv*".
Emeric Brunf5da4932012-09-28 19:42:54 +02007509
Willy Tarreau763a95b2012-10-04 23:15:39 +02007510 Supported in default-server: No
7511
Emeric Brun9b3009b2012-10-05 11:55:06 +02007512no-tlsv12
Emeric Brun8694b9a2012-10-05 14:39:07 +02007513 This option disables support for TLSv1.2 when SSL is used to communicate with
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007514 the server. Note that SSLv2 is disabled in the code and cannot be enabled
7515 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun8694b9a2012-10-05 14:39:07 +02007516 often makes sense to disable it when communicating with local servers. See
7517 also "force-sslv3", "force-tlsv*".
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007518
Willy Tarreau763a95b2012-10-04 23:15:39 +02007519 Supported in default-server: No
7520
Simon Hormanfa461682011-06-25 09:39:49 +09007521non-stick
7522 Never add connections allocated to this sever to a stick-table.
7523 This may be used in conjunction with backup to ensure that
7524 stick-table persistence is disabled for backup servers.
7525
Willy Tarreau763a95b2012-10-04 23:15:39 +02007526 Supported in default-server: No
7527
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007528observe <mode>
7529 This option enables health adjusting based on observing communication with
7530 the server. By default this functionality is disabled and enabling it also
7531 requires to enable health checks. There are two supported modes: "layer4" and
7532 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
7533 significant. In layer7, which is only allowed for http proxies, responses
7534 received from server are verified, like valid/wrong http code, unparsable
Willy Tarreau150d1462012-03-10 08:19:02 +01007535 headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007536
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007537 Supported in default-server: No
7538
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007539 See also the "check", "on-error" and "error-limit".
7540
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007541on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007542 Select what should happen when enough consecutive errors are detected.
7543 Currently, four modes are available:
7544 - fastinter: force fastinter
7545 - fail-check: simulate a failed check, also forces fastinter (default)
7546 - sudden-death: simulate a pre-fatal failed health check, one more failed
7547 check will mark a server down, forces fastinter
7548 - mark-down: mark the server immediately down and force fastinter
7549
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007550 Supported in default-server: Yes
7551
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007552 See also the "check", "observe" and "error-limit".
7553
Simon Hormane0d1bfb2011-06-21 14:34:58 +09007554on-marked-down <action>
7555 Modify what occurs when a server is marked down.
7556 Currently one action is available:
Justin Karnegeseb2c24a2012-05-24 15:28:52 -07007557 - shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
7558 all connections to the server are immediately terminated when the server
7559 goes down. It might be used if the health check detects more complex cases
7560 than a simple connection status, and long timeouts would cause the service
7561 to remain unresponsive for too long a time. For instance, a health check
7562 might detect that a database is stuck and that there's no chance to reuse
7563 existing connections anymore. Connections killed this way are logged with
7564 a 'D' termination code (for "Down").
Simon Hormane0d1bfb2011-06-21 14:34:58 +09007565
7566 Actions are disabled by default
7567
7568 Supported in default-server: Yes
7569
Justin Karnegeseb2c24a2012-05-24 15:28:52 -07007570on-marked-up <action>
7571 Modify what occurs when a server is marked up.
7572 Currently one action is available:
7573 - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
7574 done only if the server is not in backup state and if it is not disabled
7575 (it must have an effective weight > 0). This can be used sometimes to force
7576 an active server to take all the traffic back after recovery when dealing
7577 with long sessions (eg: LDAP, SQL, ...). Doing this can cause more trouble
7578 than it tries to solve (eg: incomplete transactions), so use this feature
7579 with extreme care. Sessions killed because a server comes up are logged
7580 with an 'U' termination code (for "Up").
7581
7582 Actions are disabled by default
7583
7584 Supported in default-server: Yes
7585
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007586port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007587 Using the "port" parameter, it becomes possible to use a different port to
7588 send health-checks. On some servers, it may be desirable to dedicate a port
7589 to a specific component able to perform complex tests which are more suitable
7590 to health-checks than the application. It is common to run a simple script in
7591 inetd for instance. This parameter is ignored if the "check" parameter is not
7592 set. See also the "addr" parameter.
7593
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007594 Supported in default-server: Yes
7595
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007596redir <prefix>
7597 The "redir" parameter enables the redirection mode for all GET and HEAD
7598 requests addressing this server. This means that instead of having HAProxy
7599 forward the request to the server, it will send an "HTTP 302" response with
7600 the "Location" header composed of this prefix immediately followed by the
7601 requested URI beginning at the leading '/' of the path component. That means
7602 that no trailing slash should be used after <prefix>. All invalid requests
7603 will be rejected, and all non-GET or HEAD requests will be normally served by
7604 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007605 mangling nor cookie insertion is possible in the response. However, cookies in
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007606 requests are still analysed, making this solution completely usable to direct
7607 users to a remote location in case of local disaster. Main use consists in
7608 increasing bandwidth for static servers by having the clients directly
7609 connect to them. Note: never use a relative location here, it would cause a
7610 loop between the client and HAProxy!
7611
7612 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
7613
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007614 Supported in default-server: No
7615
7616rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007617 The "rise" parameter states that a server will be considered as operational
7618 after <count> consecutive successful health checks. This value defaults to 2
7619 if unspecified. See also the "check", "inter" and "fall" parameters.
7620
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007621 Supported in default-server: Yes
7622
Willy Tarreau5ab04ec2011-03-20 10:32:26 +01007623send-proxy
7624 The "send-proxy" parameter enforces use of the PROXY protocol over any
7625 connection established to this server. The PROXY protocol informs the other
7626 end about the layer 3/4 addresses of the incoming connection, so that it can
7627 know the client's address or the public address it accessed to, whatever the
7628 upper layer protocol. For connections accepted by an "accept-proxy" listener,
7629 the advertised address will be used. Only TCPv4 and TCPv6 address families
7630 are supported. Other families such as Unix sockets, will report an UNKNOWN
7631 family. Servers using this option can fully be chained to another instance of
7632 haproxy listening with an "accept-proxy" setting. This setting must not be
Willy Tarreau6c16adc2012-10-05 00:04:16 +02007633 used if the server isn't aware of the protocol. When health checks are sent
7634 to the server, the PROXY protocol is automatically used when this option is
7635 set, unless there is an explicit "port" or "addr" directive, in which case an
7636 explicit "check-send-proxy" directive would also be needed to use the PROXY
7637 protocol. See also the "accept-proxy" option of the "bind" keyword.
Willy Tarreau5ab04ec2011-03-20 10:32:26 +01007638
7639 Supported in default-server: No
7640
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007641slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007642 The "slowstart" parameter for a server accepts a value in milliseconds which
7643 indicates after how long a server which has just come back up will run at
7644 full speed. Just as with every other time-based parameter, it can be entered
7645 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
7646 linearly from 0 to 100% during this time. The limitation applies to two
7647 parameters :
7648
7649 - maxconn: the number of connections accepted by the server will grow from 1
7650 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
7651
7652 - weight: when the backend uses a dynamic weighted algorithm, the weight
7653 grows linearly from 1 to 100%. In this case, the weight is updated at every
7654 health-check. For this reason, it is important that the "inter" parameter
7655 is smaller than the "slowstart", in order to maximize the number of steps.
7656
7657 The slowstart never applies when haproxy starts, otherwise it would cause
7658 trouble to running servers. It only applies when a server has been previously
7659 seen as failed.
7660
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007661 Supported in default-server: Yes
7662
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02007663source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02007664source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02007665source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007666 The "source" parameter sets the source address which will be used when
7667 connecting to the server. It follows the exact same parameters and principle
7668 as the backend "source" keyword, except that it only applies to the server
7669 referencing it. Please consult the "source" keyword for details.
7670
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02007671 Additionally, the "source" statement on a server line allows one to specify a
7672 source port range by indicating the lower and higher bounds delimited by a
7673 dash ('-'). Some operating systems might require a valid IP address when a
7674 source port range is specified. It is permitted to have the same IP/range for
7675 several servers. Doing so makes it possible to bypass the maximum of 64k
7676 total concurrent connections. The limit will then reach 64k connections per
7677 server.
7678
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007679 Supported in default-server: No
7680
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007681ssl
Willy Tarreau763a95b2012-10-04 23:15:39 +02007682 This option enables SSL ciphering on outgoing connections to the server. At
7683 the moment, server certificates are not checked, so this is prone to man in
7684 the middle attacks. The real intended use is to permit SSL communication
7685 with software which cannot work in other modes over networks that would
7686 otherwise be considered safe enough for clear text communications. When this
7687 option is used, health checks are automatically sent in SSL too unless there
7688 is a "port" or an "addr" directive indicating the check should be sent to a
7689 different location. See the "check-ssl" optino to force SSL health checks.
7690
7691 Supported in default-server: No
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007692
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007693track [<proxy>/]<server>
7694 This option enables ability to set the current state of the server by
7695 tracking another one. Only a server with checks enabled can be tracked
7696 so it is not possible for example to track a server that tracks another
7697 one. If <proxy> is omitted the current one is used. If disable-on-404 is
7698 used, it has to be enabled on both proxies.
7699
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007700 Supported in default-server: No
7701
Emeric Brunef42d922012-10-11 16:11:36 +02007702verify [none|required]
7703 This setting is only available when support for OpenSSL was built in. If set
7704 to 'none', server certificate is not verified. This is the default. In the
7705 other case, The certificate provided by the server is verified using CAs from
7706 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
7707 is aborted.
7708
7709 Supported in default-server: No
7710
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007711weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007712 The "weight" parameter is used to adjust the server's weight relative to
7713 other servers. All servers will receive a load proportional to their weight
7714 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +02007715 load. The default weight is 1, and the maximal value is 256. A value of 0
7716 means the server will not participate in load-balancing but will still accept
7717 persistent connections. If this parameter is used to distribute the load
7718 according to server's capacity, it is recommended to start with values which
7719 can both grow and shrink, for instance between 10 and 100 to leave enough
7720 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007721
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007722 Supported in default-server: Yes
7723
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007724
77256. HTTP header manipulation
7726---------------------------
7727
7728In HTTP mode, it is possible to rewrite, add or delete some of the request and
7729response headers based on regular expressions. It is also possible to block a
7730request or a response if a particular header matches a regular expression,
7731which is enough to stop most elementary protocol attacks, and to protect
7732against information leak from the internal network. But there is a limitation
7733to this : since HAProxy's HTTP engine does not support keep-alive, only headers
7734passed during the first request of a TCP session will be seen. All subsequent
7735headers will be considered data only and not analyzed. Furthermore, HAProxy
7736never touches data contents, it stops analysis at the end of headers.
7737
Willy Tarreau816b9792009-09-15 21:25:21 +02007738There is an exception though. If HAProxy encounters an "Informational Response"
7739(status code 1xx), it is able to process all rsp* rules which can allow, deny,
7740rewrite or delete a header, but it will refuse to add a header to any such
7741messages as this is not HTTP-compliant. The reason for still processing headers
7742in such responses is to stop and/or fix any possible information leak which may
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007743happen, for instance because another downstream equipment would unconditionally
Willy Tarreau816b9792009-09-15 21:25:21 +02007744add a header, or if a server name appears there. When such messages are seen,
7745normal processing still occurs on the next non-informational messages.
7746
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007747This section covers common usage of the following keywords, described in detail
7748in section 4.2 :
7749
7750 - reqadd <string>
7751 - reqallow <search>
7752 - reqiallow <search>
7753 - reqdel <search>
7754 - reqidel <search>
7755 - reqdeny <search>
7756 - reqideny <search>
7757 - reqpass <search>
7758 - reqipass <search>
7759 - reqrep <search> <replace>
7760 - reqirep <search> <replace>
7761 - reqtarpit <search>
7762 - reqitarpit <search>
7763 - rspadd <string>
7764 - rspdel <search>
7765 - rspidel <search>
7766 - rspdeny <search>
7767 - rspideny <search>
7768 - rsprep <search> <replace>
7769 - rspirep <search> <replace>
7770
7771With all these keywords, the same conventions are used. The <search> parameter
7772is a POSIX extended regular expression (regex) which supports grouping through
7773parenthesis (without the backslash). Spaces and other delimiters must be
7774prefixed with a backslash ('\') to avoid confusion with a field delimiter.
7775Other characters may be prefixed with a backslash to change their meaning :
7776
7777 \t for a tab
7778 \r for a carriage return (CR)
7779 \n for a new line (LF)
7780 \ to mark a space and differentiate it from a delimiter
7781 \# to mark a sharp and differentiate it from a comment
7782 \\ to use a backslash in a regex
7783 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
7784 \xXX to write the ASCII hex code XX as in the C language
7785
7786The <replace> parameter contains the string to be used to replace the largest
7787portion of text matching the regex. It can make use of the special characters
7788above, and can reference a substring which is delimited by parenthesis in the
7789regex, by writing a backslash ('\') immediately followed by one digit from 0 to
77909 indicating the group position (0 designating the entire line). This practice
7791is very common to users of the "sed" program.
7792
7793The <string> parameter represents the string which will systematically be added
7794after the last header line. It can also use special character sequences above.
7795
7796Notes related to these keywords :
7797---------------------------------
7798 - these keywords are not always convenient to allow/deny based on header
7799 contents. It is strongly recommended to use ACLs with the "block" keyword
7800 instead, resulting in far more flexible and manageable rules.
7801
7802 - lines are always considered as a whole. It is not possible to reference
7803 a header name only or a value only. This is important because of the way
7804 headers are written (notably the number of spaces after the colon).
7805
7806 - the first line is always considered as a header, which makes it possible to
7807 rewrite or filter HTTP requests URIs or response codes, but in turn makes
7808 it harder to distinguish between headers and request line. The regex prefix
7809 ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix
7810 ^[^ \t:]*: matches any header name followed by a colon.
7811
7812 - for performances reasons, the number of characters added to a request or to
7813 a response is limited at build time to values between 1 and 4 kB. This
7814 should normally be far more than enough for most usages. If it is too short
7815 on occasional usages, it is possible to gain some space by removing some
7816 useless headers before adding new ones.
7817
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007818 - keywords beginning with "reqi" and "rspi" are the same as their counterpart
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007819 without the 'i' letter except that they ignore case when matching patterns.
7820
7821 - when a request passes through a frontend then a backend, all req* rules
7822 from the frontend will be evaluated, then all req* rules from the backend
7823 will be evaluated. The reverse path is applied to responses.
7824
7825 - req* statements are applied after "block" statements, so that "block" is
7826 always the first one, but before "use_backend" in order to permit rewriting
Willy Tarreaud72758d2010-01-12 10:42:19 +01007827 before switching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007828
7829
Willy Tarreaub937b7e2010-01-12 15:27:54 +010078307. Using ACLs and pattern extraction
7831------------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007832
7833The use of Access Control Lists (ACL) provides a flexible solution to perform
7834content switching and generally to take decisions based on content extracted
7835from the request, the response or any environmental status. The principle is
7836simple :
7837
7838 - define test criteria with sets of values
7839 - perform actions only if a set of tests is valid
7840
7841The actions generally consist in blocking the request, or selecting a backend.
7842
7843In order to define a test, the "acl" keyword is used. The syntax is :
7844
7845 acl <aclname> <criterion> [flags] [operator] <value> ...
7846
7847This creates a new ACL <aclname> or completes an existing one with new tests.
7848Those tests apply to the portion of request/response specified in <criterion>
7849and may be adjusted with optional flags [flags]. Some criteria also support
7850an operator which may be specified before the set of values. The values are
7851of the type supported by the criterion, and are separated by spaces.
7852
7853ACL names must be formed from upper and lower case letters, digits, '-' (dash),
7854'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
7855which means that "my_acl" and "My_Acl" are two different ACLs.
7856
7857There is no enforced limit to the number of ACLs. The unused ones do not affect
7858performance, they just consume a small amount of memory.
7859
7860The following ACL flags are currently supported :
7861
Willy Tarreau2b5285d2010-05-09 23:45:24 +02007862 -i : ignore case during matching of all subsequent patterns.
7863 -f : load patterns from a file.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007864 -- : force end of flags. Useful when a string looks like one of the flags.
7865
Willy Tarreau2b5285d2010-05-09 23:45:24 +02007866The "-f" flag is special as it loads all of the lines it finds in the file
7867specified in argument and loads all of them before continuing. It is even
7868possible to pass multiple "-f" arguments if the patterns are to be loaded from
Willy Tarreau58215a02010-05-13 22:07:43 +02007869multiple files. Empty lines as well as lines beginning with a sharp ('#') will
7870be ignored. All leading spaces and tabs will be stripped. If it is absolutely
7871needed to insert a valid pattern beginning with a sharp, just prefix it with a
7872space so that it is not taken for a comment. Depending on the data type and
7873match method, haproxy may load the lines into a binary tree, allowing very fast
7874lookups. This is true for IPv4 and exact string matching. In this case,
7875duplicates will automatically be removed. Also, note that the "-i" flag applies
Jamie Gloudonaaa21002012-08-25 00:18:33 -04007876to subsequent entries and not to entries loaded from files preceding it. For
Willy Tarreau58215a02010-05-13 22:07:43 +02007877instance :
Willy Tarreau2b5285d2010-05-09 23:45:24 +02007878
7879 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
7880
7881In this example, each line of "exact-ua.lst" will be exactly matched against
7882the "user-agent" header of the request. Then each line of "generic-ua" will be
7883case-insensitively matched. Then the word "test" will be insensitively matched
7884too.
7885
7886Note that right now it is difficult for the ACL parsers to report errors, so if
7887a file is unreadable or unparsable, the most you'll get is a parse error in the
7888ACL. Thus, file-based ACLs should only be produced by reliable processes.
7889
Willy Tarreau6a06a402007-07-15 20:15:28 +02007890Supported types of values are :
Willy Tarreau0ba27502007-12-24 16:55:16 +01007891
Willy Tarreau6a06a402007-07-15 20:15:28 +02007892 - integers or integer ranges
7893 - strings
7894 - regular expressions
7895 - IP addresses and networks
7896
7897
Willy Tarreauc57f0e22009-05-10 13:12:33 +020078987.1. Matching integers
7899----------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007900
7901Matching integers is special in that ranges and operators are permitted. Note
7902that integer matching only applies to positive values. A range is a value
7903expressed with a lower and an upper bound separated with a colon, both of which
7904may be omitted.
7905
7906For instance, "1024:65535" is a valid range to represent a range of
7907unprivileged ports, and "1024:" would also work. "0:1023" is a valid
7908representation of privileged ports, and ":1023" would also work.
7909
Willy Tarreau62644772008-07-16 18:36:06 +02007910As a special case, some ACL functions support decimal numbers which are in fact
7911two integers separated by a dot. This is used with some version checks for
7912instance. All integer properties apply to those decimal numbers, including
7913ranges and operators.
7914
Willy Tarreau6a06a402007-07-15 20:15:28 +02007915For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +01007916operators with ranges does not make much sense and is strongly discouraged.
7917Similarly, it does not make much sense to perform order comparisons with a set
7918of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007919
Willy Tarreau0ba27502007-12-24 16:55:16 +01007920Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +02007921
7922 eq : true if the tested value equals at least one value
7923 ge : true if the tested value is greater than or equal to at least one value
7924 gt : true if the tested value is greater than at least one value
7925 le : true if the tested value is less than or equal to at least one value
7926 lt : true if the tested value is less than at least one value
7927
Willy Tarreau0ba27502007-12-24 16:55:16 +01007928For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +02007929
7930 acl negative-length hdr_val(content-length) lt 0
7931
Willy Tarreau62644772008-07-16 18:36:06 +02007932This one matches SSL versions between 3.0 and 3.1 (inclusive) :
7933
7934 acl sslv3 req_ssl_ver 3:3.1
7935
Willy Tarreau6a06a402007-07-15 20:15:28 +02007936
Willy Tarreauc57f0e22009-05-10 13:12:33 +020079377.2. Matching strings
7938---------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007939
7940String matching applies to verbatim strings as they are passed, with the
7941exception of the backslash ("\") which makes it possible to escape some
7942characters such as the space. If the "-i" flag is passed before the first
7943string, then the matching will be performed ignoring the case. In order
7944to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +01007945before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02007946
7947
Willy Tarreauc57f0e22009-05-10 13:12:33 +020079487.3. Matching regular expressions (regexes)
7949-------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007950
7951Just like with string matching, regex matching applies to verbatim strings as
7952they are passed, with the exception of the backslash ("\") which makes it
7953possible to escape some characters such as the space. If the "-i" flag is
7954passed before the first regex, then the matching will be performed ignoring
7955the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +01007956the "--" flag before the first string. Same principle applies of course to
7957match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02007958
7959
Willy Tarreauceb4ac92012-04-28 00:41:46 +020079607.4. Matching IPv4 and IPv6 addresses
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007961----------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007962
7963IPv4 addresses values can be specified either as plain addresses or with a
7964netmask appended, in which case the IPv4 address matches whenever it is
7965within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01007966host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +01007967difficult to read and debug configurations. If hostnames are used, you should
7968at least ensure that they are present in /etc/hosts so that the configuration
7969does not depend on any random DNS match at the moment the configuration is
7970parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007971
Willy Tarreauceb4ac92012-04-28 00:41:46 +02007972IPv6 may be entered in their usual form, with or without a netmask appended.
7973Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of
7974trouble with randomly resolved IP addresses, host names are never allowed in
7975IPv6 patterns.
7976
7977HAProxy is also able to match IPv4 addresses with IPv6 addresses in the
7978following situations :
7979 - tested address is IPv4, pattern address is IPv4, the match applies
7980 in IPv4 using the supplied mask if any.
7981 - tested address is IPv6, pattern address is IPv6, the match applies
7982 in IPv6 using the supplied mask if any.
7983 - tested address is IPv6, pattern address is IPv4, the match applies in IPv4
7984 using the pattern's mask if the IPv6 address matches with 2002:IPV4::,
7985 ::IPV4 or ::ffff:IPV4, otherwise it fails.
7986 - tested address is IPv4, pattern address is IPv6, the IPv4 address is first
7987 converted to IPv6 by prefixing ::ffff: in front of it, then the match is
7988 applied in IPv6 using the supplied IPv6 mask.
7989
Willy Tarreau6a06a402007-07-15 20:15:28 +02007990
Willy Tarreauc57f0e22009-05-10 13:12:33 +020079917.5. Available matching criteria
7992--------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007993
Willy Tarreauc57f0e22009-05-10 13:12:33 +020079947.5.1. Matching at Layer 4 and below
7995------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01007996
7997A first set of criteria applies to information which does not require any
7998analysis of the request or response contents. Those generally include TCP/IP
Jamie Gloudon801a0a32012-08-25 00:18:33 -04007999addresses and ports, as well as internal values independent on the stream.
Willy Tarreau0ba27502007-12-24 16:55:16 +01008000
Willy Tarreau6a06a402007-07-15 20:15:28 +02008001always_false
8002 This one never matches. All values and flags are ignored. It may be used as
8003 a temporary replacement for another one when adjusting configurations.
8004
8005always_true
8006 This one always matches. All values and flags are ignored. It may be used as
8007 a temporary replacement for another one when adjusting configurations.
8008
Willy Tarreaud63335a2010-02-26 12:56:52 +01008009avg_queue <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008010avg_queue(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008011 Returns the total number of queued connections of the designated backend
8012 divided by the number of active servers. This is very similar to "queue"
8013 except that the size of the farm is considered, in order to give a more
8014 accurate measurement of the time it may take for a new connection to be
8015 processed. The main usage is to return a sorry page to new users when it
8016 becomes certain they will get a degraded service. Note that in the event
8017 there would not be any active server anymore, we would consider twice the
8018 number of queued connections as the measured value. This is a fair estimate,
8019 as we expect one server to get back soon anyway, but we still prefer to send
8020 new traffic to another backend if in better shape. See also the "queue",
8021 "be_conn", and "be_sess_rate" criteria.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +01008022
Willy Tarreaua36af912009-10-10 12:02:45 +02008023be_conn <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008024be_conn(<backend>) <integer>
Willy Tarreaua36af912009-10-10 12:02:45 +02008025 Applies to the number of currently established connections on the backend,
8026 possibly including the connection being evaluated. If no backend name is
8027 specified, the current one is used. But it is also possible to check another
8028 backend. It can be used to use a specific farm when the nominal one is full.
8029 See also the "fe_conn", "queue" and "be_sess_rate" criteria.
Willy Tarreau6a06a402007-07-15 20:15:28 +02008030
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01008031be_id <integer>
8032 Applies to the backend's id. Can be used in frontends to check from which
8033 backend it was called.
8034
Willy Tarreaud63335a2010-02-26 12:56:52 +01008035be_sess_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008036be_sess_rate(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008037 Returns true when the sessions creation rate on the backend matches the
8038 specified values or ranges, in number of new sessions per second. This is
8039 used to switch to an alternate backend when an expensive or fragile one
8040 reaches too high a session rate, or to limit abuse of service (eg. prevent
8041 sucking of an online dictionary).
8042
8043 Example :
8044 # Redirect to an error page if the dictionary is requested too often
8045 backend dynamic
8046 mode http
8047 acl being_scanned be_sess_rate gt 100
8048 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +01008049
Tait Clarridge7896d522012-12-05 21:39:31 -05008050srv_sess_rate(<backend>/<server>) <integer>
8051 Returns true when the sessions creation rate on the server matches the
8052 specified values or ranges, in number of new sessions per second. This is
8053 used to switch to an alternate backend when an expensive or fragile one
8054 reaches too high a session rate, or to limit abuse of service (eg. prevent
8055 latent requests from overloading servers).
8056
8057 Example :
8058 # Redirect to a separate back
8059 acl srv1_full srv_sess_rate(be1/srv1) gt 50
8060 acl srv2_full srv_sess_rate(be1/srv2) gt 50
8061 use_backend be2 if srv1_full or srv2_full
8062
8063
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08008064connslots <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008065connslots(<backend>) <integer>
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08008066 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +02008067 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08008068 usage; see "use_backend" keyword) can be redirected to a different backend.
8069
Willy Tarreau55165fe2009-05-10 12:02:55 +02008070 'connslots' = number of available server connection slots, + number of
8071 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08008072
Willy Tarreaua36af912009-10-10 12:02:45 +02008073 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +02008074 useful when you have a case of traffic going to one single ip, splitting into
8075 multiple backends (perhaps using acls to do name-based load balancing) and
8076 you want to be able to differentiate between different backends, and their
8077 available "connslots". Also, whereas "nbsrv" only measures servers that are
8078 actually *down*, this acl is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +02008079 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08008080
Willy Tarreau55165fe2009-05-10 12:02:55 +02008081 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
8082 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
8083 then this acl clearly does not make sense, in which case the value returned
8084 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08008085
Willy Tarreaud63335a2010-02-26 12:56:52 +01008086dst <ip_address>
Willy Tarreauceb4ac92012-04-28 00:41:46 +02008087 Applies to the local IPv4 or IPv6 address the client connected to. It can be
8088 used to switch to a different backend for some alternative addresses.
Willy Tarreaua36af912009-10-10 12:02:45 +02008089
Willy Tarreaud63335a2010-02-26 12:56:52 +01008090dst_conn <integer>
8091 Applies to the number of currently established connections on the same socket
8092 including the one being evaluated. It can be used to either return a sorry
8093 page before hard-blocking, or to use a specific backend to drain new requests
8094 when the socket is considered saturated. This offers the ability to assign
8095 different limits to different listening ports or addresses. See also the
8096 "fe_conn" and "be_conn" criteria.
8097
8098dst_port <integer>
8099 Applies to the local port the client connected to. It can be used to switch
8100 to a different backend for some alternative ports.
8101
8102fe_conn <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008103fe_conn(<frontend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008104 Applies to the number of currently established connections on the frontend,
8105 possibly including the connection being evaluated. If no frontend name is
8106 specified, the current one is used. But it is also possible to check another
8107 frontend. It can be used to either return a sorry page before hard-blocking,
8108 or to use a specific backend to drain new requests when the farm is
8109 considered saturated. See also the "dst_conn", "be_conn" and "fe_sess_rate"
8110 criteria.
8111
8112fe_id <integer>
Cyril Bonté78caf842010-03-10 22:41:43 +01008113 Applies to the frontend's id. Can be used in backends to check from which
Willy Tarreaud63335a2010-02-26 12:56:52 +01008114 frontend it was called.
Willy Tarreaua36af912009-10-10 12:02:45 +02008115
Willy Tarreau079ff0a2009-03-05 21:34:28 +01008116fe_sess_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008117fe_sess_rate(<frontend>) <integer>
Willy Tarreau079ff0a2009-03-05 21:34:28 +01008118 Returns true when the session creation rate on the current or the named
8119 frontend matches the specified values or ranges, expressed in new sessions
8120 per second. This is used to limit the connection rate to acceptable ranges in
8121 order to prevent abuse of service at the earliest moment. This can be
8122 combined with layer 4 ACLs in order to force the clients to wait a bit for
8123 the rate to go down below the limit.
8124
8125 Example :
8126 # This frontend limits incoming mails to 10/s with a max of 100
8127 # concurrent connections. We accept any connection below 10/s, and
8128 # force excess clients to wait for 100 ms. Since clients are limited to
8129 # 100 max, there cannot be more than 10 incoming mails per second.
8130 frontend mail
8131 bind :25
8132 mode tcp
8133 maxconn 100
8134 acl too_fast fe_sess_rate ge 10
8135 tcp-request inspect-delay 100ms
8136 tcp-request content accept if ! too_fast
8137 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +01008138
Willy Tarreaud63335a2010-02-26 12:56:52 +01008139nbsrv <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008140nbsrv(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008141 Returns true when the number of usable servers of either the current backend
8142 or the named backend matches the values or ranges specified. This is used to
8143 switch to an alternate backend when the number of servers is too low to
8144 to handle some load. It is useful to report a failure when combined with
8145 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +01008146
Willy Tarreaud63335a2010-02-26 12:56:52 +01008147queue <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008148queue(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008149 Returns the total number of queued connections of the designated backend,
8150 including all the connections in server queues. If no backend name is
8151 specified, the current one is used, but it is also possible to check another
8152 one. This can be used to take actions when queuing goes above a known level,
8153 generally indicating a surge of traffic or a massive slowdown on the servers.
8154 One possible action could be to reject new users but still accept old ones.
8155 See also the "avg_queue", "be_conn", and "be_sess_rate" criteria.
8156
Willy Tarreaue9656522010-08-17 15:40:09 +02008157sc1_bytes_in_rate
8158sc2_bytes_in_rate
8159 Returns the average client-to-server bytes rate from the currently tracked
8160 counters, measured in amount of bytes over the period configured in the
8161 table. See also src_bytes_in_rate.
8162
8163sc1_bytes_out_rate
8164sc2_bytes_out_rate
8165 Returns the average server-to-client bytes rate from the currently tracked
8166 counters, measured in amount of bytes over the period configured in the
8167 table. See also src_bytes_out_rate.
8168
Willy Tarreauf73cd112011-08-13 01:45:16 +02008169sc1_clr_gpc0
8170sc2_clr_gpc0
8171 Clears the first General Purpose Counter associated to the currently tracked
8172 counters, and returns its previous value. Before the first invocation, the
8173 stored value is zero, so first invocation will always return zero. The test
8174 can also be used alone and always returns true. This is typically used as a
8175 second ACL in an expression in order to mark a connection when a first ACL
8176 was verified :
8177
8178 # block if 5 consecutive requests continue to come faster than 10 sess
8179 # per second, and reset the counter as soon as the traffic slows down.
8180 acl abuse sc1_http_req_rate gt 10
8181 acl kill sc1_inc_gpc0 gt 5
8182 acl save sc1_clr_gpc0
8183 tcp-request connection accept if !abuse save
8184 tcp-request connection reject if abuse kill
8185
Willy Tarreaue9656522010-08-17 15:40:09 +02008186sc1_conn_cnt
8187sc2_conn_cnt
8188 Returns the cumulated number of incoming connections from currently tracked
8189 counters. See also src_conn_cnt.
8190
8191sc1_conn_cur
8192sc2_conn_cur
8193 Returns the current amount of concurrent connections tracking the same
8194 tracked counters. This number is automatically incremented when tracking
8195 begins and decremented when tracking stops. See also src_conn_cur.
8196
8197sc1_conn_rate
8198sc2_conn_rate
8199 Returns the average connection rate from the currently tracked counters,
8200 measured in amount of connections over the period configured in the table.
8201 See also src_conn_rate.
8202
8203sc1_get_gpc0
8204sc2_get_gpc0
8205 Returns the value of the first General Purpose Counter associated to the
8206 currently tracked counters. See also src_get_gpc0 and sc1/sc2_inc_gpc0.
8207
8208sc1_http_err_cnt
8209sc2_http_err_cnt
8210 Returns the cumulated number of HTTP errors from the currently tracked
8211 counters. This includes the both request errors and 4xx error responses.
8212 See also src_http_err_cnt.
8213
8214sc1_http_err_rate
8215sc2_http_err_rate
8216 Returns the average rate of HTTP errors from the currently tracked counters,
8217 measured in amount of errors over the period configured in the table. This
8218 includes the both request errors and 4xx error responses. See also
8219 src_http_err_rate.
8220
8221sc1_http_req_cnt
8222sc2_http_req_cnt
8223 Returns the cumulated number of HTTP requests from the currently tracked
8224 counters. This includes every started request, valid or not. See also
8225 src_http_req_cnt.
8226
8227sc1_http_req_rate
8228sc2_http_req_rate
8229 Returns the average rate of HTTP requests from the currently tracked
8230 counters, measured in amount of requests over the period configured in
8231 the table. This includes every started request, valid or not. See also
8232 src_http_req_rate.
8233
8234sc1_inc_gpc0
8235sc2_inc_gpc0
8236 Increments the first General Purpose Counter associated to the currently
8237 tracked counters, and returns its value. Before the first invocation, the
8238 stored value is zero, so first invocation will increase it to 1 and will
8239 return 1. The test can also be used alone and always returns true. This is
8240 typically used as a second ACL in an expression in order to mark a connection
8241 when a first ACL was verified :
8242
8243 acl abuse sc1_http_req_rate gt 10
8244 acl kill sc1_inc_gpc0
8245 tcp-request connection reject if abuse kill
8246
8247sc1_kbytes_in
8248sc2_kbytes_in
8249 Returns the amount of client-to-server data from the currently tracked
8250 counters, measured in kilobytes over the period configured in the table. The
8251 test is currently performed on 32-bit integers, which limits values to 4
8252 terabytes. See also src_kbytes_in.
8253
8254sc1_kbytes_out
8255sc2_kbytes_out
8256 Returns the amount of server-to-client data from the currently tracked
8257 counters, measured in kilobytes over the period configured in the table. The
8258 test is currently performed on 32-bit integers, which limits values to 4
8259 terabytes. See also src_kbytes_out.
8260
8261sc1_sess_cnt
8262sc2_sess_cnt
8263 Returns the cumulated number of incoming connections that were transformed
8264 into sessions, which means that they were accepted by a "tcp-request
8265 connection" rule, from the currently tracked counters. A backend may count
8266 more sessions than connections because each connection could result in many
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008267 backend sessions if some HTTP keep-alive is performed over the connection
Willy Tarreaue9656522010-08-17 15:40:09 +02008268 with the client. See also src_sess_cnt.
8269
8270sc1_sess_rate
8271sc2_sess_rate
8272 Returns the average session rate from the currently tracked counters,
8273 measured in amount of sessions over the period configured in the table. A
8274 session is a connection that got past the early "tcp-request connection"
8275 rules. A backend may count more sessions than connections because each
8276 connection could result in many backend sessions if some HTTP keep-alive is
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008277 performed over the connection with the client. See also src_sess_rate.
Willy Tarreaue9656522010-08-17 15:40:09 +02008278
Willy Tarreau2406db42012-12-09 12:16:43 +01008279sc1_trackers
8280sc2_trackers
8281 Returns the current amount of concurrent connections tracking the same
8282 tracked counters. This number is automatically incremented when tracking
8283 begins and decremented when tracking stops. It differs from sc1_conn_cur in
8284 that it does not rely on any stored information but on the table's reference
8285 count (the "use" value which is returned by "show table" on the CLI). This
8286 may sometimes be more suited for layer7 tracking.
8287
Willy Tarreaud63335a2010-02-26 12:56:52 +01008288so_id <integer>
8289 Applies to the socket's id. Useful in frontends with many bind keywords.
8290
8291src <ip_address>
Willy Tarreauceb4ac92012-04-28 00:41:46 +02008292 Applies to the client's IPv4 or IPv6 address. It is usually used to limit
8293 access to certain resources such as statistics. Note that it is the TCP-level
8294 source address which is used, and not the address of a client behind a proxy.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008295
Willy Tarreauc9705a12010-07-27 20:05:50 +02008296src_bytes_in_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008297src_bytes_in_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008298 Returns the average bytes rate from the connection's source IPv4 address in
8299 the current proxy's stick-table or in the designated stick-table, measured in
8300 amount of bytes over the period configured in the table. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02008301 not found, zero is returned. See also sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008302
8303src_bytes_out_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008304src_bytes_out_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008305 Returns the average bytes rate to the connection's source IPv4 address in the
8306 current proxy's stick-table or in the designated stick-table, measured in
8307 amount of bytes over the period configured in the table. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02008308 not found, zero is returned. See also sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008309
Willy Tarreauf73cd112011-08-13 01:45:16 +02008310src_clr_gpc0 <integer>
8311src_clr_gpc0(<table>) <integer>
8312 Clears the first General Purpose Counter associated to the connection's
8313 source IPv4 address in the current proxy's stick-table or in the designated
8314 stick-table, and returns its previous value. If the address is not found, an
8315 entry is created and 0 is returned. The test can also be used alone and
8316 always returns true. This is typically used as a second ACL in an expression
8317 in order to mark a connection when a first ACL was verified :
8318
8319 # block if 5 consecutive requests continue to come faster than 10 sess
8320 # per second, and reset the counter as soon as the traffic slows down.
8321 acl abuse src_http_req_rate gt 10
8322 acl kill src_inc_gpc0 gt 5
8323 acl save src_clr_gpc0
8324 tcp-request connection accept if !abuse save
8325 tcp-request connection reject if abuse kill
8326
Willy Tarreauc9705a12010-07-27 20:05:50 +02008327src_conn_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008328src_conn_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008329 Returns the cumulated number of connections initiated from the current
8330 connection's source IPv4 address in the current proxy's stick-table or in
8331 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreaue9656522010-08-17 15:40:09 +02008332 See also sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008333
8334src_conn_cur <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008335src_conn_cur(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008336 Returns the current amount of concurrent connections initiated from the
8337 current connection's source IPv4 address in the current proxy's stick-table
8338 or in the designated stick-table. If the address is not found, zero is
Willy Tarreaue9656522010-08-17 15:40:09 +02008339 returned. See also sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008340
8341src_conn_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008342src_conn_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008343 Returns the average connection rate from the connection's source IPv4 address
8344 in the current proxy's stick-table or in the designated stick-table, measured
8345 in amount of connections over the period configured in the table. If the
Willy Tarreaue9656522010-08-17 15:40:09 +02008346 address is not found, zero is returned. See also sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008347
8348src_get_gpc0 <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008349src_get_gpc0(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008350 Returns the value of the first General Purpose Counter associated to the
8351 connection's source IPv4 address in the current proxy's stick-table or in
8352 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreaue9656522010-08-17 15:40:09 +02008353 See also sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008354
8355src_http_err_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008356src_http_err_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008357 Returns the cumulated number of HTTP errors from the current connection's
8358 source IPv4 address in the current proxy's stick-table or in the designated
8359 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreaue9656522010-08-17 15:40:09 +02008360 If the address is not found, zero is returned. See also sc1/sc2_http_err_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008361
8362src_http_err_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008363src_http_err_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008364 Returns the average rate of HTTP errors from the current connection's source
8365 IPv4 address in the current proxy's stick-table or in the designated stick-
8366 table, measured in amount of errors over the period configured in the table.
8367 This includes the both request errors and 4xx error responses. If the address
Willy Tarreaue9656522010-08-17 15:40:09 +02008368 is not found, zero is returned. See also sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008369
8370src_http_req_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008371src_http_req_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008372 Returns the cumulated number of HTTP requests from the current connection's
8373 source IPv4 address in the current proxy's stick-table or in the designated
8374 stick-table. This includes every started request, valid or not. If the
Willy Tarreaue9656522010-08-17 15:40:09 +02008375 address is not found, zero is returned. See also sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008376
8377src_http_req_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008378src_http_req_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008379 Returns the average rate of HTTP requests from the current connection's
8380 source IPv4 address in the current proxy's stick-table or in the designated
8381 stick-table, measured in amount of requests over the period configured in the
8382 table. This includes every started request, valid or not. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02008383 not found, zero is returned. See also sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008384
8385src_inc_gpc0 <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008386src_inc_gpc0(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008387 Increments the first General Purpose Counter associated to the connection's
8388 source IPv4 address in the current proxy's stick-table or in the designated
8389 stick-table, and returns its value. If the address is not found, an entry is
8390 created and 1 is returned. The test can also be used alone and always returns
8391 true. This is typically used as a second ACL in an expression in order to
8392 mark a connection when a first ACL was verified :
8393
8394 acl abuse src_http_req_rate gt 10
8395 acl kill src_inc_gpc0
Willy Tarreaue9656522010-08-17 15:40:09 +02008396 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +02008397
8398src_kbytes_in <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008399src_kbytes_in(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008400 Returns the amount of data received from the connection's source IPv4 address
8401 in the current proxy's stick-table or in the designated stick-table, measured
8402 in kilobytes over the period configured in the table. If the address is not
8403 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreaue9656522010-08-17 15:40:09 +02008404 which limits values to 4 terabytes. See also sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008405
8406src_kbytes_out <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008407src_kbytes_out(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008408 Returns the amount of data sent to the connection's source IPv4 address in
8409 the current proxy's stick-table or in the designated stick-table, measured
8410 in kilobytes over the period configured in the table. If the address is not
8411 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreaue9656522010-08-17 15:40:09 +02008412 which limits values to 4 terabytes. See also sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008413
Willy Tarreaud63335a2010-02-26 12:56:52 +01008414src_port <integer>
8415 Applies to the client's TCP source port. This has a very limited usage.
Willy Tarreau079ff0a2009-03-05 21:34:28 +01008416
Willy Tarreauc9705a12010-07-27 20:05:50 +02008417src_sess_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008418src_sess_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008419 Returns the cumulated number of connections initiated from the current
8420 connection's source IPv4 address in the current proxy's stick-table or in the
8421 designated stick-table, that were transformed into sessions, which means that
8422 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreaue9656522010-08-17 15:40:09 +02008423 is returned. See also sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008424
8425src_sess_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008426src_sess_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008427 Returns the average session rate from the connection's source IPv4 address in
8428 the current proxy's stick-table or in the designated stick-table, measured in
8429 amount of sessions over the period configured in the table. A session is a
8430 connection that got past the early "tcp-request" rules. If the address is not
Willy Tarreaue9656522010-08-17 15:40:09 +02008431 found, zero is returned. See also sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008432
8433src_updt_conn_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008434src_updt_conn_cnt(<table>) <integer>
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008435 Creates or updates the entry associated to the source IPv4 address in the
Willy Tarreauc9705a12010-07-27 20:05:50 +02008436 current proxy's stick-table or in the designated stick-table. This table
8437 must be configured to store the "conn_cnt" data type, otherwise the match
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008438 will be ignored. The current count is incremented by one, and the expiration
8439 timer refreshed. The updated count is returned, so this match can't return
8440 zero. This is used to reject service abusers based on their source address.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008441 Note: it is recommended to use the more complete "track-counters" instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008442
8443 Example :
8444 # This frontend limits incoming SSH connections to 3 per 10 second for
8445 # each source address, and rejects excess connections until a 10 second
8446 # silence is observed. At most 20 addresses are tracked.
8447 listen ssh
8448 bind :22
8449 mode tcp
8450 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +02008451 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008452 tcp-request content reject if { src_update_count gt 3 }
8453 server local 127.0.0.1:22
8454
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008455srv_conn(<backend>/<server>) <integer>
Hervé COMMOWICKdaa824e2011-08-05 12:09:44 +02008456 Applies to the number of currently established connections on the server,
8457 possibly including the connection being evaluated.
8458 It can be used to use a specific farm when one server is full.
8459 See also the "fe_conn", "be_conn" and "queue" criteria.
8460
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01008461srv_id <integer>
8462 Applies to the server's id. Can be used in frontends or backends.
8463
Willy Tarreau0b1cd942010-05-16 22:18:27 +02008464srv_is_up(<server>)
8465srv_is_up(<backend>/<server>)
8466 Returns true when the designated server is UP, and false when it is either
8467 DOWN or in maintenance mode. If <backend> is omitted, then the server is
8468 looked up in the current backend. The function takes no arguments since it
8469 is used as a boolean. It is mainly used to take action based on an external
8470 status reported via a health check (eg: a geographical site's availability).
8471 Another possible use which is more of a hack consists in using dummy servers
8472 as boolean variables that can be enabled or disabled from the CLI, so that
8473 rules depending on those ACLs can be tweaked in realtime.
8474
Willy Tarreauc735a072011-03-29 00:57:02 +02008475table_avl <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008476table_avl(<table>) <integer>
Willy Tarreauc735a072011-03-29 00:57:02 +02008477 Returns the total number of available entries in the current proxy's
8478 stick-table or in the designated stick-table. See also table_cnt.
8479
8480table_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008481table_cnt(<table>) <integer>
Willy Tarreauc735a072011-03-29 00:57:02 +02008482 Returns the total number of entries currently in use in the current proxy's
8483 stick-table or in the designated stick-table. See also src_conn_cnt and
8484 table_avl for other entry counting methods.
8485
Willy Tarreau0ba27502007-12-24 16:55:16 +01008486
Willy Tarreaue9656522010-08-17 15:40:09 +020084877.5.2. Matching contents at Layer 4 (also called Layer 6)
8488---------------------------------------------------------
Willy Tarreau62644772008-07-16 18:36:06 +02008489
8490A second set of criteria depends on data found in buffers, but which can change
8491during analysis. This requires that some data has been buffered, for instance
Willy Tarreaue9656522010-08-17 15:40:09 +02008492through TCP request content inspection. Please see the "tcp-request content"
8493keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +02008494
Willy Tarreaub6672b52011-12-12 17:23:41 +01008495rep_ssl_hello_type <integer>
8496 Returns true when data in the response buffer looks like a complete SSL (v3
8497 or superior) hello message and handshake type is equal to <integer>.
8498 This test was designed to be used with TCP response content inspection: a
Willy Tarreau7875d092012-09-10 08:20:03 +02008499 SSL session ID may be fetched. Note that this only applies to raw contents
8500 found in the request buffer and not to contents deciphered via an SSL data
8501 layer, so this will not work with "bind" lines having the "ssl" option.
Willy Tarreaub6672b52011-12-12 17:23:41 +01008502
Willy Tarreau62644772008-07-16 18:36:06 +02008503req_len <integer>
Emeric Brunbede3d02009-06-30 17:54:00 +02008504 Returns true when the length of the data in the request buffer matches the
Willy Tarreau62644772008-07-16 18:36:06 +02008505 specified range. It is important to understand that this test does not
8506 return false as long as the buffer is changing. This means that a check with
8507 equality to zero will almost always immediately match at the beginning of the
8508 session, while a test for more data will wait for that data to come in and
8509 return false only when haproxy is certain that no more data will come in.
8510 This test was designed to be used with TCP request content inspection.
8511
Willy Tarreau2492d5b2009-07-11 00:06:00 +02008512req_proto_http
8513 Returns true when data in the request buffer look like HTTP and correctly
8514 parses as such. It is the same parser as the common HTTP request parser which
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008515 is used so there should be no surprises. This test can be used for instance
Willy Tarreau2492d5b2009-07-11 00:06:00 +02008516 to direct HTTP traffic to a given port and HTTPS traffic to another one
8517 using TCP request content inspection rules.
8518
Emeric Brunbede3d02009-06-30 17:54:00 +02008519req_rdp_cookie <string>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008520req_rdp_cookie(<name>) <string>
Emeric Brunbede3d02009-06-30 17:54:00 +02008521 Returns true when data in the request buffer look like the RDP protocol, and
8522 a cookie is present and equal to <string>. By default, any cookie name is
8523 checked, but a specific cookie name can be specified in parenthesis. The
8524 parser only checks for the first cookie, as illustrated in the RDP protocol
8525 specification. The cookie name is case insensitive. This ACL can be useful
8526 with the "MSTS" cookie, as it can contain the user name of the client
8527 connecting to the server if properly configured on the client. This can be
8528 used to restrict access to certain servers to certain users.
8529
8530req_rdp_cookie_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008531req_rdp_cookie_cnt(<name>) <integer>
Emeric Brunbede3d02009-06-30 17:54:00 +02008532 Returns true when the data in the request buffer look like the RDP protocol
8533 and the number of RDP cookies matches the specified range (typically zero or
8534 one). Optionally a specific cookie name can be checked. This is a simple way
8535 of detecting the RDP protocol, as clients generally send the MSTS or MSTSHASH
8536 cookies.
8537
Willy Tarreaub6672b52011-12-12 17:23:41 +01008538req_ssl_hello_type <integer>
8539 Returns true when data in the request buffer looks like a complete SSL (v3
8540 or superior) hello message and handshake type is equal to <integer>.
8541 This test was designed to be used with TCP request content inspection: an
Willy Tarreau7875d092012-09-10 08:20:03 +02008542 SSL session ID may be fetched. Note that this only applies to raw contents
8543 found in the request buffer and not to contents deciphered via an SSL data
8544 layer, so this will not work with "bind" lines having the "ssl" option.
Willy Tarreaub6672b52011-12-12 17:23:41 +01008545
8546req_ssl_sni <string>
8547 Returns true when data in the request buffer looks like a complete SSL (v3
8548 or superior) client hello message with a Server Name Indication TLS extension
8549 (SNI) matching <string>. SNI normally contains the name of the host the
8550 client tries to connect to (for recent browsers). SNI is useful for allowing
8551 or denying access to certain hosts when SSL/TLS is used by the client. This
8552 test was designed to be used with TCP request content inspection. If content
8553 switching is needed, it is recommended to first wait for a complete client
Willy Tarreau7875d092012-09-10 08:20:03 +02008554 hello (type 1), like in the example below. Note that this only applies to raw
8555 contents found in the request buffer and not to contents deciphered via an
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008556 SSL transport layer, so this will not work with "bind" lines having the "ssl"
Willy Tarreau7875d092012-09-10 08:20:03 +02008557 option. See also "ssl_sni" below.
Willy Tarreaub6672b52011-12-12 17:23:41 +01008558
8559 Examples :
8560 # Wait for a client hello for at most 5 seconds
8561 tcp-request inspect-delay 5s
8562 tcp-request content accept if { req_ssl_hello_type 1 }
8563 use_backend bk_allow if { req_ssl_sni -f allowed_sites }
8564 default_backend bk_sorry_page
8565
Willy Tarreau62644772008-07-16 18:36:06 +02008566req_ssl_ver <decimal>
8567 Returns true when data in the request buffer look like SSL, with a protocol
8568 version matching the specified range. Both SSLv2 hello messages and SSLv3
8569 messages are supported. The test tries to be strict enough to avoid being
8570 easily fooled. In particular, it waits for as many bytes as announced in the
8571 message header if this header looks valid (bound to the buffer size). Note
8572 that TLSv1 is announced as SSL version 3.1. This test was designed to be used
Willy Tarreau7875d092012-09-10 08:20:03 +02008573 with TCP request content inspection. Note that this only applies to raw
8574 contents found in the request buffer and not to contents deciphered via an
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008575 SSL transport layer, so this will not work with "bind" lines having the "ssl"
Willy Tarreau7875d092012-09-10 08:20:03 +02008576 option.
8577
Emeric Brun2525b6b2012-10-18 15:59:43 +02008578ssl_c_ca_err <integer>
8579 Returns true when the incoming connection was made over an SSL/TLS transport
8580 layer, and the ID of the first error detected during verification of the
8581 client certificate at depth > 0 matches the specified value (check man verify
8582 for possible values). Note that error zero means no error was encountered
8583 during this verification process.
8584
8585ssl_c_ca_err_depth <integer>
8586 Returns true when the incoming connection was made over an SSL/TLS transport
8587 layer, and the depth in the CA chain of the first error detected during the
8588 verification of the client certificate matches the specified value. When no
8589 error is found, depth 0 is returned.
8590
8591ssl_c_err <integer>
8592 Returns true when the incoming connection was made over an SSL/TLS transport
8593 layer, and the ID of the first error detected during verification at depth==0
8594 matches the specified value (check man verify for possible values). Note that
8595 error zero means no error was encountered during this verification process.
8596
Emeric Brun87855892012-10-17 17:39:35 +02008597ssl_c_i_dn <string>
8598ssl_c_i_dn(entry[,occ]) <string>
8599 If no entry specified, returns true when the incoming connection was made
8600 over an SSL/TLS transport layer, and the full distinguished name of the
8601 issuer of the certificate presented by the client matches the specified
8602 string. Otherwise returns true if the value of the first given entry from
8603 the beginning of the DN matches the specified string. If a positive/negative
8604 occurrence number is specified as the optional second argument, it returns
8605 true if the value of the nth given entry value from the beginning/end of the
8606 DN matches the specified string.
8607
Emeric Brun7f56e742012-10-19 18:15:40 +02008608ssl_c_key_alg <string>
8609 Returns true when the incoming connection was made over an SSL/TLS transport
8610 layer, and the name of the algorithm used to generate the key of the
8611 certificate presented by the client matches the string.
8612
Emeric Brunce5ad802012-10-22 14:11:22 +02008613ssl_c_notafter <string>
8614 Returns true when the incoming connection was made over an SSL/TLS transport
8615 layer, and the end date of the certificate presented by the client matches
8616 the string formatted as YYMMDDhhmmss[Z].
8617
8618ssl_c_notbefore <string>
8619 Returns true when the incoming connection was made over an SSL/TLS transport
8620 layer, and the start date of the certificate presented by the client matches
8621 the string formatted as YYMMDDhhmmss[Z].
8622
Emeric Brun87855892012-10-17 17:39:35 +02008623ssl_c_s_dn <string>
8624ssl_c_s_dn(entry[,occ]) <string>
8625 If no entry specified, returns true when the incoming connection was made
8626 over an SSL/TLS transport layer, and the full distinguished name of the
8627 subject of the certificate presented by the client matches the specified
8628 string. Otherwise returns true if the value of the first given entry from
8629 the beginning of the DN matches the specified string. If a positive/negative
8630 occurrence number is specified as the optional second argument, it returns
8631 true if the value of the nth given entry value from the beginning/end of the
8632 DN matches the specified string.
8633
Willy Tarreau8d598402012-10-22 17:58:39 +02008634ssl_c_serial <hexa>
8635 Returns true when the incoming connection was made over an SSL/TLS transport
8636 layer, and the serial of the certificate presented by the client matches
8637 the value written in hexa.
8638
Emeric Brun7f56e742012-10-19 18:15:40 +02008639ssl_c_sig_alg <string>
8640 Returns true when the incoming connection was made over an SSL/TLS transport
8641 layer, and the name of the algorithm used to sign the certificate presented
8642 by the client matches the string.
8643
Emeric Brun9143d372012-12-20 15:44:16 +01008644ssl_c_used
8645 Returns true if current SSL session uses a client certificate even if current
8646 connection uses SSL session resumption. See also "ssl_fc_has_crt".
8647
Emeric Brun2525b6b2012-10-18 15:59:43 +02008648ssl_c_verify <integer>
8649 Returns true when the incoming connection was made over an SSL/TLS transport
8650 layer, and the verify result matches the specified value (check man verify
8651 for possible values). Zero indicates no error was detected.
8652
Emeric Bruna7359fd2012-10-17 15:03:11 +02008653ssl_c_version <integer>
8654 Returns true when the incoming connection was made over an SSL/TLS transport
8655 layer, and the version of the certificate presented by the client matches
8656 the value.
8657
Emeric Brun87855892012-10-17 17:39:35 +02008658ssl_f_i_dn <string>
8659ssl_f_i_dn(entry[,occ]) <string>
8660 If no entry specified, returns true when the incoming connection was made
8661 over an SSL/TLS transport layer, and the full distinguished name of the
8662 issuer of the certificate presented by the frontend matches the specified
8663 string. Otherwise returns true if the value of the first given entry from
8664 the beginning of the DN matches the specified string. If a positive/negative
8665 occurrence number is specified as the optional second argument, it returns
8666 true if the value of the nth given entry value from the beginning/end of the
8667 DN matches the specified string.
8668
Emeric Brun7f56e742012-10-19 18:15:40 +02008669ssl_c_key_alg <string>
8670 Returns true when the incoming connection was made over an SSL/TLS transport
8671 layer, and the name of the algorithm used to generate the key of the
8672 certificate presented by the frontend matches the string.
8673
Emeric Brunce5ad802012-10-22 14:11:22 +02008674ssl_f_notafter <string>
8675 Returns true when the incoming connection was made over an SSL/TLS transport
8676 layer, and the end date of the certificate presented by the frontend matches
8677 the string formatted as YYMMDDhhmmss[Z].
8678
8679ssl_f_notbefore <string>
8680 Returns true when the incoming connection was made over an SSL/TLS transport
8681 layer, and the start date of the certificate presented by the frontend matches
8682 the string formatted as YYMMDDhhmmss[Z].
8683
Emeric Brun87855892012-10-17 17:39:35 +02008684ssl_f_s_dn <string>
8685ssl_f_s_dn(entry[,occ]) <string>
8686 If no entry specified, returns true when the incoming connection was made
8687 over an SSL/TLS transport layer, and the full distinguished name of the
8688 subject of the certificate presented by the frontend matches the specified
8689 string. Otherwise returns true if the value of the first given entry from
8690 the beginning of the DN matches the specified string. If a positive/negative
8691 occurrence number is specified as the optional second argument, it returns
8692 true if the value of the nth given entry value from the beginning/end of the
8693 DN matches the specified string.
8694
Willy Tarreau8d598402012-10-22 17:58:39 +02008695ssl_f_serial <hexa>
8696 Returns true when the incoming connection was made over an SSL/TLS transport
8697 layer, and the serial of the certificate presented by the frontend matches
8698 the value written in hexa.
8699
Emeric Brun7f56e742012-10-19 18:15:40 +02008700ssl_f_sig_alg <string>
8701 Returns true when the incoming connection was made over an SSL/TLS transport
8702 layer, and the name of the algorithm used to sign the certificate presented
8703 by the frontend matches the string.
8704
Emeric Bruna7359fd2012-10-17 15:03:11 +02008705ssl_f_version <integer>
8706 Returns true when the incoming connection was made over an SSL/TLS transport
8707 layer, and the version of the certificate presented by the frontend matches
8708 the value.
8709
Emeric Brun2525b6b2012-10-18 15:59:43 +02008710ssl_fc
8711 Returns true when the front connection was made via an SSL/TLS transport
8712 layer and is locally deciphered. This means it has matched a socket declared
8713 with a "bind" line having the "ssl" option.
8714
Emeric Brun589fcad2012-10-16 14:13:26 +02008715ssl_fc_alg_keysize <integer>
8716 Returns true when the incoming connection was made over an SSL/TLS transport
8717 layer and the symmetric cipher key size supported in bits matches the value.
8718
8719ssl_fc_cipher <string>
8720 returns true when the incoming connection was made over an ssl/tls transport
8721 layer and the name of the used cipher matches the string.
8722
Emeric Brun2525b6b2012-10-18 15:59:43 +02008723ssl_fc_has_crt
8724 Returns true if a client certificate is present in an incoming connection over
8725 SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
Emeric Brun9143d372012-12-20 15:44:16 +01008726 Note: on SSL session resumption with Session ID or TLS ticket, client
8727 certificate is not present in the current connection but may be retrieved
8728 from the cache or the ticket. So prefer "ssl_c_used" if you want to check if
8729 current SSL session uses a client certificate.
Emeric Brun2525b6b2012-10-18 15:59:43 +02008730
8731ssl_fc_has_sni
Willy Tarreau7875d092012-09-10 08:20:03 +02008732 This is used to check for presence of a Server Name Indication TLS extension
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008733 in an incoming connection was made over an SSL/TLS transport layer. Returns
8734 true when the incoming connection presents a TLS SNI field. This requires
8735 that the SSL library is build with support for TLS extensions enabled (check
8736 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02008737
Emeric Brun2525b6b2012-10-18 15:59:43 +02008738ssl_fc_npn <string>
Willy Tarreaua33c6542012-10-15 13:19:06 +02008739 Returns true when the incoming connection was made over an SSL/TLS transport
8740 layer which deciphered it and found a Next Protocol Negociation TLS extension
8741 sent by the client, matching the specified string. This requires that the SSL
8742 library is build with support for TLS extensions enabled (check haproxy -vv).
Willy Tarreau6c9a3d52012-10-18 18:57:14 +02008743 Note that the TLS NPN extension is not advertised unless the "npn" keyword on
8744 the "bind" line specifies a protocol list. Also, nothing forces the client to
8745 pick a protocol from this list, any other one may be requested.
Willy Tarreaua33c6542012-10-15 13:19:06 +02008746
Emeric Brun589fcad2012-10-16 14:13:26 +02008747ssl_fc_protocol <string>
8748 Returns true when the incoming connection was made over an SSL/TLS transport
8749 layer and the name of the used protocol matches the string.
8750
Emeric Brun2525b6b2012-10-18 15:59:43 +02008751ssl_fc_sni <string>
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008752 Returns true when the incoming connection was made over an SSL/TLS transport
8753 layer which deciphered it and found a Server Name Indication TLS extension
8754 sent by the client, matching the specified string. In HTTPS, the SNI field
8755 (when present) is equal to the requested host name. This match is different
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +02008756 from "req_ssl_sni" above in that it applies to the connection being
8757 deciphered by haproxy and not to SSL contents being blindly forwarded.
Emeric Brun2525b6b2012-10-18 15:59:43 +02008758 See also "ssl_fc_sni_end" and "ssl_fc_sni_req" below. This requires that the
8759 SSL library is build with support for TLS extensions enabled (check
8760 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02008761
Emeric Brun2525b6b2012-10-18 15:59:43 +02008762ssl_fc_sni_end <string>
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008763 Returns true when the incoming connection was made over an SSL/TLS transport
8764 layer which deciphered it and found a Server Name Indication TLS extension
8765 sent by the client, ending like the specified string. In HTTPS, the SNI field
8766 (when present) is equal to the requested host name. This match is different
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +02008767 from "req_ssl_sni" above in that it applies to the connection being
8768 deciphered by haproxy and not to SSL contents being blindly forwarded. This
8769 requires that the SSL library is build with support for TLS extensions
8770 enabled (check haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02008771
Emeric Brun2525b6b2012-10-18 15:59:43 +02008772ssl_fc_sni_reg <regex>
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008773 Returns true when the incoming connection was made over an SSL/TLS transport
8774 layer which deciphered it and found a Server Name Indication TLS extension
8775 sent by the client, matching the specified regex. In HTTPS, the SNI field
8776 (when present) is equal to the requested host name. This match is different
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +02008777 from "req_ssl_sni" above in that it applies to the connection being
8778 deciphered by haproxy and not to SSL contents being blindly forwarded. This
8779 requires that the SSL library is build with support for TLS extensions
8780 enabled (check haproxy -vv).
Willy Tarreau62644772008-07-16 18:36:06 +02008781
Emeric Brun589fcad2012-10-16 14:13:26 +02008782ssl_fc_use_keysize <integer>
8783 Returns true when the incoming connection was made over an SSL/TLS transport
8784 layer and the symmetric cipher key size used in bits matches the value.
8785
Willy Tarreaub6fb4202008-07-20 11:18:28 +02008786wait_end
8787 Waits for the end of the analysis period to return true. This may be used in
8788 conjunction with content analysis to avoid returning a wrong verdict early.
8789 It may also be used to delay some actions, such as a delayed reject for some
8790 special addresses. Since it either stops the rules evaluation or immediately
8791 returns true, it is recommended to use this acl as the last one in a rule.
8792 Please note that the default ACL "WAIT_END" is always usable without prior
8793 declaration. This test was designed to be used with TCP request content
8794 inspection.
8795
8796 Examples :
8797 # delay every incoming request by 2 seconds
8798 tcp-request inspect-delay 2s
8799 tcp-request content accept if WAIT_END
8800
8801 # don't immediately tell bad guys they are rejected
8802 tcp-request inspect-delay 10s
8803 acl goodguys src 10.0.0.0/24
8804 acl badguys src 10.0.1.0/24
8805 tcp-request content accept if goodguys
8806 tcp-request content reject if badguys WAIT_END
8807 tcp-request content reject
8808
Willy Tarreau62644772008-07-16 18:36:06 +02008809
Willy Tarreauc57f0e22009-05-10 13:12:33 +020088107.5.3. Matching at Layer 7
8811--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01008812
Willy Tarreau62644772008-07-16 18:36:06 +02008813A third set of criteria applies to information which can be found at the
Willy Tarreau0ba27502007-12-24 16:55:16 +01008814application layer (layer 7). Those require that a full HTTP request has been
8815read, and are only evaluated then. They may require slightly more CPU resources
8816than the layer 4 ones, but not much since the request and response are indexed.
8817
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02008818base <string>
8819 Returns true when the concatenation of the first Host header and the path
8820 part of the request, which starts at the first slash and ends before the
8821 question mark, equals one of the strings. It may be used to match known
8822 files in virtual hosting environments, such as "www.example.com/favicon.ico".
8823 See also "path" and "uri".
8824
8825base_beg <string>
8826 Returns true when the base (see above) begins with one of the strings. This
8827 can be used to send certain directory names to alternative backends. See also
8828 "path_beg".
8829
8830base_dir <string>
8831 Returns true when one of the strings is found isolated or delimited with
8832 slashes in the base (see above). Probably of little use, see "url_dir" and
8833 "path_dir" instead.
8834
8835base_dom <string>
8836 Returns true when one of the strings is found isolated or delimited with dots
8837 in the base (see above). Probably of little use, see "path_dom" and "url_dom"
8838 instead.
8839
8840base_end <string>
8841 Returns true when the base (see above) ends with one of the strings. This may
8842 be used to control file name extension, though "path_end" is cheaper.
8843
8844base_len <integer>
8845 Returns true when the base (see above) length matches the values or ranges
8846 specified. This may be used to detect abusive requests for instance.
8847
8848base_reg <regex>
8849 Returns true when the base (see above) matches one of the regular
8850 expressions. It can be used any time, but it is important to remember that
8851 regex matching is slower than other methods. See also "path_reg", "url_reg"
8852 and all "base_" criteria.
8853
8854base_sub <string>
8855 Returns true when the base (see above) contains one of the strings. It can be
8856 used to detect particular patterns in paths, such as "../" for example. See
8857 also "base_dir".
8858
Willy Tarreau04aa6a92012-04-06 18:57:55 +02008859cook(<name>) <string>
8860 All "cook*" matching criteria inspect all "Cookie" headers to find a cookie
8861 with the name between parenthesis. If multiple occurrences of the cookie are
8862 found in the request, they will all be evaluated. Spaces around the name and
8863 the value are ignored as requested by the Cookie specification (RFC6265). The
8864 cookie name is case-sensitive. Use the scook() variant for response cookies
8865 sent by the server.
8866
8867 The "cook" criteria returns true if any of the request cookies <name> match
8868 any of the strings. This can be used to check exact for values. For instance,
8869 checking that the "profile" cookie is set to either "silver" or "gold" :
8870
8871 cook(profile) silver gold
8872
8873cook_beg(<name>) <string>
8874 Returns true if any of the request cookies <name> begins with one of the
8875 strings. See "cook" for more information on cookie matching. Use the
8876 scook_beg() variant for response cookies sent by the server.
8877
8878cook_cnt(<name>) <integer>
8879 Returns true when the number of occurrences of the specified cookie matches
8880 the values or ranges specified. This is used to detect presence, absence or
8881 abuse of a specific cookie. See "cook" for more information on header
8882 matching. Use the scook_cnt() variant for response cookies sent by the
8883 server.
8884
8885cook_dir(<name>) <string>
8886 Returns true if any of the request cookies <name> contains one of the strings
8887 either isolated or delimited by slashes. This is used to perform filename or
8888 directory name matching, though it generally is of limited use with cookies.
8889 See "cook" for more information on cookie matching. Use the scook_dir()
8890 variant for response cookies sent by the server.
8891
8892cook_dom(<name>) <string>
8893 Returns true if any of the request cookies <name> contains one of the strings
8894 either isolated or delimited by dots. This is used to perform domain name
8895 matching. See "cook" for more information on cookie matching. Use the
8896 scook_dom() variant for response cookies sent by the server.
8897
8898cook_end(<name>) <string>
8899 Returns true if any of the request cookies <name> ends with one of the
8900 strings. See "cook" for more information on cookie matching. Use the
8901 scook_end() variant for response cookies sent by the server.
8902
8903cook_len(<name>) <integer>
8904 Returns true if any of the request cookies <name> has a length which matches
8905 the values or ranges specified. This may be used to detect empty or too large
8906 cookie values. Note that an absent cookie does not match a zero-length test.
8907 See "cook" for more information on cookie matching. Use the scook_len()
8908 variant for response cookies sent by the server.
8909
8910cook_reg(<name>) <regex>
8911 Returns true if any of the request cookies <name> matches any of the regular
8912 expressions. It can be used at any time, but it is important to remember that
8913 regex matching is slower than other methods. See also other "cook_" criteria,
8914 as well as "cook" for more information on cookie matching. Use the
8915 scook_reg() variant for response cookies sent by the server.
8916
8917cook_sub(<name>) <string>
8918 Returns true if any of the request cookies <name> contains at least one of
8919 the strings. See "cook" for more information on cookie matching. Use the
8920 scook_sub() variant for response cookies sent by the server.
8921
Willy Tarreau51539362012-05-08 12:46:28 +02008922cook_val(<name>) <integer>
8923 Returns true if any of the request cookies <name> starts with a number which
8924 matches the values or ranges specified. This may be used to select a server
8925 based on application-specific cookies. Note that an absent cookie does not
8926 match any value. See "cook" for more information on cookie matching. Use the
8927 scook_val() variant for response cookies sent by the server.
8928
Willy Tarreaud63335a2010-02-26 12:56:52 +01008929hdr <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008930hdr(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008931 Note: all the "hdr*" matching criteria either apply to all headers, or to a
8932 particular header whose name is passed between parenthesis and without any
8933 space. The header name is not case-sensitive. The header matching complies
8934 with RFC2616, and treats as separate headers all values delimited by commas.
Willy Tarreau185b5c42012-04-26 15:11:51 +02008935 If an occurrence number is specified as the optional second argument, only
8936 this occurrence will be considered. Positive values indicate a position from
8937 the first occurrence, 1 being the first one. Negative values indicate
8938 positions relative to the last one, -1 being the last one. Use the shdr()
8939 variant for response headers sent by the server.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008940
8941 The "hdr" criteria returns true if any of the headers matching the criteria
Willy Tarreau25c1ebc2012-04-25 16:21:44 +02008942 match any of the strings. This can be used to check for exact values. For
Willy Tarreaud63335a2010-02-26 12:56:52 +01008943 instance, checking that "connection: close" is set :
8944
8945 hdr(Connection) -i close
8946
8947hdr_beg <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008948hdr_beg(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008949 Returns true when one of the headers begins with one of the strings. See
8950 "hdr" for more information on header matching. Use the shdr_beg() variant for
8951 response headers sent by the server.
8952
8953hdr_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008954hdr_cnt(<header>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008955 Returns true when the number of occurrence of the specified header matches
8956 the values or ranges specified. It is important to remember that one header
8957 line may count as several headers if it has several values. This is used to
8958 detect presence, absence or abuse of a specific header, as well as to block
8959 request smuggling attacks by rejecting requests which contain more than one
8960 of certain headers. See "hdr" for more information on header matching. Use
8961 the shdr_cnt() variant for response headers sent by the server.
8962
8963hdr_dir <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008964hdr_dir(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008965 Returns true when one of the headers contains one of the strings either
8966 isolated or delimited by slashes. This is used to perform filename or
8967 directory name matching, and may be used with Referer. See "hdr" for more
8968 information on header matching. Use the shdr_dir() variant for response
8969 headers sent by the server.
8970
8971hdr_dom <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008972hdr_dom(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008973 Returns true when one of the headers contains one of the strings either
8974 isolated or delimited by dots. This is used to perform domain name matching,
8975 and may be used with the Host header. See "hdr" for more information on
8976 header matching. Use the shdr_dom() variant for response headers sent by the
8977 server.
8978
8979hdr_end <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008980hdr_end(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008981 Returns true when one of the headers ends with one of the strings. See "hdr"
8982 for more information on header matching. Use the shdr_end() variant for
8983 response headers sent by the server.
8984
8985hdr_ip <ip_address>
Willy Tarreauceb4ac92012-04-28 00:41:46 +02008986hdr_ip(<header>[,<occ>]) <address>
8987 Returns true when one of the headers' values contains an IPv4 or IPv6 address
8988 matching <address>. This is mainly used with headers such as X-Forwarded-For
8989 or X-Client-IP. See "hdr" for more information on header matching. Use the
Willy Tarreaud63335a2010-02-26 12:56:52 +01008990 shdr_ip() variant for response headers sent by the server.
8991
Willy Tarreau0e698542011-09-16 08:32:32 +02008992hdr_len <integer>
Willy Tarreau185b5c42012-04-26 15:11:51 +02008993hdr_len(<header>[,<occ>]) <integer>
Willy Tarreau0e698542011-09-16 08:32:32 +02008994 Returns true when at least one of the headers has a length which matches the
8995 values or ranges specified. This may be used to detect empty or too large
8996 headers. See "hdr" for more information on header matching. Use the
8997 shdr_len() variant for response headers sent by the server.
8998
Willy Tarreaud63335a2010-02-26 12:56:52 +01008999hdr_reg <regex>
Willy Tarreau185b5c42012-04-26 15:11:51 +02009000hdr_reg(<header>[,<occ>]) <regex>
Willy Tarreau04aa6a92012-04-06 18:57:55 +02009001 Returns true it one of the headers matches one of the regular expressions. It
Willy Tarreaud63335a2010-02-26 12:56:52 +01009002 can be used at any time, but it is important to remember that regex matching
9003 is slower than other methods. See also other "hdr_" criteria, as well as
9004 "hdr" for more information on header matching. Use the shdr_reg() variant for
9005 response headers sent by the server.
9006
9007hdr_sub <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02009008hdr_sub(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01009009 Returns true when one of the headers contains one of the strings. See "hdr"
9010 for more information on header matching. Use the shdr_sub() variant for
9011 response headers sent by the server.
9012
9013hdr_val <integer>
Willy Tarreau185b5c42012-04-26 15:11:51 +02009014hdr_val(<header>[,<occ>]) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01009015 Returns true when one of the headers starts with a number which matches the
9016 values or ranges specified. This may be used to limit content-length to
9017 acceptable values for example. See "hdr" for more information on header
9018 matching. Use the shdr_val() variant for response headers sent by the server.
9019
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009020http_auth(<userlist>)
9021http_auth_group(<userlist>) <group> [<group>]*
Willy Tarreaud63335a2010-02-26 12:56:52 +01009022 Returns true when authentication data received from the client matches
9023 username & password stored on the userlist. It is also possible to
9024 use http_auth_group to check if the user is assigned to at least one
9025 of specified groups.
9026
9027 Currently only http basic auth is supported.
9028
Willy Tarreau85c27da2011-09-16 07:53:52 +02009029http_first_req
Willy Tarreau7f18e522010-10-22 20:04:13 +02009030 Returns true when the request being processed is the first one of the
9031 connection. This can be used to add or remove headers that may be missing
9032 from some requests when a request is not the first one, or even to perform
9033 some specific ACL checks only on the first request.
9034
Willy Tarreau6a06a402007-07-15 20:15:28 +02009035method <string>
9036 Applies to the method in the HTTP request, eg: "GET". Some predefined ACL
9037 already check for most common methods.
9038
Willy Tarreau6a06a402007-07-15 20:15:28 +02009039path <string>
9040 Returns true when the path part of the request, which starts at the first
9041 slash and ends before the question mark, equals one of the strings. It may be
9042 used to match known files, such as /favicon.ico.
9043
9044path_beg <string>
Willy Tarreau0ba27502007-12-24 16:55:16 +01009045 Returns true when the path begins with one of the strings. This can be used
9046 to send certain directory names to alternative backends.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009047
Willy Tarreau6a06a402007-07-15 20:15:28 +02009048path_dir <string>
9049 Returns true when one of the strings is found isolated or delimited with
9050 slashes in the path. This is used to perform filename or directory name
9051 matching without the risk of wrong match due to colliding prefixes. See also
9052 "url_dir" and "path_sub".
9053
9054path_dom <string>
9055 Returns true when one of the strings is found isolated or delimited with dots
9056 in the path. This may be used to perform domain name matching in proxy
9057 requests. See also "path_sub" and "url_dom".
9058
Willy Tarreaud63335a2010-02-26 12:56:52 +01009059path_end <string>
9060 Returns true when the path ends with one of the strings. This may be used to
9061 control file name extension.
9062
Willy Tarreau0e698542011-09-16 08:32:32 +02009063path_len <integer>
9064 Returns true when the path length matches the values or ranges specified.
9065 This may be used to detect abusive requests for instance.
9066
Willy Tarreau6a06a402007-07-15 20:15:28 +02009067path_reg <regex>
9068 Returns true when the path matches one of the regular expressions. It can be
9069 used any time, but it is important to remember that regex matching is slower
9070 than other methods. See also "url_reg" and all "path_" criteria.
9071
Willy Tarreaud63335a2010-02-26 12:56:52 +01009072path_sub <string>
9073 Returns true when the path contains one of the strings. It can be used to
9074 detect particular patterns in paths, such as "../" for example. See also
9075 "path_dir".
9076
Willy Tarreau0ce3aa02012-04-25 18:46:33 +02009077payload(<offset>,<length>) <string>
9078 Returns true if the block of <length> bytes, starting at byte <offset> in the
9079 request or response buffer (depending on the rule) exactly matches one of the
9080 strings.
9081
9082payload_lv(<offset1>,<length>[,<offset2>])
9083 Returns true if the block whose size is specified at <offset1> for <length>
9084 bytes, and which starts at <offset2> if specified or just after the length in
9085 the request or response buffer (depending on the rule) exactly matches one of
9086 the strings. The <offset2> parameter also supports relative offsets if
9087 prepended with a '+' or '-' sign.
9088
Willy Tarreaud63335a2010-02-26 12:56:52 +01009089req_ver <string>
9090 Applies to the version string in the HTTP request, eg: "1.0". Some predefined
9091 ACL already check for versions 1.0 and 1.1.
9092
9093status <integer>
9094 Applies to the HTTP status code in the HTTP response, eg: "302". It can be
9095 used to act on responses depending on status ranges, for instance, remove
9096 any Location header if the response is not a 3xx.
9097
Willy Tarreau6a06a402007-07-15 20:15:28 +02009098url <string>
9099 Applies to the whole URL passed in the request. The only real use is to match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02009100 "*", for which there already is a predefined ACL. See also "base".
Willy Tarreau6a06a402007-07-15 20:15:28 +02009101
9102url_beg <string>
9103 Returns true when the URL begins with one of the strings. This can be used to
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02009104 check whether a URL begins with a slash or with a protocol scheme. See also
9105 "base_beg".
Willy Tarreau6a06a402007-07-15 20:15:28 +02009106
Willy Tarreau6a06a402007-07-15 20:15:28 +02009107url_dir <string>
9108 Returns true when one of the strings is found isolated or delimited with
9109 slashes in the URL. This is used to perform filename or directory name
9110 matching without the risk of wrong match due to colliding prefixes. See also
9111 "path_dir" and "url_sub".
9112
9113url_dom <string>
9114 Returns true when one of the strings is found isolated or delimited with dots
9115 in the URL. This is used to perform domain name matching without the risk of
9116 wrong match due to colliding prefixes. See also "url_sub".
9117
Willy Tarreaud63335a2010-02-26 12:56:52 +01009118url_end <string>
9119 Returns true when the URL ends with one of the strings. It has very limited
9120 use. "path_end" should be used instead for filename matching.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009121
Willy Tarreauceb4ac92012-04-28 00:41:46 +02009122url_ip <address>
9123 Applies to the IPv4 or IPv6 address specified in the absolute URI in an HTTP
9124 request. It can be used to prevent access to certain resources such as local
9125 network. It is useful with option "http_proxy".
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01009126
Willy Tarreau0e698542011-09-16 08:32:32 +02009127url_len <integer>
9128 Returns true when the url length matches the values or ranges specified. This
9129 may be used to detect abusive requests for instance.
9130
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01009131url_port <integer>
Willy Tarreau0ba27502007-12-24 16:55:16 +01009132 Applies to the port specified in the absolute URI in an HTTP request. It can
9133 be used to prevent access to certain resources. It is useful with option
Willy Tarreau198a7442008-01-17 12:05:32 +01009134 "http_proxy". Note that if the port is not specified in the request, port 80
Willy Tarreau0ba27502007-12-24 16:55:16 +01009135 is assumed.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01009136
Willy Tarreaud63335a2010-02-26 12:56:52 +01009137url_reg <regex>
9138 Returns true when the URL matches one of the regular expressions. It can be
9139 used any time, but it is important to remember that regex matching is slower
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02009140 than other methods. See also "base_reg", "path_reg" and all "url_" criteria.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01009141
Willy Tarreaud63335a2010-02-26 12:56:52 +01009142url_sub <string>
9143 Returns true when the URL contains one of the strings. It can be used to
9144 detect particular patterns in query strings for example. See also "path_sub".
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01009145
Willy Tarreau25c1ebc2012-04-25 16:21:44 +02009146urlp(<name>) <string>
9147 Note: all "urlp*" matching criteria apply to the first occurrence of the
9148 parameter <name> in the query string. The parameter name is case-sensitive.
9149
9150 The "urlp" matching criteria returns true if the designated URL parameter
9151 matches any of the strings. This can be used to check for exact values.
9152
9153urlp_beg(<name>) <string>
9154 Returns true when the URL parameter "<name>" begins with one of the strings.
9155 This can be used to check whether a URL begins with a slash or with a
9156 protocol scheme.
9157
9158urlp_dir(<name>) <string>
9159 Returns true when the URL parameter "<name>" contains one of the strings
9160 either isolated or delimited with slashes. This is used to perform filename
9161 or directory name matching in a specific URL parameter without the risk of
9162 wrong match due to colliding prefixes. See also "path_dir" and "urlp_sub".
9163
9164urlp_dom(<name>) <string>
9165 Returns true when one of the strings is found isolated or delimited with dots
9166 in the URL parameter "<name>". This is used to perform domain name matching
9167 in a specific URL parameter without the risk of wrong match due to colliding
9168 prefixes. See also "urlp_sub".
9169
9170urlp_end(<name>) <string>
9171 Returns true when the URL parameter "<name>" ends with one of the strings.
9172
9173urlp_ip(<name>) <ip_address>
Willy Tarreauceb4ac92012-04-28 00:41:46 +02009174 Returns true when the URL parameter "<name>" contains an IPv4 or IPv6 address
9175 which matches one of the specified addresses.
Willy Tarreau25c1ebc2012-04-25 16:21:44 +02009176
9177urlp_len(<name>) <integer>
9178 Returns true when the URL parameter "<name>" has a length matching the values
9179 or ranges specified. This is used to detect abusive requests for instance.
9180
9181urlp_reg(<name>) <regex>
9182 Returns true when the URL parameter "<name>" matches one of the regular
9183 expressions. It can be used any time, but it is important to remember that
9184 regex matching is slower than other methods. See also "path_reg" and all
9185 "urlp_" criteria.
9186
9187urlp_sub(<name>) <string>
9188 Returns true when the URL parameter "<name>" contains one of the strings. It
9189 can be used to detect particular patterns in query strings for example. See
9190 also "path_sub" and other "urlp_" criteria.
9191
Willy Tarreaua9fddca2012-07-31 07:51:48 +02009192urlp_val(<name>) <integer>
9193 Returns true when the URL parameter "<name>" starts with a number matching
9194 the values or ranges specified. Note that the absence of the parameter does
9195 not match anything. Integers are unsigned so it is not possible to match
9196 negative data.
9197
Willy Tarreau198a7442008-01-17 12:05:32 +01009198
Willy Tarreauc57f0e22009-05-10 13:12:33 +020091997.6. Pre-defined ACLs
9200---------------------
Willy Tarreauced27012008-01-17 20:35:34 +01009201
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009202Some predefined ACLs are hard-coded so that they do not have to be declared in
9203every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +02009204order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +01009205
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009206ACL name Equivalent to Usage
9207---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009208FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +02009209HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009210HTTP_1.0 req_ver 1.0 match HTTP version 1.0
9211HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +01009212HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
9213HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
9214HTTP_URL_SLASH url_beg / match URL beginning with "/"
9215HTTP_URL_STAR url * match URL equal to "*"
9216LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009217METH_CONNECT method CONNECT match HTTP CONNECT method
9218METH_GET method GET HEAD match HTTP GET or HEAD method
9219METH_HEAD method HEAD match HTTP HEAD method
9220METH_OPTIONS method OPTIONS match HTTP OPTIONS method
9221METH_POST method POST match HTTP POST method
9222METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +02009223RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009224REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +01009225TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009226WAIT_END wait_end wait for end of content analysis
9227---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01009228
Willy Tarreauced27012008-01-17 20:35:34 +01009229
Willy Tarreauc57f0e22009-05-10 13:12:33 +020092307.7. Using ACLs to form conditions
9231----------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01009232
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009233Some actions are only performed upon a valid condition. A condition is a
9234combination of ACLs with operators. 3 operators are supported :
Willy Tarreauced27012008-01-17 20:35:34 +01009235
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009236 - AND (implicit)
9237 - OR (explicit with the "or" keyword or the "||" operator)
9238 - Negation with the exclamation mark ("!")
Willy Tarreauced27012008-01-17 20:35:34 +01009239
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009240A condition is formed as a disjunctive form:
Willy Tarreauced27012008-01-17 20:35:34 +01009241
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009242 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreauced27012008-01-17 20:35:34 +01009243
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009244Such conditions are generally used after an "if" or "unless" statement,
9245indicating when the condition will trigger the action.
Willy Tarreauced27012008-01-17 20:35:34 +01009246
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009247For instance, to block HTTP requests to the "*" URL with methods other than
9248"OPTIONS", as well as POST requests without content-length, and GET or HEAD
9249requests with a content-length greater than 0, and finally every request which
9250is not either GET/HEAD/POST/OPTIONS !
Willy Tarreauced27012008-01-17 20:35:34 +01009251
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009252 acl missing_cl hdr_cnt(Content-length) eq 0
9253 block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
9254 block if METH_GET HTTP_CONTENT
9255 block unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreauced27012008-01-17 20:35:34 +01009256
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009257To select a different backend for requests to static contents on the "www" site
9258and to every request on the "img", "video", "download" and "ftp" hosts :
Willy Tarreauced27012008-01-17 20:35:34 +01009259
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009260 acl url_static path_beg /static /images /img /css
9261 acl url_static path_end .gif .png .jpg .css .js
9262 acl host_www hdr_beg(host) -i www
9263 acl host_static hdr_beg(host) -i img. video. download. ftp.
Willy Tarreauced27012008-01-17 20:35:34 +01009264
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009265 # now use backend "static" for all static-only hosts, and for static urls
9266 # of host "www". Use backend "www" for the rest.
9267 use_backend static if host_static or host_www url_static
9268 use_backend www if host_www
Willy Tarreauced27012008-01-17 20:35:34 +01009269
Willy Tarreau95fa4692010-02-01 13:05:50 +01009270It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
9271expressions that are built on the fly without needing to be declared. They must
9272be enclosed between braces, with a space before and after each brace (because
Jamie Gloudon801a0a32012-08-25 00:18:33 -04009273the braces must be seen as independent words). Example :
Willy Tarreau95fa4692010-02-01 13:05:50 +01009274
9275 The following rule :
9276
9277 acl missing_cl hdr_cnt(Content-length) eq 0
9278 block if METH_POST missing_cl
9279
9280 Can also be written that way :
9281
9282 block if METH_POST { hdr_cnt(Content-length) eq 0 }
9283
9284It is generally not recommended to use this construct because it's a lot easier
9285to leave errors in the configuration when written that way. However, for very
9286simple rules matching only one source IP address for instance, it can make more
9287sense to use them than to declare ACLs with random names. Another example of
9288good use is the following :
9289
9290 With named ACLs :
9291
9292 acl site_dead nbsrv(dynamic) lt 2
9293 acl site_dead nbsrv(static) lt 2
9294 monitor fail if site_dead
9295
9296 With anonymous ACLs :
9297
9298 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
9299
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009300See section 4.2 for detailed help on the "block" and "use_backend" keywords.
Willy Tarreauced27012008-01-17 20:35:34 +01009301
Willy Tarreau5764b382007-11-30 17:46:49 +01009302
Willy Tarreaub937b7e2010-01-12 15:27:54 +010093037.8. Pattern extraction
9304-----------------------
9305
9306The stickiness features relies on pattern extraction in the request and
9307response. Sometimes the data needs to be converted first before being stored,
9308for instance converted from ASCII to IP or upper case to lower case.
9309
9310All these operations of data extraction and conversion are defined as
9311"pattern extraction rules". A pattern rule always has the same format. It
9312begins with a single pattern fetch word, potentially followed by a list of
9313arguments within parenthesis then an optional list of transformations. As
9314much as possible, the pattern fetch functions use the same name as their
9315equivalent used in ACLs.
9316
9317The list of currently supported pattern fetch functions is the following :
9318
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02009319 base This returns the concatenation of the first Host header and the
9320 path part of the request, which starts at the first slash and
9321 ends before the question mark. It can be useful in virtual
9322 hosted environments to detect URL abuses as well as to improve
9323 shared caches efficiency. Using this with a limited size stick
9324 table also allows one to collect statistics about most commonly
9325 requested objects by host/path.
9326
Willy Tarreauab1f7b72012-12-09 13:38:54 +01009327 base32 This returns a 32-bit hash of the value returned by the "base"
9328 fetch method above. This is useful to track per-URL activity on
9329 high traffic sites without having to store all URLs. Instead a
9330 shorter hash is stored, saving a lot of memory. The output type
9331 is an unsigned integer.
9332
Willy Tarreau4a550602012-12-09 14:53:32 +01009333 base32+src This returns the concatenation of the base32 fetch above and the
9334 src fetch below. The resulting type is of type binary, with a
9335 size of 8 or 20 bytes depending on the source address family.
9336 This can be used to track per-IP, per-URL counters.
9337
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009338 src This is the source IPv4 address of the client of the session.
David du Colombier9a6d3c92011-03-17 10:40:24 +01009339 It is of type IPv4 and works on both IPv4 and IPv6 tables.
9340 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent,
9341 according to RFC 4291.
9342
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009343 dst This is the destination IPv4 address of the session on the
9344 client side, which is the address the client connected to.
9345 It can be useful when running in transparent mode. It is of
David du Colombier9a6d3c92011-03-17 10:40:24 +01009346 type IPv4 and works on both IPv4 and IPv6 tables.
9347 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent,
9348 according to RFC 4291.
9349
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009350 dst_port This is the destination TCP port of the session on the client
9351 side, which is the port the client connected to. This might be
9352 used when running in transparent mode or when assigning dynamic
9353 ports to some clients for a whole application session. It is of
9354 type integer and only works with such tables.
9355
Willy Tarreau185b5c42012-04-26 15:11:51 +02009356 hdr(<name>[,<occ>])
9357 This extracts the last occurrence of header <name> in an HTTP
9358 request. Optionally, a specific occurrence might be specified as
9359 a position number. Positive values indicate a position from the
9360 first occurrence, with 1 being the first one. Negative values
9361 indicate positions relative to the last one, with -1 being the
9362 last one. A typical use is with the X-Forwarded-For header once
Willy Tarreaue428fb72011-12-16 21:50:30 +01009363 converted to IP, associated with an IP stick-table.
Willy Tarreau4a568972010-05-12 08:08:50 +02009364
Willy Tarreau6812bcf2012-04-29 09:28:50 +02009365 path This extracts the request's URL path (without the host part). A
9366 typical use is with prefetch-capable caches, and with portals
9367 which need to aggregate multiple information from databases and
9368 keep them in caches. Note that with outgoing caches, it would be
9369 wiser to use "url" instead.
9370
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009371 payload(<offset>,<length>)
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009372 This extracts a binary block of <length> bytes, and starting
9373 at bytes <offset> in the buffer of request or response (request
9374 on "stick on" or "stick match" or response in on "stick store
9375 response").
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009376
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009377 payload_lv(<offset1>,<length>[,<offset2>])
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009378 This extracts a binary block. In a first step the size of the
9379 block is read from response or request buffer at <offset>
9380 bytes and considered coded on <length> bytes. In a second step
9381 data of the block are read from buffer at <offset2> bytes
9382 (by default <lengthoffset> + <lengthsize>).
9383 If <offset2> is prefixed by '+' or '-', it is relative to
9384 <lengthoffset> + <lengthsize> else it is absolute.
9385 Ex: see SSL session id example in "stick table" chapter.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009386
Willy Tarreau25c1ebc2012-04-25 16:21:44 +02009387 src_port This is the source TCP port of the session on the client side,
9388 which is the port the client connected from. It is very unlikely
9389 that this function will be useful but it's available at no cost.
9390 It is of type integer and only works with such tables.
9391
Emeric Brun2525b6b2012-10-18 15:59:43 +02009392 ssl_c_ca_err Returns the ID of the first error detected during verify of the
9393 client certificate at depth > 0, or 0 if no error was detected.
9394
9395 ssl_c_ca_err_depth
9396 Returns the depth of the first error detected during verify. If
9397 no error is encountered in the CA chain, zero is returned.
9398
9399 ssl_c_err Returns the ID of the first error detected during verify of the
9400 client certificate at depth == 0, or 0 if no errors.
9401
Emeric Brun87855892012-10-17 17:39:35 +02009402 ssl_c_i_dn[(entry[,occ])]
9403 If no entry specified, returns the full distinguished name of
9404 the issuer of the certificate presented by the client when
9405 the incoming connection was made over an SSL/TLS transport
9406 layer. Otherwise returns the the value of the first given entry
9407 found from the the beginning of the DN. If a positive/negative
9408 occurrence number is specified as the optional second argument,
9409 it returns the value of the nth given entry found from the
9410 beginning/end of the DN. For instance to retrieve the common
9411 name ssl_c_i_dn(CN) and the second organization unit
9412 ssl_c_i_dn(OU,2).
9413
Emeric Brun7f56e742012-10-19 18:15:40 +02009414 ssl_c_key_alg
9415 Returns the name of the algorithm used to generate the key of
9416 the certificate presented by the client when the incoming
9417 connection was made over an SSL/TLS transport layer.
9418
Emeric Brunce5ad802012-10-22 14:11:22 +02009419 ssl_c_notafter
9420 Returns the end date presented by the client as a formatted
9421 string YYMMDDhhmmss[Z] when the incoming connection was made
9422 over an SSL/TLS transport layer.
9423
9424 ssl_c_notbefore
9425 Returns the start date presented by the client as a formatted
9426 string YYMMDDhhmmss[Z] when the incoming connection was made
9427 over an SSL/TLS transport layer.
9428
Emeric Brun87855892012-10-17 17:39:35 +02009429 ssl_c_s_dn[(entry[,occ])]
9430 If no entry specified, returns the full distinguished name of
9431 the subject of the certificate presented by the client when
9432 the incoming connection was made over an SSL/TLS transport
9433 layer. Otherwise returns the the value of the first given entry
9434 found from the the beginning of the DN. If a positive/negative
9435 occurrence number is specified as the optional second argument,
9436 it returns the value of the nth given entry found from the
9437 beginning/end of the DN. For instance to retrieve the common
9438 name ssl_c_s_dn(CN) and the second organization unit
9439 ssl_c_s_dn(OU,2).
9440
Willy Tarreau8d598402012-10-22 17:58:39 +02009441 ssl_c_serial Returns the serial of the certificate presented by the client
9442 when the incoming connection was made over an SSL/TLS transport
9443 layer.
9444
Emeric Brun7f56e742012-10-19 18:15:40 +02009445 ssl_c_sig_alg
9446 Returns the name of the algorithm used to sign the certificate
9447 presented by the client when the incoming connection was made
9448 over an SSL/TLS transport layer.
9449
Emeric Brun9143d372012-12-20 15:44:16 +01009450 ssl_c_used
9451 Returns 1 if current SSL session use a client certificate,
9452 otherwise 0. See also "ssl_fc_has_crt".
9453
Emeric Brun2525b6b2012-10-18 15:59:43 +02009454 ssl_c_verify Returns the verify result errorID when the incoming connection
9455 was made over an SSL/TLS transport layer, otherwise zero if no
9456 error is encountered.
9457
Emeric Bruna7359fd2012-10-17 15:03:11 +02009458 ssl_c_version
9459 Returns the version of the certificate presented by the client
9460 when the incoming connection was made over an SSL/TLS transport
9461 layer.
9462
Emeric Brun87855892012-10-17 17:39:35 +02009463 ssl_f_i_dn[(entry[,occ])]
9464 If no entry specified, returns the full distinguished name of
9465 the issuer of the certificate presented by the frontend when
9466 the incoming connection was made over an SSL/TLS transport
9467 layer. Otherwise returns the the value of the first given entry
9468 found from the the beginning of the DN. If a positive/negative
9469 occurrence number is specified as the optional second argument,
9470 it returns the value of the nth given entry found from the
9471 beginning/end of the DN. For instance to retrieve the common
9472 name ssl_f_i_dn(CN) and the second organization unit
9473 ssl_f_i_dn(OU,2).
9474
Emeric Brun7f56e742012-10-19 18:15:40 +02009475 ssl_f_key_alg
9476 Returns the name of the algorithm used to generate the key of
9477 the certificate presented by the frontend when the incoming
9478 connection was made over an SSL/TLS transport layer.
9479
Emeric Brunce5ad802012-10-22 14:11:22 +02009480 ssl_f_notafter
9481 Returns the end date presented by the frontend as a formatted
9482 string YYMMDDhhmmss[Z] when the incoming connection was made
9483 over an SSL/TLS transport layer.
9484
9485 ssl_f_notbefore
9486 Returns the start date presented by the frontend as a formatted
9487 string YYMMDDhhmmss[Z] when the incoming connection was made
9488 over an SSL/TLS transport layer.
9489
Emeric Brun87855892012-10-17 17:39:35 +02009490 ssl_f_s_dn[(entry[,occ])]
9491 If no entry specified, returns the full distinguished name of
9492 the subject of the certificate presented by the frontend when
9493 the incoming connection was made over an SSL/TLS transport
9494 layer. Otherwise returns the the value of the first given entry
9495 found from the the beginning of the DN. If a positive/negative
9496 occurrence number is specified as the optional second argument,
9497 it returns the value of the nth given entry found from the
9498 beginning/end of the DN. For instance to retrieve the common
9499 name ssl_f_s_dn(CN) and the second organization unit
9500 ssl_f_s_dn(OU,2).
9501
Willy Tarreau8d598402012-10-22 17:58:39 +02009502 ssl_f_serial Returns the serial of the certificate presented by the frontend
9503 when the incoming connection was made over an SSL/TLS transport
9504 layer.
9505
Emeric Brun7f56e742012-10-19 18:15:40 +02009506 ssl_f_sig_alg
9507 Returns the name of the algorithm used to sign the certificate
9508 presented by the frontend when the incoming connection was made
9509 over an SSL/TLS transport layer.
9510
Emeric Bruna7359fd2012-10-17 15:03:11 +02009511 ssl_f_version
9512 Returns the version of the certificate presented by the frontend
9513 when the incoming connection was made over an SSL/TLS transport
9514 layer.
9515
Emeric Brun2525b6b2012-10-18 15:59:43 +02009516 ssl_fc This checks the transport layer used on the front connection,
9517 and returns 1 if it was made via an SSL/TLS transport layer,
9518 otherwise zero.
9519
Emeric Brun589fcad2012-10-16 14:13:26 +02009520 ssl_fc_alg_keysize
9521 Returns the symmetric cipher key size support d in bits when the
9522 incoming connection was made over an SSL/TLS transport layer.
9523
9524 ssl_fc_cipher
9525 Returns the name of the used cipher when the incoming connection
9526 was made over an SSL/TLS transport layer.
9527
Emeric Brun2525b6b2012-10-18 15:59:43 +02009528 ssl_fc_has_crt
9529 Returns 1 if a client certificate is present in the front
9530 connection over SSL/TLS transport layer, otherwise 0.
Emeric Brun9143d372012-12-20 15:44:16 +01009531 Note: on SSL session resumption with Session ID or TLS ticket,
9532 client certificate is not present in the current connection but
9533 may be retrieved from the cache or the ticket. So prefer
9534 "ssl_c_used" if you want to check if current SSL session uses
9535 a client certificate.
Emeric Brun2525b6b2012-10-18 15:59:43 +02009536
9537 ssl_fc_has_sni
9538 This checks the transport layer used by the front connection, and
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02009539 returns 1 if the connection was made via an SSL/TLS transport
9540 layer and the client sent a Server Name Indication TLS extension,
Willy Tarreau7875d092012-09-10 08:20:03 +02009541 otherwise zero. This requires that the SSL library is build with
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02009542 support for TLS extensions enabled (check haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02009543
Emeric Brun2525b6b2012-10-18 15:59:43 +02009544 ssl_fc_npn This extracts the Next Protocol Negociation field from an
Willy Tarreaua33c6542012-10-15 13:19:06 +02009545 incoming connection made via an SSL/TLS transport layer and
9546 locally deciphered by haproxy. The result is a string containing
9547 the protocol name advertised by the client. The SSL library must
9548 have been built with support for TLS extensions enabled (check
Emeric Brun2525b6b2012-10-18 15:59:43 +02009549 haproxy -vv). See also the "npn" bind keyword.
Willy Tarreaua33c6542012-10-15 13:19:06 +02009550
Emeric Brun589fcad2012-10-16 14:13:26 +02009551 ssl_fc_protocol
Cyril Bonté316a8cf2012-11-11 13:38:27 +01009552 Returns the name of the used protocol when the incoming
9553 connection was made over an SSL/TLS transport layer.
Emeric Brun589fcad2012-10-16 14:13:26 +02009554
Emeric Brunfe68f682012-10-16 14:59:28 +02009555 ssl_fc_session_id
9556 Returns the SSL ID of the front connection when the incoming
9557 connection was made over an SSL/TLS transport layer. Useful to
9558 stick on a given client.
9559
Emeric Brun2525b6b2012-10-18 15:59:43 +02009560 ssl_fc_sni This extracts the Server Name Indication field from an incoming
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02009561 connection made via an SSL/TLS transport layer and locally
9562 deciphered by haproxy. The result typically is a string matching
9563 the HTTPS host name (253 chars or less). The SSL library must
9564 have been built with support for TLS extensions enabled (check
9565 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02009566
Emeric Brun589fcad2012-10-16 14:13:26 +02009567 ssl_fc_use_keysize
9568 Returns the symmetric cipher key size used in bits when the
9569 incoming connection was made over an SSL/TLS transport layer.
9570
Willy Tarreau6812bcf2012-04-29 09:28:50 +02009571 url This extracts the request's URL as presented in the request. A
9572 typical use is with prefetch-capable caches, and with portals
9573 which need to aggregate multiple information from databases and
9574 keep them in caches. See also "path".
9575
9576 url_ip This extracts the IP address from the request's URL when the
9577 host part is presented as an IP address. Its use is very
9578 limited. For instance, a monitoring system might use this field
9579 as an alternative for the source IP in order to test what path a
9580 given source address would follow, or to force an entry in a
9581 table for a given source address.
9582
9583 url_port This extracts the port part from the request's URL. It probably
9584 is totally useless but it was available at no cost.
9585
bedis4c75cca2012-10-05 08:38:24 +02009586 url_param(<name>[,<delim>])
Cyril Bontédc4d9032012-04-08 21:57:39 +02009587 This extracts the first occurrence of the parameter <name> in
bedis4c75cca2012-10-05 08:38:24 +02009588 the parameter string of the request and uses the corresponding
9589 value to match. Optionally, a delimiter can be provided. If not
9590 then the question mark '?' is used by default.
9591 A typical use is to get sticky session through url for cases
9592 where cookies cannot be used.
9593
9594 Example :
9595 # match http://example.com/foo?PHPSESSIONID=some_id
9596 stick on url_param(PHPSESSIONID)
9597 # match http://example.com/foo;JSESSIONID=some_id
9598 stick on url_param(JSESSIONID,;)
David Cournapeau16023ee2010-12-23 20:55:41 +09009599
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009600 rdp_cookie(<name>)
Cyril Bontédc4d9032012-04-08 21:57:39 +02009601 This extracts the value of the rdp cookie <name> as a string
9602 and uses this value to match. This enables implementation of
9603 persistence based on the mstshash cookie. This is typically
9604 done if there is no msts cookie present.
Simon Hormanab814e02011-06-24 14:50:20 +09009605
Cyril Bontédc4d9032012-04-08 21:57:39 +02009606 This differs from "balance rdp-cookie" in that any balancing
9607 algorithm may be used and thus the distribution of clients
9608 to backend servers is not linked to a hash of the RDP
9609 cookie. It is envisaged that using a balancing algorithm
9610 such as "balance roundrobin" or "balance leastconnect" will
9611 lead to a more even distribution of clients to backend
9612 servers than the hash used by "balance rdp-cookie".
Simon Hormanab814e02011-06-24 14:50:20 +09009613
Cyril Bontédc4d9032012-04-08 21:57:39 +02009614 Example :
9615 listen tse-farm
9616 bind 0.0.0.0:3389
9617 # wait up to 5s for an RDP cookie in the request
9618 tcp-request inspect-delay 5s
9619 tcp-request content accept if RDP_COOKIE
9620 # apply RDP cookie persistence
9621 persist rdp-cookie
9622 # Persist based on the mstshash cookie
9623 # This is only useful makes sense if
9624 # balance rdp-cookie is not used
9625 stick-table type string size 204800
9626 stick on rdp_cookie(mstshash)
9627 server srv1 1.1.1.1:3389
9628 server srv1 1.1.1.2:3389
Simon Hormanab814e02011-06-24 14:50:20 +09009629
Cyril Bontédc4d9032012-04-08 21:57:39 +02009630 See also : "balance rdp-cookie", "persist rdp-cookie",
9631 "tcp-request" and the "req_rdp_cookie" ACL.
Simon Hormanab814e02011-06-24 14:50:20 +09009632
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009633 cookie(<name>)
Cyril Bontédc4d9032012-04-08 21:57:39 +02009634 This extracts the last occurrence of the cookie name <name> on a
Willy Tarreau28376d62012-04-26 21:26:10 +02009635 "Cookie" header line from the request, or a "Set-Cookie" header
9636 from the response, and uses the corresponding value to match. A
9637 typical use is to get multiple clients sharing a same profile
9638 use the same server. This can be similar to what "appsession"
9639 does with the "request-learn" statement, but with support for
9640 multi-peer synchronization and state keeping across restarts.
Willy Tarreaub3eb2212011-07-01 16:16:17 +02009641
Cyril Bontédc4d9032012-04-08 21:57:39 +02009642 See also : "appsession"
Willy Tarreaub3eb2212011-07-01 16:16:17 +02009643
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009644 set-cookie(<name>)
Willy Tarreau28376d62012-04-26 21:26:10 +02009645 This fetch function is deprecated and has been superseded by the
9646 "cookie" fetch which is capable of handling both requests and
9647 responses. This keyword will disappear soon.
9648
Cyril Bontédc4d9032012-04-08 21:57:39 +02009649 This extracts the last occurrence of the cookie name <name> on a
9650 "Set-Cookie" header line from the response and uses the
9651 corresponding value to match. This can be comparable to what
9652 "appsession" does with default options, but with support for
9653 multi-peer synchronization and state keeping across restarts.
Willy Tarreaub3eb2212011-07-01 16:16:17 +02009654
Cyril Bontédc4d9032012-04-08 21:57:39 +02009655 See also : "appsession"
Willy Tarreaub3eb2212011-07-01 16:16:17 +02009656
Simon Hormanab814e02011-06-24 14:50:20 +09009657
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009658The currently available list of transformations include :
9659
9660 lower Convert a string pattern to lower case. This can only be placed
9661 after a string pattern fetch function or after a conversion
9662 function returning a string type. The result is of type string.
9663
9664 upper Convert a string pattern to upper case. This can only be placed
9665 after a string pattern fetch function or after a conversion
9666 function returning a string type. The result is of type string.
9667
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009668 ipmask(<mask>) Apply a mask to an IPv4 address, and use the result for lookups
Willy Tarreaud31d6eb2010-01-26 18:01:41 +01009669 and storage. This can be used to make all hosts within a
9670 certain mask to share the same table entries and as such use
9671 the same server. The mask can be passed in dotted form (eg:
9672 255.255.255.0) or in CIDR form (eg: 24).
9673
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009674
Willy Tarreauc57f0e22009-05-10 13:12:33 +020096758. Logging
9676----------
Willy Tarreau844e3c52008-01-11 16:28:18 +01009677
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009678One of HAProxy's strong points certainly lies is its precise logs. It probably
9679provides the finest level of information available for such a product, which is
9680very important for troubleshooting complex environments. Standard information
9681provided in logs include client ports, TCP/HTTP state timers, precise session
9682state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009683to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009684headers.
9685
9686In order to improve administrators reactivity, it offers a great transparency
9687about encountered problems, both internal and external, and it is possible to
9688send logs to different sources at the same time with different level filters :
9689
9690 - global process-level logs (system errors, start/stop, etc..)
9691 - per-instance system and internal errors (lack of resource, bugs, ...)
9692 - per-instance external troubles (servers up/down, max connections)
9693 - per-instance activity (client connections), either at the establishment or
9694 at the termination.
9695
9696The ability to distribute different levels of logs to different log servers
9697allow several production teams to interact and to fix their problems as soon
9698as possible. For example, the system team might monitor system-wide errors,
9699while the application team might be monitoring the up/down for their servers in
9700real time, and the security team might analyze the activity logs with one hour
9701delay.
9702
9703
Willy Tarreauc57f0e22009-05-10 13:12:33 +020097048.1. Log levels
9705---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009706
Simon Hormandf791f52011-05-29 15:01:10 +09009707TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009708source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +09009709HTTP request, HTTP return code, number of bytes transmitted, conditions
9710in which the session ended, and even exchanged cookies values. For example
9711track a particular user's problems. All messages may be sent to up to two
9712syslog servers. Check the "log" keyword in section 4.2 for more information
9713about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009714
9715
Willy Tarreauc57f0e22009-05-10 13:12:33 +020097168.2. Log formats
9717----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009718
William Lallemand48940402012-01-30 16:47:22 +01009719HAProxy supports 5 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +09009720and will be detailed in the following sections. A few of them may vary
9721slightly with the configuration, due to indicators specific to certain
9722options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009723
9724 - the default format, which is very basic and very rarely used. It only
9725 provides very basic information about the incoming connection at the moment
9726 it is accepted : source IP:port, destination IP:port, and frontend-name.
9727 This mode will eventually disappear so it will not be described to great
9728 extents.
9729
9730 - the TCP format, which is more advanced. This format is enabled when "option
9731 tcplog" is set on the frontend. HAProxy will then usually wait for the
9732 connection to terminate before logging. This format provides much richer
9733 information, such as timers, connection counts, queue size, etc... This
9734 format is recommended for pure TCP proxies.
9735
9736 - the HTTP format, which is the most advanced for HTTP proxying. This format
9737 is enabled when "option httplog" is set on the frontend. It provides the
9738 same information as the TCP format with some HTTP-specific fields such as
9739 the request, the status code, and captures of headers and cookies. This
9740 format is recommended for HTTP proxies.
9741
Emeric Brun3a058f32009-06-30 18:26:00 +02009742 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
9743 fields arranged in the same order as the CLF format. In this mode, all
9744 timers, captures, flags, etc... appear one per field after the end of the
9745 common fields, in the same order they appear in the standard HTTP format.
9746
William Lallemand48940402012-01-30 16:47:22 +01009747 - the custom log format, allows you to make your own log line.
9748
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009749Next sections will go deeper into details for each of these formats. Format
9750specification will be performed on a "field" basis. Unless stated otherwise, a
9751field is a portion of text delimited by any number of spaces. Since syslog
9752servers are susceptible of inserting fields at the beginning of a line, it is
9753always assumed that the first field is the one containing the process name and
9754identifier.
9755
9756Note : Since log lines may be quite long, the log examples in sections below
9757 might be broken into multiple lines. The example log lines will be
9758 prefixed with 3 closing angle brackets ('>>>') and each time a log is
9759 broken into multiple lines, each non-final line will end with a
9760 backslash ('\') and the next line will start indented by two characters.
9761
9762
Willy Tarreauc57f0e22009-05-10 13:12:33 +020097638.2.1. Default log format
9764-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009765
9766This format is used when no specific option is set. The log is emitted as soon
9767as the connection is accepted. One should note that this currently is the only
9768format which logs the request's destination IP and ports.
9769
9770 Example :
9771 listen www
9772 mode http
9773 log global
9774 server srv1 127.0.0.1:8000
9775
9776 >>> Feb 6 12:12:09 localhost \
9777 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
9778 (www/HTTP)
9779
9780 Field Format Extract from the example above
9781 1 process_name '[' pid ']:' haproxy[14385]:
9782 2 'Connect from' Connect from
9783 3 source_ip ':' source_port 10.0.1.2:33312
9784 4 'to' to
9785 5 destination_ip ':' destination_port 10.0.3.31:8012
9786 6 '(' frontend_name '/' mode ')' (www/HTTP)
9787
9788Detailed fields description :
9789 - "source_ip" is the IP address of the client which initiated the connection.
9790 - "source_port" is the TCP port of the client which initiated the connection.
9791 - "destination_ip" is the IP address the client connected to.
9792 - "destination_port" is the TCP port the client connected to.
9793 - "frontend_name" is the name of the frontend (or listener) which received
9794 and processed the connection.
9795 - "mode is the mode the frontend is operating (TCP or HTTP).
9796
Willy Tarreauceb24bc2010-11-09 12:46:41 +01009797In case of a UNIX socket, the source and destination addresses are marked as
9798"unix:" and the ports reflect the internal ID of the socket which accepted the
9799connection (the same ID as reported in the stats).
9800
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009801It is advised not to use this deprecated format for newer installations as it
9802will eventually disappear.
9803
9804
Willy Tarreauc57f0e22009-05-10 13:12:33 +020098058.2.2. TCP log format
9806---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009807
9808The TCP format is used when "option tcplog" is specified in the frontend, and
9809is the recommended format for pure TCP proxies. It provides a lot of precious
9810information for troubleshooting. Since this format includes timers and byte
9811counts, the log is normally emitted at the end of the session. It can be
9812emitted earlier if "option logasap" is specified, which makes sense in most
9813environments with long sessions such as remote terminals. Sessions which match
9814the "monitor" rules are never logged. It is also possible not to emit logs for
9815sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02009816specifying "option dontlognull" in the frontend. Successful connections will
9817not be logged if "option dontlog-normal" is specified in the frontend. A few
9818fields may slightly vary depending on some configuration options, those are
9819marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009820
9821 Example :
9822 frontend fnt
9823 mode tcp
9824 option tcplog
9825 log global
9826 default_backend bck
9827
9828 backend bck
9829 server srv1 127.0.0.1:8000
9830
9831 >>> Feb 6 12:12:56 localhost \
9832 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
9833 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
9834
9835 Field Format Extract from the example above
9836 1 process_name '[' pid ']:' haproxy[14387]:
9837 2 client_ip ':' client_port 10.0.1.2:33313
9838 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
9839 4 frontend_name fnt
9840 5 backend_name '/' server_name bck/srv1
9841 6 Tw '/' Tc '/' Tt* 0/0/5007
9842 7 bytes_read* 212
9843 8 termination_state --
9844 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
9845 10 srv_queue '/' backend_queue 0/0
9846
9847Detailed fields description :
9848 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +01009849 connection to haproxy. If the connection was accepted on a UNIX socket
9850 instead, the IP address would be replaced with the word "unix". Note that
9851 when the connection is accepted on a socket configured with "accept-proxy"
9852 and the PROXY protocol is correctly used, then the logs will reflect the
9853 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009854
9855 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +01009856 If the connection was accepted on a UNIX socket instead, the port would be
9857 replaced with the ID of the accepting socket, which is also reported in the
9858 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009859
9860 - "accept_date" is the exact date when the connection was received by haproxy
9861 (which might be very slightly different from the date observed on the
9862 network if there was some queuing in the system's backlog). This is usually
9863 the same date which may appear in any upstream firewall's log.
9864
9865 - "frontend_name" is the name of the frontend (or listener) which received
9866 and processed the connection.
9867
9868 - "backend_name" is the name of the backend (or listener) which was selected
9869 to manage the connection to the server. This will be the same as the
9870 frontend if no switching rule has been applied, which is common for TCP
9871 applications.
9872
9873 - "server_name" is the name of the last server to which the connection was
9874 sent, which might differ from the first one if there were connection errors
9875 and a redispatch occurred. Note that this server belongs to the backend
9876 which processed the request. If the connection was aborted before reaching
9877 a server, "<NOSRV>" is indicated instead of a server name.
9878
9879 - "Tw" is the total time in milliseconds spent waiting in the various queues.
9880 It can be "-1" if the connection was aborted before reaching the queue.
9881 See "Timers" below for more details.
9882
9883 - "Tc" is the total time in milliseconds spent waiting for the connection to
9884 establish to the final server, including retries. It can be "-1" if the
9885 connection was aborted before a connection could be established. See
9886 "Timers" below for more details.
9887
9888 - "Tt" is the total time in milliseconds elapsed between the accept and the
9889 last close. It covers all possible processings. There is one exception, if
9890 "option logasap" was specified, then the time counting stops at the moment
9891 the log is emitted. In this case, a '+' sign is prepended before the value,
9892 indicating that the final one will be larger. See "Timers" below for more
9893 details.
9894
9895 - "bytes_read" is the total number of bytes transmitted from the server to
9896 the client when the log is emitted. If "option logasap" is specified, the
9897 this value will be prefixed with a '+' sign indicating that the final one
9898 may be larger. Please note that this value is a 64-bit counter, so log
9899 analysis tools must be able to handle it without overflowing.
9900
9901 - "termination_state" is the condition the session was in when the session
9902 ended. This indicates the session state, which side caused the end of
9903 session to happen, and for what reason (timeout, error, ...). The normal
9904 flags should be "--", indicating the session was closed by either end with
9905 no data remaining in buffers. See below "Session state at disconnection"
9906 for more details.
9907
9908 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009909 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009910 limits have been reached. For instance, if actconn is close to 512 when
9911 multiple connection errors occur, chances are high that the system limits
9912 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009913 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009914
9915 - "feconn" is the total number of concurrent connections on the frontend when
9916 the session was logged. It is useful to estimate the amount of resource
9917 required to sustain high loads, and to detect when the frontend's "maxconn"
9918 has been reached. Most often when this value increases by huge jumps, it is
9919 because there is congestion on the backend servers, but sometimes it can be
9920 caused by a denial of service attack.
9921
9922 - "beconn" is the total number of concurrent connections handled by the
9923 backend when the session was logged. It includes the total number of
9924 concurrent connections active on servers as well as the number of
9925 connections pending in queues. It is useful to estimate the amount of
9926 additional servers needed to support high loads for a given application.
9927 Most often when this value increases by huge jumps, it is because there is
9928 congestion on the backend servers, but sometimes it can be caused by a
9929 denial of service attack.
9930
9931 - "srv_conn" is the total number of concurrent connections still active on
9932 the server when the session was logged. It can never exceed the server's
9933 configured "maxconn" parameter. If this value is very often close or equal
9934 to the server's "maxconn", it means that traffic regulation is involved a
9935 lot, meaning that either the server's maxconn value is too low, or that
9936 there aren't enough servers to process the load with an optimal response
9937 time. When only one of the server's "srv_conn" is high, it usually means
9938 that this server has some trouble causing the connections to take longer to
9939 be processed than on other servers.
9940
9941 - "retries" is the number of connection retries experienced by this session
9942 when trying to connect to the server. It must normally be zero, unless a
9943 server is being stopped at the same moment the connection was attempted.
9944 Frequent retries generally indicate either a network problem between
9945 haproxy and the server, or a misconfigured system backlog on the server
9946 preventing new connections from being queued. This field may optionally be
9947 prefixed with a '+' sign, indicating that the session has experienced a
9948 redispatch after the maximal retry count has been reached on the initial
9949 server. In this case, the server name appearing in the log is the one the
9950 connection was redispatched to, and not the first one, though both may
9951 sometimes be the same in case of hashing for instance. So as a general rule
9952 of thumb, when a '+' is present in front of the retry count, this count
9953 should not be attributed to the logged server.
9954
9955 - "srv_queue" is the total number of requests which were processed before
9956 this one in the server queue. It is zero when the request has not gone
9957 through the server queue. It makes it possible to estimate the approximate
9958 server's response time by dividing the time spent in queue by the number of
9959 requests in the queue. It is worth noting that if a session experiences a
9960 redispatch and passes through two server queues, their positions will be
9961 cumulated. A request should not pass through both the server queue and the
9962 backend queue unless a redispatch occurs.
9963
9964 - "backend_queue" is the total number of requests which were processed before
9965 this one in the backend's global queue. It is zero when the request has not
9966 gone through the global queue. It makes it possible to estimate the average
9967 queue length, which easily translates into a number of missing servers when
9968 divided by a server's "maxconn" parameter. It is worth noting that if a
9969 session experiences a redispatch, it may pass twice in the backend's queue,
9970 and then both positions will be cumulated. A request should not pass
9971 through both the server queue and the backend queue unless a redispatch
9972 occurs.
9973
9974
Willy Tarreauc57f0e22009-05-10 13:12:33 +020099758.2.3. HTTP log format
9976----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009977
9978The HTTP format is the most complete and the best suited for HTTP proxies. It
9979is enabled by when "option httplog" is specified in the frontend. It provides
9980the same level of information as the TCP format with additional features which
9981are specific to the HTTP protocol. Just like the TCP format, the log is usually
9982emitted at the end of the session, unless "option logasap" is specified, which
9983generally only makes sense for download sites. A session which matches the
9984"monitor" rules will never logged. It is also possible not to log sessions for
9985which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02009986frontend. Successful connections will not be logged if "option dontlog-normal"
9987is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +01009988
9989Most fields are shared with the TCP log, some being different. A few fields may
9990slightly vary depending on some configuration options. Those ones are marked
9991with a star ('*') after the field name below.
9992
9993 Example :
9994 frontend http-in
9995 mode http
9996 option httplog
9997 log global
9998 default_backend bck
9999
10000 backend static
10001 server srv1 127.0.0.1:8000
10002
10003 >>> Feb 6 12:14:14 localhost \
10004 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
10005 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 +010010006 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010007
10008 Field Format Extract from the example above
10009 1 process_name '[' pid ']:' haproxy[14389]:
10010 2 client_ip ':' client_port 10.0.1.2:33317
10011 3 '[' accept_date ']' [06/Feb/2009:12:14:14.655]
10012 4 frontend_name http-in
10013 5 backend_name '/' server_name static/srv1
10014 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt* 10/0/30/69/109
10015 7 status_code 200
10016 8 bytes_read* 2750
10017 9 captured_request_cookie -
10018 10 captured_response_cookie -
10019 11 termination_state ----
10020 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
10021 13 srv_queue '/' backend_queue 0/0
10022 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
10023 15 '{' captured_response_headers* '}' {}
10024 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +010010025
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010026
10027Detailed fields description :
10028 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010010029 connection to haproxy. If the connection was accepted on a UNIX socket
10030 instead, the IP address would be replaced with the word "unix". Note that
10031 when the connection is accepted on a socket configured with "accept-proxy"
10032 and the PROXY protocol is correctly used, then the logs will reflect the
10033 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010034
10035 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010010036 If the connection was accepted on a UNIX socket instead, the port would be
10037 replaced with the ID of the accepting socket, which is also reported in the
10038 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010039
10040 - "accept_date" is the exact date when the TCP connection was received by
10041 haproxy (which might be very slightly different from the date observed on
10042 the network if there was some queuing in the system's backlog). This is
10043 usually the same date which may appear in any upstream firewall's log. This
10044 does not depend on the fact that the client has sent the request or not.
10045
10046 - "frontend_name" is the name of the frontend (or listener) which received
10047 and processed the connection.
10048
10049 - "backend_name" is the name of the backend (or listener) which was selected
10050 to manage the connection to the server. This will be the same as the
10051 frontend if no switching rule has been applied.
10052
10053 - "server_name" is the name of the last server to which the connection was
10054 sent, which might differ from the first one if there were connection errors
10055 and a redispatch occurred. Note that this server belongs to the backend
10056 which processed the request. If the request was aborted before reaching a
10057 server, "<NOSRV>" is indicated instead of a server name. If the request was
10058 intercepted by the stats subsystem, "<STATS>" is indicated instead.
10059
10060 - "Tq" is the total time in milliseconds spent waiting for the client to send
10061 a full HTTP request, not counting data. It can be "-1" if the connection
10062 was aborted before a complete request could be received. It should always
10063 be very small because a request generally fits in one single packet. Large
10064 times here generally indicate network trouble between the client and
10065 haproxy. See "Timers" below for more details.
10066
10067 - "Tw" is the total time in milliseconds spent waiting in the various queues.
10068 It can be "-1" if the connection was aborted before reaching the queue.
10069 See "Timers" below for more details.
10070
10071 - "Tc" is the total time in milliseconds spent waiting for the connection to
10072 establish to the final server, including retries. It can be "-1" if the
10073 request was aborted before a connection could be established. See "Timers"
10074 below for more details.
10075
10076 - "Tr" is the total time in milliseconds spent waiting for the server to send
10077 a full HTTP response, not counting data. It can be "-1" if the request was
10078 aborted before a complete response could be received. It generally matches
10079 the server's processing time for the request, though it may be altered by
10080 the amount of data sent by the client to the server. Large times here on
10081 "GET" requests generally indicate an overloaded server. See "Timers" below
10082 for more details.
10083
10084 - "Tt" is the total time in milliseconds elapsed between the accept and the
10085 last close. It covers all possible processings. There is one exception, if
10086 "option logasap" was specified, then the time counting stops at the moment
10087 the log is emitted. In this case, a '+' sign is prepended before the value,
10088 indicating that the final one will be larger. See "Timers" below for more
10089 details.
10090
10091 - "status_code" is the HTTP status code returned to the client. This status
10092 is generally set by the server, but it might also be set by haproxy when
10093 the server cannot be reached or when its response is blocked by haproxy.
10094
10095 - "bytes_read" is the total number of bytes transmitted to the client when
10096 the log is emitted. This does include HTTP headers. If "option logasap" is
10097 specified, the this value will be prefixed with a '+' sign indicating that
10098 the final one may be larger. Please note that this value is a 64-bit
10099 counter, so log analysis tools must be able to handle it without
10100 overflowing.
10101
10102 - "captured_request_cookie" is an optional "name=value" entry indicating that
10103 the client had this cookie in the request. The cookie name and its maximum
10104 length are defined by the "capture cookie" statement in the frontend
10105 configuration. The field is a single dash ('-') when the option is not
10106 set. Only one cookie may be captured, it is generally used to track session
10107 ID exchanges between a client and a server to detect session crossing
10108 between clients due to application bugs. For more details, please consult
10109 the section "Capturing HTTP headers and cookies" below.
10110
10111 - "captured_response_cookie" is an optional "name=value" entry indicating
10112 that the server has returned a cookie with its response. The cookie name
10113 and its maximum length are defined by the "capture cookie" statement in the
10114 frontend configuration. The field is a single dash ('-') when the option is
10115 not set. Only one cookie may be captured, it is generally used to track
10116 session ID exchanges between a client and a server to detect session
10117 crossing between clients due to application bugs. For more details, please
10118 consult the section "Capturing HTTP headers and cookies" below.
10119
10120 - "termination_state" is the condition the session was in when the session
10121 ended. This indicates the session state, which side caused the end of
10122 session to happen, for what reason (timeout, error, ...), just like in TCP
10123 logs, and information about persistence operations on cookies in the last
10124 two characters. The normal flags should begin with "--", indicating the
10125 session was closed by either end with no data remaining in buffers. See
10126 below "Session state at disconnection" for more details.
10127
10128 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010129 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010130 limits have been reached. For instance, if actconn is close to 512 or 1024
10131 when multiple connection errors occur, chances are high that the system
10132 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010133 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010134 system.
10135
10136 - "feconn" is the total number of concurrent connections on the frontend when
10137 the session was logged. It is useful to estimate the amount of resource
10138 required to sustain high loads, and to detect when the frontend's "maxconn"
10139 has been reached. Most often when this value increases by huge jumps, it is
10140 because there is congestion on the backend servers, but sometimes it can be
10141 caused by a denial of service attack.
10142
10143 - "beconn" is the total number of concurrent connections handled by the
10144 backend when the session was logged. It includes the total number of
10145 concurrent connections active on servers as well as the number of
10146 connections pending in queues. It is useful to estimate the amount of
10147 additional servers needed to support high loads for a given application.
10148 Most often when this value increases by huge jumps, it is because there is
10149 congestion on the backend servers, but sometimes it can be caused by a
10150 denial of service attack.
10151
10152 - "srv_conn" is the total number of concurrent connections still active on
10153 the server when the session was logged. It can never exceed the server's
10154 configured "maxconn" parameter. If this value is very often close or equal
10155 to the server's "maxconn", it means that traffic regulation is involved a
10156 lot, meaning that either the server's maxconn value is too low, or that
10157 there aren't enough servers to process the load with an optimal response
10158 time. When only one of the server's "srv_conn" is high, it usually means
10159 that this server has some trouble causing the requests to take longer to be
10160 processed than on other servers.
10161
10162 - "retries" is the number of connection retries experienced by this session
10163 when trying to connect to the server. It must normally be zero, unless a
10164 server is being stopped at the same moment the connection was attempted.
10165 Frequent retries generally indicate either a network problem between
10166 haproxy and the server, or a misconfigured system backlog on the server
10167 preventing new connections from being queued. This field may optionally be
10168 prefixed with a '+' sign, indicating that the session has experienced a
10169 redispatch after the maximal retry count has been reached on the initial
10170 server. In this case, the server name appearing in the log is the one the
10171 connection was redispatched to, and not the first one, though both may
10172 sometimes be the same in case of hashing for instance. So as a general rule
10173 of thumb, when a '+' is present in front of the retry count, this count
10174 should not be attributed to the logged server.
10175
10176 - "srv_queue" is the total number of requests which were processed before
10177 this one in the server queue. It is zero when the request has not gone
10178 through the server queue. It makes it possible to estimate the approximate
10179 server's response time by dividing the time spent in queue by the number of
10180 requests in the queue. It is worth noting that if a session experiences a
10181 redispatch and passes through two server queues, their positions will be
10182 cumulated. A request should not pass through both the server queue and the
10183 backend queue unless a redispatch occurs.
10184
10185 - "backend_queue" is the total number of requests which were processed before
10186 this one in the backend's global queue. It is zero when the request has not
10187 gone through the global queue. It makes it possible to estimate the average
10188 queue length, which easily translates into a number of missing servers when
10189 divided by a server's "maxconn" parameter. It is worth noting that if a
10190 session experiences a redispatch, it may pass twice in the backend's queue,
10191 and then both positions will be cumulated. A request should not pass
10192 through both the server queue and the backend queue unless a redispatch
10193 occurs.
10194
10195 - "captured_request_headers" is a list of headers captured in the request due
10196 to the presence of the "capture request header" statement in the frontend.
10197 Multiple headers can be captured, they will be delimited by a vertical bar
10198 ('|'). When no capture is enabled, the braces do not appear, causing a
10199 shift of remaining fields. It is important to note that this field may
10200 contain spaces, and that using it requires a smarter log parser than when
10201 it's not used. Please consult the section "Capturing HTTP headers and
10202 cookies" below for more details.
10203
10204 - "captured_response_headers" is a list of headers captured in the response
10205 due to the presence of the "capture response header" statement in the
10206 frontend. Multiple headers can be captured, they will be delimited by a
10207 vertical bar ('|'). When no capture is enabled, the braces do not appear,
10208 causing a shift of remaining fields. It is important to note that this
10209 field may contain spaces, and that using it requires a smarter log parser
10210 than when it's not used. Please consult the section "Capturing HTTP headers
10211 and cookies" below for more details.
10212
10213 - "http_request" is the complete HTTP request line, including the method,
10214 request and HTTP version string. Non-printable characters are encoded (see
10215 below the section "Non-printable characters"). This is always the last
10216 field, and it is always delimited by quotes and is the only one which can
10217 contain quotes. If new fields are added to the log format, they will be
10218 added before this field. This field might be truncated if the request is
10219 huge and does not fit in the standard syslog buffer (1024 characters). This
10220 is the reason why this field must always remain the last one.
10221
10222
Cyril Bontédc4d9032012-04-08 21:57:39 +0200102238.2.4. Custom log format
10224------------------------
William Lallemand48940402012-01-30 16:47:22 +010010225
Willy Tarreau2beef582012-12-20 17:22:52 +010010226The directive log-format allows you to customize the logs in http mode and tcp
William Lallemandbddd4fd2012-02-27 11:23:10 +010010227mode. It takes a string as argument.
William Lallemand48940402012-01-30 16:47:22 +010010228
10229HAproxy understands some log format variables. % precedes log format variables.
10230Variables can take arguments using braces ('{}'), and multiple arguments are
10231separated by commas within the braces. Flags may be added or removed by
10232prefixing them with a '+' or '-' sign.
10233
10234Special variable "%o" may be used to propagate its flags to all other
10235variables on the same format string. This is particularly handy with quoted
10236string formats ("Q").
10237
Willy Tarreauc8368452012-12-21 00:09:23 +010010238If a variable is named between square brackets ('[' .. ']') then it is used
10239as a pattern extraction rule (see section 7.8). This it useful to add some
10240less common information such as the client's SSL certificate's DN, or to log
10241the key that would be used to store an entry into a stick table.
10242
William Lallemand48940402012-01-30 16:47:22 +010010243Note: spaces must be escaped. A space character is considered as a separator.
10244HAproxy will automatically merge consecutive separators.
10245
10246Flags are :
10247 * Q: quote a string
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010248 * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid)
William Lallemand48940402012-01-30 16:47:22 +010010249
10250 Example:
10251
10252 log-format %T\ %t\ Some\ Text
10253 log-format %{+Q}o\ %t\ %s\ %{-Q}r
10254
10255At the moment, the default HTTP format is defined this way :
10256
Willy Tarreau2beef582012-12-20 17:22:52 +010010257 log-format %ci:%cp\ [%t]\ %ft\ %b/%s\ %Tq/%Tw/%Tc/%Tr/%Tt\ %ST\ %B\ %CC\ \
10258 %CS\ %tsc\ %ac/%fc/%bc/%sc/%rc\ %sq/%bq\ %hr\ %hs\ %{+Q}r
William Lallemand48940402012-01-30 16:47:22 +010010259
William Lallemandbddd4fd2012-02-27 11:23:10 +010010260the default CLF format is defined this way :
William Lallemand48940402012-01-30 16:47:22 +010010261
Willy Tarreau2beef582012-12-20 17:22:52 +010010262 log-format %{+Q}o\ %{-Q}ci\ -\ -\ [%T]\ %r\ %ST\ %B\ \"\"\ \"\"\ %cp\ \
Willy Tarreau773d65f2012-10-12 14:56:11 +020010263 %ms\ %ft\ %b\ %s\ \%Tq\ %Tw\ %Tc\ %Tr\ %Tt\ %tsc\ %ac\ %fc\ \
Willy Tarreau2beef582012-12-20 17:22:52 +010010264 %bc\ %sc\ %rc\ %sq\ %bq\ %CC\ %CS\ \%hrl\ %hsl
William Lallemand48940402012-01-30 16:47:22 +010010265
William Lallemandbddd4fd2012-02-27 11:23:10 +010010266and the default TCP format is defined this way :
10267
Willy Tarreau2beef582012-12-20 17:22:52 +010010268 log-format %ci:%cp\ [%t]\ %ft\ %b/%s\ %Tw/%Tc/%Tt\ %B\ %ts\ \
William Lallemandbddd4fd2012-02-27 11:23:10 +010010269 %ac/%fc/%bc/%sc/%rc\ %sq/%bq
10270
William Lallemand48940402012-01-30 16:47:22 +010010271Please refer to the table below for currently defined variables :
10272
William Lallemandbddd4fd2012-02-27 11:23:10 +010010273 +---+------+-----------------------------------------------+-------------+
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010274 | R | var | field name (8.2.2 and 8.2.3 for description) | type |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010275 +---+------+-----------------------------------------------+-------------+
10276 | | %o | special variable, apply flags on all next var | |
10277 +---+------+-----------------------------------------------+-------------+
Willy Tarreau2beef582012-12-20 17:22:52 +010010278 | | %B | bytes_read (from server to client) | numeric |
10279 | H | %CC | captured_request_cookie | string |
10280 | H | %CS | captured_response_cookie | string |
William Lallemand5f232402012-04-05 18:02:55 +020010281 | | %H | hostname | string |
William Lallemanda73203e2012-03-12 12:48:57 +010010282 | | %ID | unique-id | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010010283 | H | %ST | status_code | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020010284 | | %T | gmt_date_time | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010285 | | %Tc | Tc | numeric |
Yuxans Yao4e25b012012-10-19 10:36:09 +080010286 | | %Tl | local_date_time | date |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010287 | H | %Tq | Tq | numeric |
10288 | H | %Tr | Tr | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020010289 | | %Ts | timestamp | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010290 | | %Tt | Tt | numeric |
10291 | | %Tw | Tw | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010010292 | | %U | bytes_uploaded (from client to server) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010293 | | %ac | actconn | numeric |
10294 | | %b | backend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010010295 | | %bc | beconn (backend concurrent connections) | numeric |
10296 | | %bi | backend_source_ip (connecting address) | IP |
10297 | | %bp | backend_source_port (connecting address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010298 | | %bq | backend_queue | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010010299 | | %ci | client_ip (accepted address) | IP |
10300 | | %cp | client_port (accepted address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010301 | | %f | frontend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010010302 | | %fc | feconn (frontend concurrent connections) | numeric |
10303 | | %fi | frontend_ip (accepting address) | IP |
10304 | | %fp | frontend_port (accepting address) | numeric |
Willy Tarreau773d65f2012-10-12 14:56:11 +020010305 | | %ft | frontend_name_transport ('~' suffix for SSL) | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010306 | H | %hr | captured_request_headers default style | string |
10307 | H | %hrl | captured_request_headers CLF style | string list |
10308 | H | %hs | captured_response_headers default style | string |
10309 | H | %hsl | captured_response_headers CLF style | string list |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010310 | | %ms | accept date milliseconds | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020010311 | | %pid | PID | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010312 | H | %r | http_request | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010313 | | %rc | retries | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010010314 | H | %rt | http_request_counter | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010315 | | %s | server_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010010316 | | %sc | srv_conn (server concurrent connections) | numeric |
10317 | | %si | server_IP (target address) | IP |
10318 | | %sp | server_port (target address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010319 | | %sq | srv_queue | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010320 | S | %sslc| ssl_ciphers (ex: AES-SHA) | string |
10321 | S | %sslv| ssl_version (ex: TLSv1) | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010010322 | | %t | date_time (with millisecond resolution) | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010323 | | %ts | termination_state | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010324 | H | %tsc | termination_state with cookie status | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010010325 +---+------+-----------------------------------------------+-------------+
William Lallemand48940402012-01-30 16:47:22 +010010326
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020010327 R = Restrictions : H = mode http only ; S = SSL only
William Lallemand48940402012-01-30 16:47:22 +010010328
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010010329
103308.2.5. Error log format
10331-----------------------
10332
10333When an incoming connection fails due to an SSL handshake or an invalid PROXY
10334protocol header, haproxy will log the event using a shorter, fixed line format.
10335By default, logs are emitted at the LOG_INFO level, unless the option
10336"log-separate-errors" is set in the backend, in which case the LOG_ERR level
10337will be used. Connections on which no data are exchanged (eg: probes) are not
10338logged if the "dontlognull" option is set.
10339
10340The format looks like this :
10341
10342 >>> Dec 3 18:27:14 localhost \
10343 haproxy[6103]: 127.0.0.1:56059 [03/Dec/2012:17:35:10.380] frt/f1: \
10344 Connection error during SSL handshake
10345
10346 Field Format Extract from the example above
10347 1 process_name '[' pid ']:' haproxy[6103]:
10348 2 client_ip ':' client_port 127.0.0.1:56059
10349 3 '[' accept_date ']' [03/Dec/2012:17:35:10.380]
10350 4 frontend_name "/" bind_name ":" frt/f1:
10351 5 message Connection error during SSL handshake
10352
10353These fields just provide minimal information to help debugging connection
10354failures.
10355
10356
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200103578.3. Advanced logging options
10358-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010359
10360Some advanced logging options are often looked for but are not easy to find out
10361just by looking at the various options. Here is an entry point for the few
10362options which can enable better logging. Please refer to the keywords reference
10363for more information about their usage.
10364
10365
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200103668.3.1. Disabling logging of external tests
10367------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010368
10369It is quite common to have some monitoring tools perform health checks on
10370haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
10371commercial load-balancer, and sometimes it will simply be a more complete
10372monitoring system such as Nagios. When the tests are very frequent, users often
10373ask how to disable logging for those checks. There are three possibilities :
10374
10375 - if connections come from everywhere and are just TCP probes, it is often
10376 desired to simply disable logging of connections without data exchange, by
10377 setting "option dontlognull" in the frontend. It also disables logging of
10378 port scans, which may or may not be desired.
10379
10380 - if the connection come from a known source network, use "monitor-net" to
10381 declare this network as monitoring only. Any host in this network will then
10382 only be able to perform health checks, and their requests will not be
10383 logged. This is generally appropriate to designate a list of equipments
10384 such as other load-balancers.
10385
10386 - if the tests are performed on a known URI, use "monitor-uri" to declare
10387 this URI as dedicated to monitoring. Any host sending this request will
10388 only get the result of a health-check, and the request will not be logged.
10389
10390
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200103918.3.2. Logging before waiting for the session to terminate
10392----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010393
10394The problem with logging at end of connection is that you have no clue about
10395what is happening during very long sessions, such as remote terminal sessions
10396or large file downloads. This problem can be worked around by specifying
10397"option logasap" in the frontend. Haproxy will then log as soon as possible,
10398just before data transfer begins. This means that in case of TCP, it will still
10399log the connection status to the server, and in case of HTTP, it will log just
10400after processing the server headers. In this case, the number of bytes reported
10401is the number of header bytes sent to the client. In order to avoid confusion
10402with normal logs, the total time field and the number of bytes are prefixed
10403with a '+' sign which means that real numbers are certainly larger.
10404
10405
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200104068.3.3. Raising log level upon errors
10407------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020010408
10409Sometimes it is more convenient to separate normal traffic from errors logs,
10410for instance in order to ease error monitoring from log files. When the option
10411"log-separate-errors" is used, connections which experience errors, timeouts,
10412retries, redispatches or HTTP status codes 5xx will see their syslog level
10413raised from "info" to "err". This will help a syslog daemon store the log in
10414a separate file. It is very important to keep the errors in the normal traffic
10415file too, so that log ordering is not altered. You should also be careful if
10416you already have configured your syslog daemon to store all logs higher than
10417"notice" in an "admin" file, because the "err" level is higher than "notice".
10418
10419
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200104208.3.4. Disabling logging of successful connections
10421--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020010422
10423Although this may sound strange at first, some large sites have to deal with
10424multiple thousands of logs per second and are experiencing difficulties keeping
10425them intact for a long time or detecting errors within them. If the option
10426"dontlog-normal" is set on the frontend, all normal connections will not be
10427logged. In this regard, a normal connection is defined as one without any
10428error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
10429and a response with a status 5xx is not considered normal and will be logged
10430too. Of course, doing is is really discouraged as it will remove most of the
10431useful information from the logs. Do this only if you have no other
10432alternative.
10433
10434
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200104358.4. Timing events
10436------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010437
10438Timers provide a great help in troubleshooting network problems. All values are
10439reported in milliseconds (ms). These timers should be used in conjunction with
10440the session termination flags. In TCP mode with "option tcplog" set on the
10441frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
10442mode, 5 control points are reported under the form "Tq/Tw/Tc/Tr/Tt" :
10443
10444 - Tq: total time to get the client request (HTTP mode only). It's the time
10445 elapsed between the moment the client connection was accepted and the
10446 moment the proxy received the last HTTP header. The value "-1" indicates
10447 that the end of headers (empty line) has never been seen. This happens when
10448 the client closes prematurely or times out.
10449
10450 - Tw: total time spent in the queues waiting for a connection slot. It
10451 accounts for backend queue as well as the server queues, and depends on the
10452 queue size, and the time needed for the server to complete previous
10453 requests. The value "-1" means that the request was killed before reaching
10454 the queue, which is generally what happens with invalid or denied requests.
10455
10456 - Tc: total time to establish the TCP connection to the server. It's the time
10457 elapsed between the moment the proxy sent the connection request, and the
10458 moment it was acknowledged by the server, or between the TCP SYN packet and
10459 the matching SYN/ACK packet in return. The value "-1" means that the
10460 connection never established.
10461
10462 - Tr: server response time (HTTP mode only). It's the time elapsed between
10463 the moment the TCP connection was established to the server and the moment
10464 the server sent its complete response headers. It purely shows its request
10465 processing time, without the network overhead due to the data transmission.
10466 It is worth noting that when the client has data to send to the server, for
10467 instance during a POST request, the time already runs, and this can distort
10468 apparent response time. For this reason, it's generally wise not to trust
10469 too much this field for POST requests initiated from clients behind an
10470 untrusted network. A value of "-1" here means that the last the response
10471 header (empty line) was never seen, most likely because the server timeout
10472 stroke before the server managed to process the request.
10473
10474 - Tt: total session duration time, between the moment the proxy accepted it
10475 and the moment both ends were closed. The exception is when the "logasap"
10476 option is specified. In this case, it only equals (Tq+Tw+Tc+Tr), and is
10477 prefixed with a '+' sign. From this field, we can deduce "Td", the data
10478 transmission time, by substracting other timers when valid :
10479
10480 Td = Tt - (Tq + Tw + Tc + Tr)
10481
10482 Timers with "-1" values have to be excluded from this equation. In TCP
10483 mode, "Tq" and "Tr" have to be excluded too. Note that "Tt" can never be
10484 negative.
10485
10486These timers provide precious indications on trouble causes. Since the TCP
10487protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
10488that timers close to multiples of 3s are nearly always related to lost packets
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010489due to network problems (wires, negotiation, congestion). Moreover, if "Tt" is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010490close to a timeout value specified in the configuration, it often means that a
10491session has been aborted on timeout.
10492
10493Most common cases :
10494
10495 - If "Tq" is close to 3000, a packet has probably been lost between the
10496 client and the proxy. This is very rare on local networks but might happen
10497 when clients are on far remote networks and send large requests. It may
10498 happen that values larger than usual appear here without any network cause.
10499 Sometimes, during an attack or just after a resource starvation has ended,
10500 haproxy may accept thousands of connections in a few milliseconds. The time
10501 spent accepting these connections will inevitably slightly delay processing
10502 of other connections, and it can happen that request times in the order of
10503 a few tens of milliseconds are measured after a few thousands of new
Patrick Mezard105faca2010-06-12 17:02:46 +020010504 connections have been accepted at once. Setting "option http-server-close"
10505 may display larger request times since "Tq" also measures the time spent
10506 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010507
10508 - If "Tc" is close to 3000, a packet has probably been lost between the
10509 server and the proxy during the server connection phase. This value should
10510 always be very low, such as 1 ms on local networks and less than a few tens
10511 of ms on remote networks.
10512
Willy Tarreau55165fe2009-05-10 12:02:55 +020010513 - If "Tr" is nearly always lower than 3000 except some rare values which seem
10514 to be the average majored by 3000, there are probably some packets lost
10515 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010516
10517 - If "Tt" is large even for small byte counts, it generally is because
10518 neither the client nor the server decides to close the connection, for
10519 instance because both have agreed on a keep-alive connection mode. In order
10520 to solve this issue, it will be needed to specify "option httpclose" on
10521 either the frontend or the backend. If the problem persists, it means that
10522 the server ignores the "close" connection mode and expects the client to
10523 close. Then it will be required to use "option forceclose". Having the
10524 smallest possible 'Tt' is important when connection regulation is used with
10525 the "maxconn" option on the servers, since no new connection will be sent
10526 to the server until another one is released.
10527
10528Other noticeable HTTP log cases ('xx' means any value to be ignored) :
10529
10530 Tq/Tw/Tc/Tr/+Tt The "option logasap" is present on the frontend and the log
10531 was emitted before the data phase. All the timers are valid
10532 except "Tt" which is shorter than reality.
10533
10534 -1/xx/xx/xx/Tt The client was not able to send a complete request in time
10535 or it aborted too early. Check the session termination flags
10536 then "timeout http-request" and "timeout client" settings.
10537
10538 Tq/-1/xx/xx/Tt It was not possible to process the request, maybe because
10539 servers were out of order, because the request was invalid
10540 or forbidden by ACL rules. Check the session termination
10541 flags.
10542
10543 Tq/Tw/-1/xx/Tt The connection could not establish on the server. Either it
10544 actively refused it or it timed out after Tt-(Tq+Tw) ms.
10545 Check the session termination flags, then check the
10546 "timeout connect" setting. Note that the tarpit action might
10547 return similar-looking patterns, with "Tw" equal to the time
10548 the client connection was maintained open.
10549
10550 Tq/Tw/Tc/-1/Tt The server has accepted the connection but did not return
10551 a complete response in time, or it closed its connexion
10552 unexpectedly after Tt-(Tq+Tw+Tc) ms. Check the session
10553 termination flags, then check the "timeout server" setting.
10554
10555
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200105568.5. Session state at disconnection
10557-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010558
10559TCP and HTTP logs provide a session termination indicator in the
10560"termination_state" field, just before the number of active connections. It is
105612-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
10562each of which has a special meaning :
10563
10564 - On the first character, a code reporting the first event which caused the
10565 session to terminate :
10566
10567 C : the TCP session was unexpectedly aborted by the client.
10568
10569 S : the TCP session was unexpectedly aborted by the server, or the
10570 server explicitly refused it.
10571
10572 P : the session was prematurely aborted by the proxy, because of a
10573 connection limit enforcement, because a DENY filter was matched,
10574 because of a security check which detected and blocked a dangerous
10575 error in server response which might have caused information leak
10576 (eg: cacheable cookie), or because the response was processed by
10577 the proxy (redirect, stats, etc...).
10578
10579 R : a resource on the proxy has been exhausted (memory, sockets, source
10580 ports, ...). Usually, this appears during the connection phase, and
10581 system logs should contain a copy of the precise error. If this
10582 happens, it must be considered as a very serious anomaly which
10583 should be fixed as soon as possible by any means.
10584
10585 I : an internal error was identified by the proxy during a self-check.
10586 This should NEVER happen, and you are encouraged to report any log
10587 containing this, because this would almost certainly be a bug. It
10588 would be wise to preventively restart the process after such an
10589 event too, in case it would be caused by memory corruption.
10590
Simon Horman752dc4a2011-06-21 14:34:59 +090010591 D : the session was killed by haproxy because the server was detected
10592 as down and was configured to kill all connections when going down.
10593
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070010594 U : the session was killed by haproxy on this backup server because an
10595 active server was detected as up and was configured to kill all
10596 backup connections when going up.
10597
Willy Tarreaua2a64e92011-09-07 23:01:56 +020010598 K : the session was actively killed by an admin operating on haproxy.
10599
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010600 c : the client-side timeout expired while waiting for the client to
10601 send or receive data.
10602
10603 s : the server-side timeout expired while waiting for the server to
10604 send or receive data.
10605
10606 - : normal session completion, both the client and the server closed
10607 with nothing left in the buffers.
10608
10609 - on the second character, the TCP or HTTP session state when it was closed :
10610
Willy Tarreauf7b30a92010-12-06 22:59:17 +010010611 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010612 (HTTP mode only). Nothing was sent to any server.
10613
10614 Q : the proxy was waiting in the QUEUE for a connection slot. This can
10615 only happen when servers have a 'maxconn' parameter set. It can
10616 also happen in the global queue after a redispatch consecutive to
10617 a failed attempt to connect to a dying server. If no redispatch is
10618 reported, then no connection attempt was made to any server.
10619
10620 C : the proxy was waiting for the CONNECTION to establish on the
10621 server. The server might at most have noticed a connection attempt.
10622
10623 H : the proxy was waiting for complete, valid response HEADERS from the
10624 server (HTTP only).
10625
10626 D : the session was in the DATA phase.
10627
10628 L : the proxy was still transmitting LAST data to the client while the
10629 server had already finished. This one is very rare as it can only
10630 happen when the client dies while receiving the last packets.
10631
10632 T : the request was tarpitted. It has been held open with the client
10633 during the whole "timeout tarpit" duration or until the client
10634 closed, both of which will be reported in the "Tw" timer.
10635
10636 - : normal session completion after end of data transfer.
10637
10638 - the third character tells whether the persistence cookie was provided by
10639 the client (only in HTTP mode) :
10640
10641 N : the client provided NO cookie. This is usually the case for new
10642 visitors, so counting the number of occurrences of this flag in the
10643 logs generally indicate a valid trend for the site frequentation.
10644
10645 I : the client provided an INVALID cookie matching no known server.
10646 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +020010647 cookies between HTTP/HTTPS sites, persistence conditionally
10648 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010649
10650 D : the client provided a cookie designating a server which was DOWN,
10651 so either "option persist" was used and the client was sent to
10652 this server, or it was not set and the client was redispatched to
10653 another server.
10654
Willy Tarreau996a92c2010-10-13 19:30:47 +020010655 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010656 server.
10657
Willy Tarreau996a92c2010-10-13 19:30:47 +020010658 E : the client provided a valid cookie, but with a last date which was
10659 older than what is allowed by the "maxidle" cookie parameter, so
10660 the cookie is consider EXPIRED and is ignored. The request will be
10661 redispatched just as if there was no cookie.
10662
10663 O : the client provided a valid cookie, but with a first date which was
10664 older than what is allowed by the "maxlife" cookie parameter, so
10665 the cookie is consider too OLD and is ignored. The request will be
10666 redispatched just as if there was no cookie.
10667
Willy Tarreauc89ccb62012-04-05 21:18:22 +020010668 U : a cookie was present but was not used to select the server because
10669 some other server selection mechanism was used instead (typically a
10670 "use-server" rule).
10671
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010672 - : does not apply (no cookie set in configuration).
10673
10674 - the last character reports what operations were performed on the persistence
10675 cookie returned by the server (only in HTTP mode) :
10676
10677 N : NO cookie was provided by the server, and none was inserted either.
10678
10679 I : no cookie was provided by the server, and the proxy INSERTED one.
10680 Note that in "cookie insert" mode, if the server provides a cookie,
10681 it will still be overwritten and reported as "I" here.
10682
Willy Tarreau996a92c2010-10-13 19:30:47 +020010683 U : the proxy UPDATED the last date in the cookie that was presented by
10684 the client. This can only happen in insert mode with "maxidle". It
10685 happens everytime there is activity at a different date than the
10686 date indicated in the cookie. If any other change happens, such as
10687 a redispatch, then the cookie will be marked as inserted instead.
10688
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010689 P : a cookie was PROVIDED by the server and transmitted as-is.
10690
10691 R : the cookie provided by the server was REWRITTEN by the proxy, which
10692 happens in "cookie rewrite" or "cookie prefix" modes.
10693
10694 D : the cookie provided by the server was DELETED by the proxy.
10695
10696 - : does not apply (no cookie set in configuration).
10697
Willy Tarreau996a92c2010-10-13 19:30:47 +020010698The combination of the two first flags gives a lot of information about what
10699was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010700helpful to detect server saturation, network troubles, local system resource
10701starvation, attacks, etc...
10702
10703The most common termination flags combinations are indicated below. They are
10704alphabetically sorted, with the lowercase set just after the upper case for
10705easier finding and understanding.
10706
10707 Flags Reason
10708
10709 -- Normal termination.
10710
10711 CC The client aborted before the connection could be established to the
10712 server. This can happen when haproxy tries to connect to a recently
10713 dead (or unchecked) server, and the client aborts while haproxy is
10714 waiting for the server to respond or for "timeout connect" to expire.
10715
10716 CD The client unexpectedly aborted during data transfer. This can be
10717 caused by a browser crash, by an intermediate equipment between the
10718 client and haproxy which decided to actively break the connection,
10719 by network routing issues between the client and haproxy, or by a
10720 keep-alive session between the server and the client terminated first
10721 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +010010722
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010723 cD The client did not send nor acknowledge any data for as long as the
10724 "timeout client" delay. This is often caused by network failures on
Cyril Bontédc4d9032012-04-08 21:57:39 +020010725 the client side, or the client simply leaving the net uncleanly.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010726
10727 CH The client aborted while waiting for the server to start responding.
10728 It might be the server taking too long to respond or the client
10729 clicking the 'Stop' button too fast.
10730
10731 cH The "timeout client" stroke while waiting for client data during a
10732 POST request. This is sometimes caused by too large TCP MSS values
10733 for PPPoE networks which cannot transport full-sized packets. It can
10734 also happen when client timeout is smaller than server timeout and
10735 the server takes too long to respond.
10736
10737 CQ The client aborted while its session was queued, waiting for a server
10738 with enough empty slots to accept it. It might be that either all the
10739 servers were saturated or that the assigned server was taking too
10740 long a time to respond.
10741
10742 CR The client aborted before sending a full HTTP request. Most likely
10743 the request was typed by hand using a telnet client, and aborted
10744 too early. The HTTP status code is likely a 400 here. Sometimes this
10745 might also be caused by an IDS killing the connection between haproxy
10746 and the client.
10747
10748 cR The "timeout http-request" stroke before the client sent a full HTTP
10749 request. This is sometimes caused by too large TCP MSS values on the
10750 client side for PPPoE networks which cannot transport full-sized
10751 packets, or by clients sending requests by hand and not typing fast
10752 enough, or forgetting to enter the empty line at the end of the
10753 request. The HTTP status code is likely a 408 here.
10754
10755 CT The client aborted while its session was tarpitted. It is important to
10756 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +020010757 wrong tarpit rules have been written. If a lot of them happen, it
10758 might make sense to lower the "timeout tarpit" value to something
10759 closer to the average reported "Tw" timer, in order not to consume
10760 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010761
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010762 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010763 the TCP connection (the proxy received a TCP RST or an ICMP message
10764 in return). Under some circumstances, it can also be the network
10765 stack telling the proxy that the server is unreachable (eg: no route,
10766 or no ARP response on local network). When this happens in HTTP mode,
10767 the status code is likely a 502 or 503 here.
10768
10769 sC The "timeout connect" stroke before a connection to the server could
10770 complete. When this happens in HTTP mode, the status code is likely a
10771 503 or 504 here.
10772
10773 SD The connection to the server died with an error during the data
10774 transfer. This usually means that haproxy has received an RST from
10775 the server or an ICMP message from an intermediate equipment while
10776 exchanging data with the server. This can be caused by a server crash
10777 or by a network issue on an intermediate equipment.
10778
10779 sD The server did not send nor acknowledge any data for as long as the
10780 "timeout server" setting during the data phase. This is often caused
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010781 by too short timeouts on L4 equipments before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010782 load-balancers, ...), as well as keep-alive sessions maintained
10783 between the client and the server expiring first on haproxy.
10784
10785 SH The server aborted before sending its full HTTP response headers, or
10786 it crashed while processing the request. Since a server aborting at
10787 this moment is very rare, it would be wise to inspect its logs to
10788 control whether it crashed and why. The logged request may indicate a
10789 small set of faulty requests, demonstrating bugs in the application.
10790 Sometimes this might also be caused by an IDS killing the connection
10791 between haproxy and the server.
10792
10793 sH The "timeout server" stroke before the server could return its
10794 response headers. This is the most common anomaly, indicating too
10795 long transactions, probably caused by server or database saturation.
10796 The immediate workaround consists in increasing the "timeout server"
10797 setting, but it is important to keep in mind that the user experience
10798 will suffer from these long response times. The only long term
10799 solution is to fix the application.
10800
10801 sQ The session spent too much time in queue and has been expired. See
10802 the "timeout queue" and "timeout connect" settings to find out how to
10803 fix this if it happens too often. If it often happens massively in
10804 short periods, it may indicate general problems on the affected
10805 servers due to I/O or database congestion, or saturation caused by
10806 external attacks.
10807
10808 PC The proxy refused to establish a connection to the server because the
10809 process' socket limit has been reached while attempting to connect.
Cyril Bontédc4d9032012-04-08 21:57:39 +020010810 The global "maxconn" parameter may be increased in the configuration
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010811 so that it does not happen anymore. This status is very rare and
10812 might happen when the global "ulimit-n" parameter is forced by hand.
10813
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010010814 PD The proxy blocked an incorrectly formatted chunked encoded message in
10815 a request or a response, after the server has emitted its headers. In
10816 most cases, this will indicate an invalid message from the server to
10817 the client.
10818
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010819 PH The proxy blocked the server's response, because it was invalid,
10820 incomplete, dangerous (cache control), or matched a security filter.
10821 In any case, an HTTP 502 error is sent to the client. One possible
10822 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010010823 containing unauthorized characters. It is also possible but quite
10824 rare, that the proxy blocked a chunked-encoding request from the
10825 client due to an invalid syntax, before the server responded. In this
10826 case, an HTTP 400 error is sent to the client and reported in the
10827 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010828
10829 PR The proxy blocked the client's HTTP request, either because of an
10830 invalid HTTP syntax, in which case it returned an HTTP 400 error to
10831 the client, or because a deny filter matched, in which case it
10832 returned an HTTP 403 error.
10833
10834 PT The proxy blocked the client's request and has tarpitted its
10835 connection before returning it a 500 server error. Nothing was sent
10836 to the server. The connection was maintained open for as long as
10837 reported by the "Tw" timer field.
10838
10839 RC A local resource has been exhausted (memory, sockets, source ports)
10840 preventing the connection to the server from establishing. The error
10841 logs will tell precisely what was missing. This is very rare and can
10842 only be solved by proper system tuning.
10843
Willy Tarreau996a92c2010-10-13 19:30:47 +020010844The combination of the two last flags gives a lot of information about how
10845persistence was handled by the client, the server and by haproxy. This is very
10846important to troubleshoot disconnections, when users complain they have to
10847re-authenticate. The commonly encountered flags are :
10848
10849 -- Persistence cookie is not enabled.
10850
10851 NN No cookie was provided by the client, none was inserted in the
10852 response. For instance, this can be in insert mode with "postonly"
10853 set on a GET request.
10854
10855 II A cookie designating an invalid server was provided by the client,
10856 a valid one was inserted in the response. This typically happens when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010857 a "server" entry is removed from the configuration, since its cookie
Willy Tarreau996a92c2010-10-13 19:30:47 +020010858 value can be presented by a client when no other server knows it.
10859
10860 NI No cookie was provided by the client, one was inserted in the
10861 response. This typically happens for first requests from every user
10862 in "insert" mode, which makes it an easy way to count real users.
10863
10864 VN A cookie was provided by the client, none was inserted in the
10865 response. This happens for most responses for which the client has
10866 already got a cookie.
10867
10868 VU A cookie was provided by the client, with a last visit date which is
10869 not completely up-to-date, so an updated cookie was provided in
10870 response. This can also happen if there was no date at all, or if
10871 there was a date but the "maxidle" parameter was not set, so that the
10872 cookie can be switched to unlimited time.
10873
10874 EI A cookie was provided by the client, with a last visit date which is
10875 too old for the "maxidle" parameter, so the cookie was ignored and a
10876 new cookie was inserted in the response.
10877
10878 OI A cookie was provided by the client, with a first visit date which is
10879 too old for the "maxlife" parameter, so the cookie was ignored and a
10880 new cookie was inserted in the response.
10881
10882 DI The server designated by the cookie was down, a new server was
10883 selected and a new cookie was emitted in the response.
10884
10885 VI The server designated by the cookie was not marked dead but could not
10886 be reached. A redispatch happened and selected another one, which was
10887 then advertised in the response.
10888
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010889
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200108908.6. Non-printable characters
10891-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010892
10893In order not to cause trouble to log analysis tools or terminals during log
10894consulting, non-printable characters are not sent as-is into log files, but are
10895converted to the two-digits hexadecimal representation of their ASCII code,
10896prefixed by the character '#'. The only characters that can be logged without
10897being escaped are comprised between 32 and 126 (inclusive). Obviously, the
10898escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
10899is the same for the character '"' which becomes "#22", as well as '{', '|' and
10900'}' when logging headers.
10901
10902Note that the space character (' ') is not encoded in headers, which can cause
10903issues for tools relying on space count to locate fields. A typical header
10904containing spaces is "User-Agent".
10905
10906Last, it has been observed that some syslog daemons such as syslog-ng escape
10907the quote ('"') with a backslash ('\'). The reverse operation can safely be
10908performed since no quote may appear anywhere else in the logs.
10909
10910
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200109118.7. Capturing HTTP cookies
10912---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010913
10914Cookie capture simplifies the tracking a complete user session. This can be
10915achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010916section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010917cookie will simultaneously be checked in the request ("Cookie:" header) and in
10918the response ("Set-Cookie:" header). The respective values will be reported in
10919the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010920locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010921not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
10922user switches to a new session for example, because the server will reassign it
10923a new cookie. It is also possible to detect if a server unexpectedly sets a
10924wrong cookie to a client, leading to session crossing.
10925
10926 Examples :
10927 # capture the first cookie whose name starts with "ASPSESSION"
10928 capture cookie ASPSESSION len 32
10929
10930 # capture the first cookie whose name is exactly "vgnvisitor"
10931 capture cookie vgnvisitor= len 32
10932
10933
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200109348.8. Capturing HTTP headers
10935---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010936
10937Header captures are useful to track unique request identifiers set by an upper
10938proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
10939the response, one can search for information about the response length, how the
10940server asked the cache to behave, or an object location during a redirection.
10941
10942Header captures are performed using the "capture request header" and "capture
10943response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010944section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010945
10946It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010947time. Non-existent headers are logged as empty strings, and if one header
10948appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010949are grouped within braces '{' and '}' in the same order as they were declared,
10950and delimited with a vertical bar '|' without any space. Response headers
10951follow the same representation, but are displayed after a space following the
10952request headers block. These blocks are displayed just before the HTTP request
10953in the logs.
10954
10955 Example :
10956 # This instance chains to the outgoing proxy
10957 listen proxy-out
10958 mode http
10959 option httplog
10960 option logasap
10961 log global
10962 server cache1 192.168.1.1:3128
10963
10964 # log the name of the virtual server
10965 capture request header Host len 20
10966
10967 # log the amount of data uploaded during a POST
10968 capture request header Content-Length len 10
10969
10970 # log the beginning of the referrer
10971 capture request header Referer len 20
10972
10973 # server name (useful for outgoing proxies only)
10974 capture response header Server len 20
10975
10976 # logging the content-length is useful with "option logasap"
10977 capture response header Content-Length len 10
10978
10979 # log the expected cache behaviour on the response
10980 capture response header Cache-Control len 8
10981
10982 # the Via header will report the next proxy's name
10983 capture response header Via len 20
10984
10985 # log the URL location during a redirection
10986 capture response header Location len 20
10987
10988 >>> Aug 9 20:26:09 localhost \
10989 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
10990 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
10991 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
10992 "GET http://fr.adserver.yahoo.com/"
10993
10994 >>> Aug 9 20:30:46 localhost \
10995 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
10996 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
10997 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010010998 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010999
11000 >>> Aug 9 20:30:46 localhost \
11001 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
11002 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
11003 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
11004 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010011005 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011006
11007
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200110088.9. Examples of logs
11009---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011010
11011These are real-world examples of logs accompanied with an explanation. Some of
11012them have been made up by hand. The syslog part has been removed for better
11013reading. Their sole purpose is to explain how to decipher them.
11014
11015 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
11016 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
11017 "HEAD / HTTP/1.0"
11018
11019 => long request (6.5s) entered by hand through 'telnet'. The server replied
11020 in 147 ms, and the session ended normally ('----')
11021
11022 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
11023 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
11024 0/9 "HEAD / HTTP/1.0"
11025
11026 => Idem, but the request was queued in the global queue behind 9 other
11027 requests, and waited there for 1230 ms.
11028
11029 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
11030 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
11031 "GET /image.iso HTTP/1.0"
11032
11033 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011034 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011035 14 ms, 243 bytes of headers were sent to the client, and total time from
11036 accept to first data byte is 30 ms.
11037
11038 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
11039 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
11040 "GET /cgi-bin/bug.cgi? HTTP/1.0"
11041
11042 => the proxy blocked a server response either because of an "rspdeny" or
11043 "rspideny" filter, or because the response was improperly formatted and
Willy Tarreau3c92c5f2011-08-28 09:45:47 +020011044 not HTTP-compliant, or because it blocked sensitive information which
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011045 risked being cached. In this case, the response is replaced with a "502
11046 bad gateway". The flags ("PH--") tell us that it was haproxy who decided
11047 to return the 502 and not the server.
11048
11049 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +010011050 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 +010011051
11052 => the client never completed its request and aborted itself ("C---") after
11053 8.5s, while the proxy was waiting for the request headers ("-R--").
11054 Nothing was sent to any server.
11055
11056 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
11057 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
11058
11059 => The client never completed its request, which was aborted by the
11060 time-out ("c---") after 50s, while the proxy was waiting for the request
11061 headers ("-R--"). Nothing was sent to any server, but the proxy could
11062 send a 408 return code to the client.
11063
11064 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
11065 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
11066
11067 => This log was produced with "option tcplog". The client timed out after
11068 5 seconds ("c----").
11069
11070 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
11071 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +010011072 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011073
11074 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011075 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011076 (config says 'retries 3'), and no redispatch (otherwise we would have
11077 seen "/+3"). Status code 503 was returned to the client. There were 115
11078 connections on this server, 202 connections on this proxy, and 205 on
11079 the global process. It is possible that the server refused the
11080 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +010011081
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011082
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200110839. Statistics and monitoring
11084----------------------------
11085
11086It is possible to query HAProxy about its status. The most commonly used
11087mechanism is the HTTP statistics page. This page also exposes an alternative
11088CSV output format for monitoring tools. The same format is provided on the
11089Unix socket.
11090
11091
110929.1. CSV format
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011093---------------
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010011094
Willy Tarreau7f062c42009-03-05 18:43:00 +010011095The statistics may be consulted either from the unix socket or from the HTTP
11096page. Both means provide a CSV format whose fields follow.
11097
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010011098 0. pxname: proxy name
11099 1. svname: service name (FRONTEND for frontend, BACKEND for backend, any name
11100 for server)
11101 2. qcur: current queued requests
11102 3. qmax: max queued requests
11103 4. scur: current sessions
11104 5. smax: max sessions
11105 6. slim: sessions limit
11106 7. stot: total sessions
11107 8. bin: bytes in
11108 9. bout: bytes out
11109 10. dreq: denied requests
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010011110 11. dresp: denied responses
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010011111 12. ereq: request errors
11112 13. econ: connection errors
Willy Tarreauae526782010-03-04 20:34:23 +010011113 14. eresp: response errors (among which srv_abrt)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010011114 15. wretr: retries (warning)
11115 16. wredis: redispatches (warning)
Cyril Bonté0dae5852010-02-03 00:26:28 +010011116 17. status: status (UP/DOWN/NOLB/MAINT/MAINT(via)...)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010011117 18. weight: server weight (server), total weight (backend)
11118 19. act: server is active (server), number of active servers (backend)
11119 20. bck: server is backup (server), number of backup servers (backend)
11120 21. chkfail: number of failed checks
11121 22. chkdown: number of UP->DOWN transitions
11122 23. lastchg: last status change (in seconds)
11123 24. downtime: total downtime (in seconds)
11124 25. qlimit: queue limit
11125 26. pid: process id (0 for first instance, 1 for second, ...)
11126 27. iid: unique proxy id
11127 28. sid: service id (unique inside a proxy)
11128 29. throttle: warm up status
11129 30. lbtot: total number of times a server was selected
11130 31. tracked: id of proxy/server if tracking is enabled
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +020011131 32. type (0=frontend, 1=backend, 2=server, 3=socket)
Krzysztof Piotr Oledzkidb57c6b2009-08-31 21:23:27 +020011132 33. rate: number of sessions per second over last elapsed second
11133 34. rate_lim: limit on new sessions per second
11134 35. rate_max: max number of new sessions per second
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +020011135 36. check_status: status of last health check, one of:
Cyril Bontéf0c60612010-02-06 14:44:47 +010011136 UNK -> unknown
11137 INI -> initializing
11138 SOCKERR -> socket error
11139 L4OK -> check passed on layer 4, no upper layers testing enabled
11140 L4TMOUT -> layer 1-4 timeout
11141 L4CON -> layer 1-4 connection problem, for example
11142 "Connection refused" (tcp rst) or "No route to host" (icmp)
11143 L6OK -> check passed on layer 6
11144 L6TOUT -> layer 6 (SSL) timeout
11145 L6RSP -> layer 6 invalid response - protocol error
11146 L7OK -> check passed on layer 7
11147 L7OKC -> check conditionally passed on layer 7, for example 404 with
11148 disable-on-404
11149 L7TOUT -> layer 7 (HTTP/SMTP) timeout
11150 L7RSP -> layer 7 invalid response - protocol error
11151 L7STS -> layer 7 response error, for example HTTP 5xx
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +020011152 37. check_code: layer5-7 code, if available
11153 38. check_duration: time in ms took to finish last health check
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011154 39. hrsp_1xx: http responses with 1xx code
11155 40. hrsp_2xx: http responses with 2xx code
11156 41. hrsp_3xx: http responses with 3xx code
11157 42. hrsp_4xx: http responses with 4xx code
11158 43. hrsp_5xx: http responses with 5xx code
11159 44. hrsp_other: http responses with other codes (protocol error)
Willy Tarreaud63335a2010-02-26 12:56:52 +010011160 45. hanafail: failed health checks details
11161 46. req_rate: HTTP requests per second over last elapsed second
11162 47. req_rate_max: max number of HTTP requests per second observed
11163 48. req_tot: total number of HTTP requests received
Willy Tarreauae526782010-03-04 20:34:23 +010011164 49. cli_abrt: number of data transfers aborted by the client
11165 50. srv_abrt: number of data transfers aborted by the server (inc. in eresp)
Willy Tarreau55058a72012-11-21 08:27:21 +010011166 51. comp_in: number of HTTP response bytes fed to the compressor
11167 52. comp_out: number of HTTP response bytes emitted by the compressor
11168 53. comp_byp: number of bytes that bypassed the HTTP compressor (CPU/BW limit)
Willy Tarreau11d4ec82012-11-26 00:49:03 +010011169 54. comp_rsp: number of HTTP responses that were compressed
Willy Tarreau844e3c52008-01-11 16:28:18 +010011170
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011171
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200111729.2. Unix Socket commands
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011173-------------------------
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010011174
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011175The following commands are supported on the UNIX stats socket ; all of them
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011176must be terminated by a line feed. The socket supports pipelining, so that it
11177is possible to chain multiple commands at once provided they are delimited by
11178a semi-colon or a line feed, although the former is more reliable as it has no
11179risk of being truncated over the network. The responses themselves will each be
11180followed by an empty line, so it will be easy for an external script to match a
11181given response with a given request. By default one command line is processed
11182then the connection closes, but there is an interactive allowing multiple lines
11183to be issued one at a time.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011184
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011185It is important to understand that when multiple haproxy processes are started
11186on the same sockets, any process may pick up the request and will output its
11187own stats.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011188
Willy Tarreaud63335a2010-02-26 12:56:52 +010011189clear counters
11190 Clear the max values of the statistics counters in each proxy (frontend &
11191 backend) and in each server. The cumulated counters are not affected. This
11192 can be used to get clean counters after an incident, without having to
11193 restart nor to clear traffic counters. This command is restricted and can
11194 only be issued on sockets configured for levels "operator" or "admin".
11195
11196clear counters all
11197 Clear all statistics counters in each proxy (frontend & backend) and in each
11198 server. This has the same effect as restarting. This command is restricted
11199 and can only be issued on sockets configured for level "admin".
11200
Simon Hormanc88b8872011-06-15 15:18:49 +090011201clear table <table> [ data.<type> <operator> <value> ] | [ key <key> ]
11202 Remove entries from the stick-table <table>.
11203
11204 This is typically used to unblock some users complaining they have been
11205 abusively denied access to a service, but this can also be used to clear some
11206 stickiness entries matching a server that is going to be replaced (see "show
11207 table" below for details). Note that sometimes, removal of an entry will be
11208 refused because it is currently tracked by a session. Retrying a few seconds
11209 later after the session ends is usual enough.
11210
11211 In the case where no options arguments are given all entries will be removed.
11212
11213 When the "data." form is used entries matching a filter applied using the
11214 stored data (see "stick-table" in section 4.2) are removed. A stored data
11215 type must be specified in <type>, and this data type must be stored in the
11216 table otherwise an error is reported. The data is compared according to
11217 <operator> with the 64-bit integer <value>. Operators are the same as with
11218 the ACLs :
11219
11220 - eq : match entries whose data is equal to this value
11221 - ne : match entries whose data is not equal to this value
11222 - le : match entries whose data is less than or equal to this value
11223 - ge : match entries whose data is greater than or equal to this value
11224 - lt : match entries whose data is less than this value
11225 - gt : match entries whose data is greater than this value
11226
11227 When the key form is used the entry <key> is removed. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +090011228 same type as the table, which currently is limited to IPv4, IPv6, integer and
11229 string.
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011230
11231 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020011232 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +020011233 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020011234 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
11235 bytes_out_rate(60000)=187
11236 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
11237 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011238
11239 $ echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1
11240
11241 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +020011242 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau62a36c42010-08-17 15:53:10 +020011243 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
11244 bytes_out_rate(60000)=191
Simon Hormanc88b8872011-06-15 15:18:49 +090011245 $ echo "clear table http_proxy data.gpc0 eq 1" | socat stdio /tmp/sock1
11246 $ echo "show table http_proxy" | socat stdio /tmp/sock1
11247 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011248
Willy Tarreau532a4502011-09-07 22:37:44 +020011249disable frontend <frontend>
11250 Mark the frontend as temporarily stopped. This corresponds to the mode which
11251 is used during a soft restart : the frontend releases the port but can be
11252 enabled again if needed. This should be used with care as some non-Linux OSes
11253 are unable to enable it back. This is intended to be used in environments
11254 where stopping a proxy is not even imaginable but a misconfigured proxy must
11255 be fixed. That way it's possible to release the port and bind it into another
11256 process to restore operations. The frontend will appear with status "STOP"
11257 on the stats page.
11258
11259 The frontend may be specified either by its name or by its numeric ID,
11260 prefixed with a sharp ('#').
11261
11262 This command is restricted and can only be issued on sockets configured for
11263 level "admin".
11264
Willy Tarreaud63335a2010-02-26 12:56:52 +010011265disable server <backend>/<server>
11266 Mark the server DOWN for maintenance. In this mode, no more checks will be
11267 performed on the server until it leaves maintenance.
11268 If the server is tracked by other servers, those servers will be set to DOWN
11269 during the maintenance.
11270
11271 In the statistics page, a server DOWN for maintenance will appear with a
11272 "MAINT" status, its tracking servers with the "MAINT(via)" one.
11273
11274 Both the backend and the server may be specified either by their name or by
Willy Tarreauf5f31922011-08-02 11:32:07 +020011275 their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010011276
11277 This command is restricted and can only be issued on sockets configured for
11278 level "admin".
11279
Willy Tarreau532a4502011-09-07 22:37:44 +020011280enable frontend <frontend>
11281 Resume a frontend which was temporarily stopped. It is possible that some of
11282 the listening ports won't be able to bind anymore (eg: if another process
11283 took them since the 'disable frontend' operation). If this happens, an error
11284 is displayed. Some operating systems might not be able to resume a frontend
11285 which was disabled.
11286
11287 The frontend may be specified either by its name or by its numeric ID,
11288 prefixed with a sharp ('#').
11289
11290 This command is restricted and can only be issued on sockets configured for
11291 level "admin".
11292
Willy Tarreaud63335a2010-02-26 12:56:52 +010011293enable server <backend>/<server>
11294 If the server was previously marked as DOWN for maintenance, this marks the
11295 server UP and checks are re-enabled.
11296
11297 Both the backend and the server may be specified either by their name or by
Willy Tarreauf5f31922011-08-02 11:32:07 +020011298 their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010011299
11300 This command is restricted and can only be issued on sockets configured for
11301 level "admin".
11302
11303get weight <backend>/<server>
11304 Report the current weight and the initial weight of server <server> in
11305 backend <backend> or an error if either doesn't exist. The initial weight is
11306 the one that appears in the configuration file. Both are normally equal
11307 unless the current weight has been changed. Both the backend and the server
11308 may be specified either by their name or by their numeric ID, prefixed with a
Willy Tarreauf5f31922011-08-02 11:32:07 +020011309 sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010011310
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011311help
11312 Print the list of known keywords and their basic usage. The same help screen
11313 is also displayed for unknown commands.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011314
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011315prompt
11316 Toggle the prompt at the beginning of the line and enter or leave interactive
11317 mode. In interactive mode, the connection is not closed after a command
11318 completes. Instead, the prompt will appear again, indicating the user that
11319 the interpreter is waiting for a new command. The prompt consists in a right
11320 angle bracket followed by a space "> ". This mode is particularly convenient
11321 when one wants to periodically check information such as stats or errors.
11322 It is also a good idea to enter interactive mode before issuing a "help"
11323 command.
11324
11325quit
11326 Close the connection when in interactive mode.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010011327
Willy Tarreau2a0f4d22011-08-02 11:49:05 +020011328set maxconn frontend <frontend> <value>
Willy Tarreau3c7a79d2012-09-26 21:07:15 +020011329 Dynamically change the specified frontend's maxconn setting. Any positive
11330 value is allowed including zero, but setting values larger than the global
11331 maxconn does not make much sense. If the limit is increased and connections
11332 were pending, they will immediately be accepted. If it is lowered to a value
11333 below the current number of connections, new connections acceptation will be
Willy Tarreau2a0f4d22011-08-02 11:49:05 +020011334 delayed until the threshold is reached. The frontend might be specified by
11335 either its name or its numeric ID prefixed with a sharp ('#').
11336
Willy Tarreau91886b62011-09-07 14:38:31 +020011337set maxconn global <maxconn>
11338 Dynamically change the global maxconn setting within the range defined by the
11339 initial global maxconn setting. If it is increased and connections were
11340 pending, they will immediately be accepted. If it is lowered to a value below
11341 the current number of connections, new connections acceptation will be
11342 delayed until the threshold is reached. A value of zero restores the initial
11343 setting.
11344
Willy Tarreauf5b22872011-09-07 16:13:44 +020011345set rate-limit connections global <value>
11346 Change the process-wide connection rate limit, which is set by the global
11347 'maxconnrate' setting. A value of zero disables the limitation. This limit
11348 applies to all frontends and the change has an immediate effect. The value
11349 is passed in number of connections per second.
11350
William Lallemandd85f9172012-11-09 17:05:39 +010011351set rate-limit http-compression global <value>
11352 Change the maximum input compression rate, which is set by the global
11353 'maxcomprate' setting. A value of zero disables the limitation. The value is
William Lallemand096f5542012-11-19 17:26:05 +010011354 passed in number of kilobytes per second. The value is available in the "show
11355 info" on the line "CompressBpsRateLim" in bytes.
William Lallemandd85f9172012-11-09 17:05:39 +010011356
Willy Tarreau654694e2012-06-07 01:03:16 +020011357set table <table> key <key> data.<data_type> <value>
11358 Create or update a stick-table entry in the table. If the key is not present,
11359 an entry is inserted. See stick-table in section 4.2 to find all possible
11360 values for <data_type>. The most likely use consists in dynamically entering
11361 entries for source IP addresses, with a flag in gpc0 to dynamically block an
11362 IP address or affect its quality of service.
11363
Willy Tarreaud63335a2010-02-26 12:56:52 +010011364set timeout cli <delay>
11365 Change the CLI interface timeout for current connection. This can be useful
11366 during long debugging sessions where the user needs to constantly inspect
11367 some indicators without being disconnected. The delay is passed in seconds.
11368
11369set weight <backend>/<server> <weight>[%]
11370 Change a server's weight to the value passed in argument. If the value ends
11371 with the '%' sign, then the new weight will be relative to the initially
11372 configured weight. Relative weights are only permitted between 0 and 100%,
11373 and absolute weights are permitted between 0 and 256. Servers which are part
11374 of a farm running a static load-balancing algorithm have stricter limitations
11375 because the weight cannot change once set. Thus for these servers, the only
11376 accepted values are 0 and 100% (or 0 and the initial weight). Changes take
11377 effect immediately, though certain LB algorithms require a certain amount of
11378 requests to consider changes. A typical usage of this command is to disable
11379 a server during an update by setting its weight to zero, then to enable it
11380 again after the update by setting it back to 100%. This command is restricted
11381 and can only be issued on sockets configured for level "admin". Both the
11382 backend and the server may be specified either by their name or by their
Willy Tarreauf5f31922011-08-02 11:32:07 +020011383 numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010011384
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010011385show errors [<iid>]
11386 Dump last known request and response errors collected by frontends and
11387 backends. If <iid> is specified, the limit the dump to errors concerning
Willy Tarreau6162db22009-10-10 17:13:00 +020011388 either frontend or backend whose ID is <iid>. This command is restricted
11389 and can only be issued on sockets configured for levels "operator" or
11390 "admin".
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010011391
11392 The errors which may be collected are the last request and response errors
11393 caused by protocol violations, often due to invalid characters in header
11394 names. The report precisely indicates what exact character violated the
11395 protocol. Other important information such as the exact date the error was
11396 detected, frontend and backend names, the server name (when known), the
11397 internal session ID and the source address which has initiated the session
11398 are reported too.
11399
11400 All characters are returned, and non-printable characters are encoded. The
11401 most common ones (\t = 9, \n = 10, \r = 13 and \e = 27) are encoded as one
11402 letter following a backslash. The backslash itself is encoded as '\\' to
11403 avoid confusion. Other non-printable characters are encoded '\xNN' where
11404 NN is the two-digits hexadecimal representation of the character's ASCII
11405 code.
11406
11407 Lines are prefixed with the position of their first character, starting at 0
11408 for the beginning of the buffer. At most one input line is printed per line,
11409 and large lines will be broken into multiple consecutive output lines so that
11410 the output never goes beyond 79 characters wide. It is easy to detect if a
11411 line was broken, because it will not end with '\n' and the next line's offset
11412 will be followed by a '+' sign, indicating it is a continuation of previous
11413 line.
11414
11415 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020011416 $ echo "show errors" | socat stdio /tmp/sock1
11417 >>> [04/Mar/2009:15:46:56.081] backend http-in (#2) : invalid response
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010011418 src 127.0.0.1, session #54, frontend fe-eth0 (#1), server s2 (#1)
11419 response length 213 bytes, error at position 23:
11420
11421 00000 HTTP/1.0 200 OK\r\n
11422 00017 header/bizarre:blah\r\n
11423 00038 Location: blah\r\n
11424 00054 Long-line: this is a very long line which should b
11425 00104+ e broken into multiple lines on the output buffer,
11426 00154+ otherwise it would be too large to print in a ter
11427 00204+ minal\r\n
11428 00211 \r\n
11429
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011430 In the example above, we see that the backend "http-in" which has internal
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010011431 ID 2 has blocked an invalid response from its server s2 which has internal
11432 ID 1. The request was on session 54 initiated by source 127.0.0.1 and
11433 received by frontend fe-eth0 whose ID is 1. The total response length was
11434 213 bytes when the error was detected, and the error was at byte 23. This
11435 is the slash ('/') in header name "header/bizarre", which is not a valid
11436 HTTP character for a header name.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010011437
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011438show info
11439 Dump info about haproxy status on current process.
11440
11441show sess
11442 Dump all known sessions. Avoid doing this on slow connections as this can
Willy Tarreau6162db22009-10-10 17:13:00 +020011443 be huge. This command is restricted and can only be issued on sockets
11444 configured for levels "operator" or "admin".
11445
Willy Tarreau66dc20a2010-03-05 17:53:32 +010011446show sess <id>
11447 Display a lot of internal information about the specified session identifier.
11448 This identifier is the first field at the beginning of the lines in the dumps
11449 of "show sess" (it corresponds to the session pointer). Those information are
11450 useless to most users but may be used by haproxy developers to troubleshoot a
11451 complex bug. The output format is intentionally not documented so that it can
Willy Tarreau76153662012-11-26 01:16:39 +010011452 freely evolve depending on demands. The special id "all" dumps the states of
11453 all sessions, which can be avoided as much as possible as it is highly CPU
11454 intensive and can take a lot of time.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011455
11456show stat [<iid> <type> <sid>]
11457 Dump statistics in the CSV format. By passing <id>, <type> and <sid>, it is
11458 possible to dump only selected items :
11459 - <iid> is a proxy ID, -1 to dump everything
11460 - <type> selects the type of dumpable objects : 1 for frontends, 2 for
11461 backends, 4 for servers, -1 for everything. These values can be ORed,
11462 for example:
11463 1 + 2 = 3 -> frontend + backend.
11464 1 + 2 + 4 = 7 -> frontend + backend + server.
11465 - <sid> is a server ID, -1 to dump everything from the selected proxy.
11466
11467 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020011468 $ echo "show info;show stat" | socat stdio unix-connect:/tmp/sock1
11469 >>> Name: HAProxy
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011470 Version: 1.4-dev2-49
11471 Release_date: 2009/09/23
11472 Nbproc: 1
11473 Process_num: 1
11474 (...)
11475
11476 # pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,dreq, (...)
11477 stats,FRONTEND,,,0,0,1000,0,0,0,0,0,0,,,,,OPEN,,,,,,,,,1,1,0, (...)
11478 stats,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,0,0,0,,0,250,(...)
11479 (...)
11480 www1,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,1,1,0,,0,250, (...)
11481
11482 $
11483
11484 Here, two commands have been issued at once. That way it's easy to find
11485 which process the stats apply to in multi-process mode. Notice the empty
11486 line after the information output which marks the end of the first block.
11487 A similar empty line appears at the end of the second block (stats) so that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011488 the reader knows the output has not been truncated.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011489
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011490show table
11491 Dump general information on all known stick-tables. Their name is returned
11492 (the name of the proxy which holds them), their type (currently zero, always
11493 IP), their size in maximum possible number of entries, and the number of
11494 entries currently in use.
11495
11496 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020011497 $ echo "show table" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090011498 >>> # table: front_pub, type: ip, size:204800, used:171454
11499 >>> # table: back_rdp, type: ip, size:204800, used:0
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011500
Simon Horman17bce342011-06-15 15:18:47 +090011501show table <name> [ data.<type> <operator> <value> ] | [ key <key> ]
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011502 Dump contents of stick-table <name>. In this mode, a first line of generic
11503 information about the table is reported as with "show table", then all
11504 entries are dumped. Since this can be quite heavy, it is possible to specify
Simon Horman17bce342011-06-15 15:18:47 +090011505 a filter in order to specify what entries to display.
11506
11507 When the "data." form is used the filter applies to the stored data (see
11508 "stick-table" in section 4.2). A stored data type must be specified
11509 in <type>, and this data type must be stored in the table otherwise an
11510 error is reported. The data is compared according to <operator> with the
11511 64-bit integer <value>. Operators are the same as with the ACLs :
11512
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011513 - eq : match entries whose data is equal to this value
11514 - ne : match entries whose data is not equal to this value
11515 - le : match entries whose data is less than or equal to this value
11516 - ge : match entries whose data is greater than or equal to this value
11517 - lt : match entries whose data is less than this value
11518 - gt : match entries whose data is greater than this value
11519
Simon Hormanc88b8872011-06-15 15:18:49 +090011520
11521 When the key form is used the entry <key> is shown. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +090011522 same type as the table, which currently is limited to IPv4, IPv6, integer,
11523 and string.
Simon Horman17bce342011-06-15 15:18:47 +090011524
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011525 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020011526 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090011527 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020011528 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
11529 bytes_out_rate(60000)=187
11530 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
11531 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011532
Willy Tarreau62a36c42010-08-17 15:53:10 +020011533 $ echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090011534 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020011535 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
11536 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011537
Willy Tarreau62a36c42010-08-17 15:53:10 +020011538 $ echo "show table http_proxy data.conn_rate gt 5" | \
11539 socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090011540 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020011541 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
11542 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011543
Simon Horman17bce342011-06-15 15:18:47 +090011544 $ echo "show table http_proxy key 127.0.0.2" | \
11545 socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090011546 >>> # table: http_proxy, type: ip, size:204800, used:2
Simon Horman17bce342011-06-15 15:18:47 +090011547 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
11548 bytes_out_rate(60000)=191
11549
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011550 When the data criterion applies to a dynamic value dependent on time such as
11551 a bytes rate, the value is dynamically computed during the evaluation of the
11552 entry in order to decide whether it has to be dumped or not. This means that
11553 such a filter could match for some time then not match anymore because as
11554 time goes, the average event rate drops.
11555
11556 It is possible to use this to extract lists of IP addresses abusing the
11557 service, in order to monitor them or even blacklist them in a firewall.
11558 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020011559 $ echo "show table http_proxy data.gpc0 gt 0" \
11560 | socat stdio /tmp/sock1 \
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020011561 | fgrep 'key=' | cut -d' ' -f2 | cut -d= -f2 > abusers-ip.txt
11562 ( or | awk '/key/{ print a[split($2,a,"=")]; }' )
Krzysztof Piotr Oledzki719e7262009-10-04 15:02:46 +020011563
Willy Tarreau532a4502011-09-07 22:37:44 +020011564shutdown frontend <frontend>
11565 Completely delete the specified frontend. All the ports it was bound to will
11566 be released. It will not be possible to enable the frontend anymore after
11567 this operation. This is intended to be used in environments where stopping a
11568 proxy is not even imaginable but a misconfigured proxy must be fixed. That
11569 way it's possible to release the port and bind it into another process to
11570 restore operations. The frontend will not appear at all on the stats page
11571 once it is terminated.
11572
11573 The frontend may be specified either by its name or by its numeric ID,
11574 prefixed with a sharp ('#').
11575
11576 This command is restricted and can only be issued on sockets configured for
11577 level "admin".
11578
Willy Tarreaua295edc2011-09-07 23:21:03 +020011579shutdown session <id>
11580 Immediately terminate the session matching the specified session identifier.
11581 This identifier is the first field at the beginning of the lines in the dumps
11582 of "show sess" (it corresponds to the session pointer). This can be used to
11583 terminate a long-running session without waiting for a timeout or when an
11584 endless transfer is ongoing. Such terminated sessions are reported with a 'K'
11585 flag in the logs.
11586
Willy Tarreau52b2d222011-09-07 23:48:48 +020011587shutdown sessions <backend>/<server>
11588 Immediately terminate all the sessions attached to the specified server. This
11589 can be used to terminate long-running sessions after a server is put into
11590 maintenance mode, for instance. Such terminated sessions are reported with a
11591 'K' flag in the logs.
11592
Willy Tarreau0ba27502007-12-24 16:55:16 +010011593/*
11594 * Local variables:
11595 * fill-column: 79
11596 * End:
11597 */