blob: d15df49071e2d643da620439f2c364ef3a82f011 [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 Tarreaua3ecbd92012-12-28 15:04:05 +01007 2012/12/28
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
Willy Tarreaub67fdc42013-03-29 19:28:11 +0100320 307 when performing a redirection, depending on the configured code
321 308 when performing a redirection, depending on the configured code
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200322 400 for an invalid or too large request
323 401 when an authentication is required to perform the action (when
324 accessing the stats page)
325 403 when a request is forbidden by a "block" ACL or "reqdeny" filter
326 408 when the request timeout strikes before the request is complete
327 500 when haproxy encounters an unrecoverable internal error, such as a
328 memory allocation failure, which should never happen
329 502 when the server returns an empty, invalid or incomplete response, or
330 when an "rspdeny" filter blocks the response.
331 503 when no server was available to handle the request, or in response to
332 monitoring requests which match the "monitor fail" condition
333 504 when the response timeout strikes before the server responds
334
335The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3364.2).
337
338
3391.3.2. The response headers
340---------------------------
341
342Response headers work exactly like request headers, and as such, HAProxy uses
343the same parsing function for both. Please refer to paragraph 1.2.2 for more
344details.
345
346
3472. Configuring HAProxy
348----------------------
349
3502.1. Configuration file format
351------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200352
353HAProxy's configuration process involves 3 major sources of parameters :
354
355 - the arguments from the command-line, which always take precedence
356 - the "global" section, which sets process-wide parameters
357 - the proxies sections which can take form of "defaults", "listen",
358 "frontend" and "backend".
359
Willy Tarreau0ba27502007-12-24 16:55:16 +0100360The configuration file syntax consists in lines beginning with a keyword
361referenced in this manual, optionally followed by one or several parameters
362delimited by spaces. If spaces have to be entered in strings, then they must be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100363preceded by a backslash ('\') to be escaped. Backslashes also have to be
Willy Tarreau0ba27502007-12-24 16:55:16 +0100364escaped by doubling them.
365
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200366
3672.2. Time format
368----------------
369
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100370Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100371values are generally expressed in milliseconds (unless explicitly stated
372otherwise) but may be expressed in any other unit by suffixing the unit to the
373numeric value. It is important to consider this because it will not be repeated
374for every keyword. Supported units are :
375
376 - us : microseconds. 1 microsecond = 1/1000000 second
377 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
378 - s : seconds. 1s = 1000ms
379 - m : minutes. 1m = 60s = 60000ms
380 - h : hours. 1h = 60m = 3600s = 3600000ms
381 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
382
383
Patrick Mezard35da19c2010-06-12 17:02:47 +02003842.3. Examples
385-------------
386
387 # Simple configuration for an HTTP proxy listening on port 80 on all
388 # interfaces and forwarding requests to a single backend "servers" with a
389 # single server "server1" listening on 127.0.0.1:8000
390 global
391 daemon
392 maxconn 256
393
394 defaults
395 mode http
396 timeout connect 5000ms
397 timeout client 50000ms
398 timeout server 50000ms
399
400 frontend http-in
401 bind *:80
402 default_backend servers
403
404 backend servers
405 server server1 127.0.0.1:8000 maxconn 32
406
407
408 # The same configuration defined with a single listen block. Shorter but
409 # less expressive, especially in HTTP mode.
410 global
411 daemon
412 maxconn 256
413
414 defaults
415 mode http
416 timeout connect 5000ms
417 timeout client 50000ms
418 timeout server 50000ms
419
420 listen http-in
421 bind *:80
422 server server1 127.0.0.1:8000 maxconn 32
423
424
425Assuming haproxy is in $PATH, test these configurations in a shell with:
426
Willy Tarreauccb289d2010-12-11 20:19:38 +0100427 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200428
429
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004303. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200431--------------------
432
433Parameters in the "global" section are process-wide and often OS-specific. They
434are generally set once for all and do not need being changed once correct. Some
435of them have command-line equivalents.
436
437The following keywords are supported in the "global" section :
438
439 * Process management and security
Emeric Brunc8e8d122012-10-02 18:42:10 +0200440 - ca-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200441 - chroot
Emeric Brunc8e8d122012-10-02 18:42:10 +0200442 - crt-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200443 - daemon
444 - gid
445 - group
446 - log
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100447 - log-send-hostname
Willy Tarreau6a06a402007-07-15 20:15:28 +0200448 - nbproc
449 - pidfile
450 - uid
451 - ulimit-n
452 - user
Willy Tarreaufbee7132007-10-18 13:53:22 +0200453 - stats
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200454 - node
455 - description
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100456 - unix-bind
Willy Tarreaud72758d2010-01-12 10:42:19 +0100457
Willy Tarreau6a06a402007-07-15 20:15:28 +0200458 * Performance tuning
459 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +0200460 - maxconnrate
William Lallemandd85f9172012-11-09 17:05:39 +0100461 - maxcomprate
William Lallemand072a2bf2012-11-20 17:01:01 +0100462 - maxcompcpuusage
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100463 - maxpipes
Willy Tarreau403edff2012-09-06 11:58:37 +0200464 - maxsslconn
Willy Tarreau6a06a402007-07-15 20:15:28 +0200465 - noepoll
466 - nokqueue
467 - nopoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100468 - nosplice
Willy Tarreaufe255b72007-10-14 23:09:26 +0200469 - spread-checks
Willy Tarreau27a674e2009-08-17 07:23:33 +0200470 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200471 - tune.chksize
William Lallemandf3747832012-11-09 12:33:10 +0100472 - tune.comp.maxlevel
Willy Tarreau193b8c62012-11-22 00:17:38 +0100473 - tune.http.cookielen
Willy Tarreauac1932d2011-10-24 19:14:41 +0200474 - tune.http.maxhdr
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100475 - tune.maxaccept
476 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200477 - tune.maxrewrite
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200478 - tune.pipesize
Willy Tarreaue803de22010-01-21 17:43:04 +0100479 - tune.rcvbuf.client
480 - tune.rcvbuf.server
481 - tune.sndbuf.client
482 - tune.sndbuf.server
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100483 - tune.ssl.cachesize
Willy Tarreaubfd59462013-02-21 07:46:09 +0100484 - tune.ssl.lifetime
485 - tune.ssl.maxrecord
William Lallemanda509e4c2012-11-07 16:54:34 +0100486 - tune.zlib.memlevel
487 - tune.zlib.windowsize
Willy Tarreaud72758d2010-01-12 10:42:19 +0100488
Willy Tarreau6a06a402007-07-15 20:15:28 +0200489 * Debugging
490 - debug
491 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200492
493
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004943.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200495------------------------------------
496
Emeric Brunc8e8d122012-10-02 18:42:10 +0200497ca-base <dir>
498 Assigns a default directory to fetch SSL CA certificates and CRLs from when a
Emeric Brunfd33a262012-10-11 16:28:27 +0200499 relative path is used with "ca-file" or "crl-file" directives. Absolute
500 locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200501
Willy Tarreau6a06a402007-07-15 20:15:28 +0200502chroot <jail dir>
503 Changes current directory to <jail dir> and performs a chroot() there before
504 dropping privileges. This increases the security level in case an unknown
505 vulnerability would be exploited, since it would make it very hard for the
506 attacker to exploit the system. This only works when the process is started
507 with superuser privileges. It is important to ensure that <jail_dir> is both
508 empty and unwritable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100509
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100510cpu-map <"all"|"odd"|"even"|process_num> <cpu-set>...
511 On Linux 2.6 and above, it is possible to bind a process to a specific CPU
512 set. This means that the process will never run on other CPUs. The "cpu-map"
513 directive specifies CPU sets for process sets. The first argument is the
514 process number to bind. This process must have a number between 1 and 32,
515 and any process IDs above nbproc are ignored. It is possible to specify all
516 processes at once using "all", only odd numbers using "odd" or even numbers
517 using "even", just like with the "bind-process" directive. The second and
518 forthcoming arguments are CPU sets. Each CPU set is either a unique number
519 between 0 and 31 or a range with two such numbers delimited by a dash ('-').
520 Multiple CPU numbers or ranges may be specified, and the processes will be
521 allowed to bind to all of them. Obviously, multiple "cpu-map" directives may
522 be specified. Each "cpu-map" directive will replace the previous ones when
523 they overlap.
524
Emeric Brunc8e8d122012-10-02 18:42:10 +0200525crt-base <dir>
526 Assigns a default directory to fetch SSL certificates from when a relative
527 path is used with "crtfile" directives. Absolute locations specified after
528 "crtfile" prevail and ignore "crt-base".
529
Willy Tarreau6a06a402007-07-15 20:15:28 +0200530daemon
531 Makes the process fork into background. This is the recommended mode of
532 operation. It is equivalent to the command line "-D" argument. It can be
533 disabled by the command line "-db" argument.
534
535gid <number>
536 Changes the process' group ID to <number>. It is recommended that the group
537 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
538 be started with a user belonging to this group, or with superuser privileges.
Michael Schererab012dd2013-01-12 18:35:19 +0100539 Note that if haproxy is started from a user having supplementary groups, it
540 will only be able to drop these groups if started with superuser privileges.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200541 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100542
Willy Tarreau6a06a402007-07-15 20:15:28 +0200543group <group name>
544 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
545 See also "gid" and "user".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100546
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200547log <address> <facility> [max level [min level]]
Willy Tarreau6a06a402007-07-15 20:15:28 +0200548 Adds a global syslog server. Up to two global servers can be defined. They
549 will receive logs for startups and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100550 configured with "log global".
551
552 <address> can be one of:
553
Willy Tarreau2769aa02007-12-27 18:26:09 +0100554 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100555 no port is specified, 514 is used by default (the standard syslog
556 port).
557
David du Colombier24bb5f52011-03-17 10:40:23 +0100558 - An IPv6 address followed by a colon and optionally a UDP port. If
559 no port is specified, 514 is used by default (the standard syslog
560 port).
561
Robert Tsai81ae1952007-12-05 10:47:29 +0100562 - A filesystem path to a UNIX domain socket, keeping in mind
563 considerations for chroot (be sure the path is accessible inside
564 the chroot) and uid/gid (be sure the path is appropriately
565 writeable).
566
Willy Tarreaudad36a32013-03-11 01:20:04 +0100567 Any part of the address string may reference any number of environment
568 variables by preceding their name with a dollar sign ('$') and
569 optionally enclosing them with braces ('{}'), similarly to what is done
570 in Bourne shell.
571
Robert Tsai81ae1952007-12-05 10:47:29 +0100572 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200573
574 kern user mail daemon auth syslog lpr news
575 uucp cron auth2 ftp ntp audit alert cron2
576 local0 local1 local2 local3 local4 local5 local6 local7
577
578 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +0200579 all messages are sent. If a maximum level is specified, only messages with a
580 severity at least as important as this level will be sent. An optional minimum
581 level can be specified. If it is set, logs emitted with a more severe level
582 than this one will be capped to this level. This is used to avoid sending
583 "emerg" messages on all terminals on some default syslog configurations.
584 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200585
Cyril Bontédc4d9032012-04-08 21:57:39 +0200586 emerg alert crit err warning notice info debug
Willy Tarreau6a06a402007-07-15 20:15:28 +0200587
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100588log-send-hostname [<string>]
589 Sets the hostname field in the syslog header. If optional "string" parameter
590 is set the header is set to the string contents, otherwise uses the hostname
591 of the system. Generally used if one is not relaying logs through an
592 intermediate syslog server or for simply customizing the hostname printed in
593 the logs.
594
Kevinm48936af2010-12-22 16:08:21 +0000595log-tag <string>
596 Sets the tag field in the syslog header to this string. It defaults to the
597 program name as launched from the command line, which usually is "haproxy".
598 Sometimes it can be useful to differentiate between multiple processes
599 running on the same host.
600
Willy Tarreau6a06a402007-07-15 20:15:28 +0200601nbproc <number>
602 Creates <number> processes when going daemon. This requires the "daemon"
603 mode. By default, only one process is created, which is the recommended mode
604 of operation. For systems limited to small sets of file descriptors per
605 process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES
606 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon".
607
608pidfile <pidfile>
609 Writes pids of all daemons into file <pidfile>. This option is equivalent to
610 the "-p" command line argument. The file must be accessible to the user
611 starting the process. See also "daemon".
612
Willy Tarreau110ecc12012-11-15 17:50:01 +0100613stats bind-process [ all | odd | even | <number 1-32>[-<number 1-32>] ] ...
Willy Tarreau35b7b162012-10-22 23:17:18 +0200614 Limits the stats socket to a certain set of processes numbers. By default the
615 stats socket is bound to all processes, causing a warning to be emitted when
616 nbproc is greater than 1 because there is no way to select the target process
617 when connecting. However, by using this setting, it becomes possible to pin
618 the stats socket to a specific set of processes, typically the first one. The
619 warning will automatically be disabled when this setting is used, whatever
620 the number of processes used.
621
Willy Tarreauabb175f2012-09-24 12:43:26 +0200622stats socket [<address:port>|<path>] [param*]
623 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
624 Connections to this socket will return various statistics outputs and even
625 allow some commands to be issued to change some runtime settings. Please
626 consult section 9.2 "Unix Socket commands" for more details.
Willy Tarreau6162db22009-10-10 17:13:00 +0200627
Willy Tarreauabb175f2012-09-24 12:43:26 +0200628 All parameters supported by "bind" lines are supported, for instance to
629 restrict access to some users or their access rights. Please consult
630 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200631
632stats timeout <timeout, in milliseconds>
633 The default timeout on the stats socket is set to 10 seconds. It is possible
634 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +0100635 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +0200636
637stats maxconn <connections>
638 By default, the stats socket is limited to 10 concurrent connections. It is
639 possible to change this value with "stats maxconn".
640
Willy Tarreau6a06a402007-07-15 20:15:28 +0200641uid <number>
642 Changes the process' user ID to <number>. It is recommended that the user ID
643 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
644 be started with superuser privileges in order to be able to switch to another
645 one. See also "gid" and "user".
646
647ulimit-n <number>
648 Sets the maximum number of per-process file-descriptors to <number>. By
649 default, it is automatically computed, so it is recommended not to use this
650 option.
651
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100652unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
653 [ group <group> ] [ gid <gid> ]
654
655 Fixes common settings to UNIX listening sockets declared in "bind" statements.
656 This is mainly used to simplify declaration of those UNIX sockets and reduce
657 the risk of errors, since those settings are most commonly required but are
658 also process-specific. The <prefix> setting can be used to force all socket
659 path to be relative to that directory. This might be needed to access another
660 component's chroot. Note that those paths are resolved before haproxy chroots
661 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
662 all have the same meaning as their homonyms used by the "bind" statement. If
663 both are specified, the "bind" statement has priority, meaning that the
664 "unix-bind" settings may be seen as process-wide default settings.
665
Willy Tarreau6a06a402007-07-15 20:15:28 +0200666user <user name>
667 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
668 See also "uid" and "group".
669
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +0200670node <name>
671 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
672
673 This statement is useful in HA configurations where two or more processes or
674 servers share the same IP address. By setting a different node-name on all
675 nodes, it becomes easy to immediately spot what server is handling the
676 traffic.
677
678description <text>
679 Add a text that describes the instance.
680
681 Please note that it is required to escape certain characters (# for example)
682 and this text is inserted into a html page so you should avoid using
683 "<" and ">" characters.
684
Willy Tarreau6a06a402007-07-15 20:15:28 +0200685
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006863.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +0200687-----------------------
688
689maxconn <number>
690 Sets the maximum per-process number of concurrent connections to <number>. It
691 is equivalent to the command-line argument "-n". Proxies will stop accepting
692 connections when this limit is reached. The "ulimit-n" parameter is
693 automatically adjusted according to this value. See also "ulimit-n".
694
Willy Tarreau81c25d02011-09-07 15:17:21 +0200695maxconnrate <number>
696 Sets the maximum per-process number of connections per second to <number>.
697 Proxies will stop accepting connections when this limit is reached. It can be
698 used to limit the global capacity regardless of each frontend capacity. It is
699 important to note that this can only be used as a service protection measure,
700 as there will not necessarily be a fair share between frontends when the
701 limit is reached, so it's a good idea to also limit each frontend to some
702 value close to its expected share. Also, lowering tune.maxaccept can improve
703 fairness.
704
William Lallemandd85f9172012-11-09 17:05:39 +0100705maxcomprate <number>
706 Sets the maximum per-process input compression rate to <number> kilobytes
707 pers second. For each session, if the maximum is reached, the compression
708 level will be decreased during the session. If the maximum is reached at the
709 beginning of a session, the session will not compress at all. If the maximum
710 is not reached, the compression level will be increased up to
711 tune.comp.maxlevel. A value of zero means there is no limit, this is the
712 default value.
713
William Lallemand072a2bf2012-11-20 17:01:01 +0100714maxcompcpuusage <number>
715 Sets the maximum CPU usage HAProxy can reach before stopping the compression
716 for new requests or decreasing the compression level of current requests.
717 It works like 'maxcomprate' but measures CPU usage instead of incoming data
718 bandwidth. The value is expressed in percent of the CPU used by haproxy. In
719 case of multiple processes (nbproc > 1), each process manages its individual
720 usage. A value of 100 disable the limit. The default value is 100. Setting
721 a lower value will prevent the compression work from slowing the whole
722 process down and from introducing high latencies.
723
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100724maxpipes <number>
725 Sets the maximum per-process number of pipes to <number>. Currently, pipes
726 are only used by kernel-based tcp splicing. Since a pipe contains two file
727 descriptors, the "ulimit-n" value will be increased accordingly. The default
728 value is maxconn/4, which seems to be more than enough for most heavy usages.
729 The splice code dynamically allocates and releases pipes, and can fall back
730 to standard copy, so setting this value too low may only impact performance.
731
Willy Tarreau403edff2012-09-06 11:58:37 +0200732maxsslconn <number>
733 Sets the maximum per-process number of concurrent SSL connections to
734 <number>. By default there is no SSL-specific limit, which means that the
735 global maxconn setting will apply to all connections. Setting this limit
736 avoids having openssl use too much memory and crash when malloc returns NULL
737 (since it unfortunately does not reliably check for such conditions). Note
738 that the limit applies both to incoming and outgoing connections, so one
739 connection which is deciphered then ciphered accounts for 2 SSL connections.
740
William Lallemand9d5f5482012-11-07 16:12:57 +0100741maxzlibmem <number>
742 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
743 When the maximum amount is reached, future sessions will not compress as long
744 as RAM is unavailable. When sets to 0, there is no limit.
William Lallemande3a7d992012-11-20 11:25:20 +0100745 The default value is 0. The value is available in bytes on the UNIX socket
746 with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is
747 "ZlibMemUsage" in bytes.
748
Willy Tarreau6a06a402007-07-15 20:15:28 +0200749noepoll
750 Disables the use of the "epoll" event polling system on Linux. It is
751 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100752 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +0200753
754nokqueue
755 Disables the use of the "kqueue" event polling system on BSD. It is
756 equivalent to the command-line argument "-dk". The next polling system
757 used will generally be "poll". See also "nopoll".
758
759nopoll
760 Disables the use of the "poll" event polling system. It is equivalent to the
761 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +0100762 It should never be needed to disable "poll" since it's available on all
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100763 platforms supported by HAProxy. See also "nokqueue" and "noepoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +0200764
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100765nosplice
766 Disables the use of kernel tcp splicing between sockets on Linux. It is
767 equivalent to the command line argument "-dS". Data will then be copied
768 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100769 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100770 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
771 be used. This option makes it easier to globally disable kernel splicing in
772 case of doubt. See also "option splice-auto", "option splice-request" and
773 "option splice-response".
774
Willy Tarreaufe255b72007-10-14 23:09:26 +0200775spread-checks <0..50, in percent>
776 Sometimes it is desirable to avoid sending health checks to servers at exact
777 intervals, for instance when many logical servers are located on the same
778 physical server. With the help of this parameter, it becomes possible to add
779 some randomness in the check interval between 0 and +/- 50%. A value between
780 2 and 5 seems to show good results. The default value remains at 0.
781
Willy Tarreau27a674e2009-08-17 07:23:33 +0200782tune.bufsize <number>
783 Sets the buffer size to this size (in bytes). Lower values allow more
784 sessions to coexist in the same amount of RAM, and higher values allow some
785 applications with very large cookies to work. The default value is 16384 and
786 can be changed at build time. It is strongly recommended not to change this
787 from the default value, as very low values will break some services such as
788 statistics, and values larger than default size will increase memory usage,
789 possibly causing the system to run out of memory. At least the global maxconn
790 parameter should be decreased by the same factor as this one is increased.
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +0400791 If HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will
792 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
793 than this size, haproxy will return HTTP 502 (Bad Gateway).
Willy Tarreau27a674e2009-08-17 07:23:33 +0200794
Willy Tarreau43961d52010-10-04 20:39:20 +0200795tune.chksize <number>
796 Sets the check buffer size to this size (in bytes). Higher values may help
797 find string or regex patterns in very large pages, though doing so may imply
798 more memory and CPU usage. The default value is 16384 and can be changed at
799 build time. It is not recommended to change this value, but to use better
800 checks whenever possible.
801
William Lallemandf3747832012-11-09 12:33:10 +0100802tune.comp.maxlevel <number>
803 Sets the maximum compression level. The compression level affects CPU
804 usage during compression. This value affects CPU usage during compression.
805 Each session using compression initializes the compression algorithm with
806 this value. The default value is 1.
807
Willy Tarreau193b8c62012-11-22 00:17:38 +0100808tune.http.cookielen <number>
809 Sets the maximum length of captured cookies. This is the maximum value that
810 the "capture cookie xxx len yyy" will be allowed to take, and any upper value
811 will automatically be truncated to this one. It is important not to set too
812 high a value because all cookie captures still allocate this size whatever
813 their configured value (they share a same pool). This value is per request
814 per response, so the memory allocated is twice this value per connection.
815 When not specified, the limit is set to 63 characters. It is recommended not
816 to change this value.
817
Willy Tarreauac1932d2011-10-24 19:14:41 +0200818tune.http.maxhdr <number>
819 Sets the maximum number of headers in a request. When a request comes with a
820 number of headers greater than this value (including the first line), it is
821 rejected with a "400 Bad Request" status code. Similarly, too large responses
822 are blocked with "502 Bad Gateway". The default value is 101, which is enough
823 for all usages, considering that the widely deployed Apache server uses the
824 same limit. It can be useful to push this limit further to temporarily allow
825 a buggy application to work by the time it gets fixed. Keep in mind that each
826 new header consumes 32bits of memory for each session, so don't push this
827 limit too high.
828
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100829tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +0100830 Sets the maximum number of consecutive connections a process may accept in a
831 row before switching to other work. In single process mode, higher numbers
832 give better performance at high connection rates. However in multi-process
833 modes, keeping a bit of fairness between processes generally is better to
834 increase performance. This value applies individually to each listener, so
835 that the number of processes a listener is bound to is taken into account.
836 This value defaults to 64. In multi-process mode, it is divided by twice
837 the number of processes the listener is bound to. Setting this value to -1
838 completely disables the limitation. It should normally not be needed to tweak
839 this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100840
841tune.maxpollevents <number>
842 Sets the maximum amount of events that can be processed at once in a call to
843 the polling system. The default value is adapted to the operating system. It
844 has been noticed that reducing it below 200 tends to slightly decrease
845 latency at the expense of network bandwidth, and increasing it above 200
846 tends to trade latency for slightly increased bandwidth.
847
Willy Tarreau27a674e2009-08-17 07:23:33 +0200848tune.maxrewrite <number>
849 Sets the reserved buffer space to this size in bytes. The reserved space is
850 used for header rewriting or appending. The first reads on sockets will never
851 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
852 bufsize, though that does not make much sense since there are rarely large
853 numbers of headers to add. Setting it too high prevents processing of large
854 requests or responses. Setting it too low prevents addition of new headers
855 to already large requests or to POST requests. It is generally wise to set it
856 to about 1024. It is automatically readjusted to half of bufsize if it is
857 larger than that. This means you don't have to worry about it when changing
858 bufsize.
859
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200860tune.pipesize <number>
861 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
862 are the default size for the system. But sometimes when using TCP splicing,
863 it can improve performance to increase pipe sizes, especially if it is
864 suspected that pipes are not filled and that many calls to splice() are
865 performed. This has an impact on the kernel's memory footprint, so this must
866 not be changed if impacts are not understood.
867
Willy Tarreaue803de22010-01-21 17:43:04 +0100868tune.rcvbuf.client <number>
869tune.rcvbuf.server <number>
870 Forces the kernel socket receive buffer size on the client or the server side
871 to the specified value in bytes. This value applies to all TCP/HTTP frontends
872 and backends. It should normally never be set, and the default size (0) lets
873 the kernel autotune this value depending on the amount of available memory.
874 However it can sometimes help to set it to very low values (eg: 4096) in
875 order to save kernel memory by preventing it from buffering too large amounts
876 of received data. Lower values will significantly increase CPU usage though.
877
878tune.sndbuf.client <number>
879tune.sndbuf.server <number>
880 Forces the kernel socket send buffer size on the client or the server side to
881 the specified value in bytes. This value applies to all TCP/HTTP frontends
882 and backends. It should normally never be set, and the default size (0) lets
883 the kernel autotune this value depending on the amount of available memory.
884 However it can sometimes help to set it to very low values (eg: 4096) in
885 order to save kernel memory by preventing it from buffering too large amounts
886 of received data. Lower values will significantly increase CPU usage though.
887 Another use case is to prevent write timeouts with extremely slow clients due
888 to the kernel waiting for a large part of the buffer to be read before
889 notifying haproxy again.
890
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100891tune.ssl.cachesize <number>
Emeric Brunaf9619d2012-11-28 18:47:52 +0100892 Sets the size of the global SSL session cache, in a number of blocks. A block
893 is large enough to contain an encoded session without peer certificate.
894 An encoded session with peer certificate is stored in multiple blocks
895 depending on the size of the peer certificate. A block use approximatively
896 200 bytes of memory. The default value may be forced at build time, otherwise
897 defaults to 20000. When the cache is full, the most idle entries are purged
898 and reassigned. Higher values reduce the occurrence of such a purge, hence
899 the number of CPU-intensive SSL handshakes by ensuring that all users keep
900 their session as long as possible. All entries are pre-allocated upon startup
Emeric Brun22890a12012-12-28 14:41:32 +0100901 and are shared between all processes if "nbproc" is greater than 1. Setting
902 this value to 0 disables the SSL session cache.
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100903
Emeric Brun4f65bff2012-11-16 15:11:00 +0100904tune.ssl.lifetime <timeout>
905 Sets how long a cached SSL session may remain valid. This time is expressed
906 in seconds and defaults to 300 (5 mn). It is important to understand that it
907 does not guarantee that sessions will last that long, because if the cache is
908 full, the longest idle sessions will be purged despite their configured
909 lifetime. The real usefulness of this setting is to prevent sessions from
910 being used for too long.
911
Willy Tarreaubfd59462013-02-21 07:46:09 +0100912tune.ssl.maxrecord <number>
913 Sets the maximum amount of bytes passed to SSL_write() at a time. Default
914 value 0 means there is no limit. Over SSL/TLS, the client can decipher the
915 data only once it has received a full record. With large records, it means
916 that clients might have to download up to 16kB of data before starting to
917 process them. Limiting the value can improve page load times on browsers
918 located over high latency or low bandwidth networks. It is suggested to find
919 optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over
920 Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled),
921 keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and
922 2859 gave good results during tests. Use "strace -e trace=write" to find the
923 best value.
924
William Lallemanda509e4c2012-11-07 16:54:34 +0100925tune.zlib.memlevel <number>
926 Sets the memLevel parameter in zlib initialization for each session. It
927 defines how much memory should be allocated for the intenal compression
928 state. A value of 1 uses minimum memory but is slow and reduces compression
929 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
930 between 1 and 9. The default value is 8.
931
932tune.zlib.windowsize <number>
933 Sets the window size (the size of the history buffer) as a parameter of the
934 zlib initialization for each session. Larger values of this parameter result
935 in better compression at the expense of memory usage. Can be a value between
936 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200937
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009383.3. Debugging
939--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200940
941debug
942 Enables debug mode which dumps to stdout all exchanges, and disables forking
943 into background. It is the equivalent of the command-line argument "-d". It
944 should never be used in a production configuration since it may prevent full
945 system startup.
946
947quiet
948 Do not display any message during startup. It is equivalent to the command-
949 line argument "-q".
950
Emeric Brunf099e792010-09-27 12:05:28 +0200951
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01009523.4. Userlists
953--------------
954It is possible to control access to frontend/backend/listen sections or to
955http stats by allowing only authenticated and authorized users. To do this,
956it is required to create at least one userlist and to define users.
957
958userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +0100959 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100960 used to store authentication & authorization data for independent customers.
961
962group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +0100963 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100964 attach users to this group by using a comma separated list of names
965 proceeded by "users" keyword.
966
Cyril Bontéf0c60612010-02-06 14:44:47 +0100967user <username> [password|insecure-password <password>]
968 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100969 Adds user <username> to the current userlist. Both secure (encrypted) and
970 insecure (unencrypted) passwords can be used. Encrypted passwords are
Cyril Bonté78caf842010-03-10 22:41:43 +0100971 evaluated using the crypt(3) function so depending of the system's
972 capabilities, different algorithms are supported. For example modern Glibc
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100973 based Linux system supports MD5, SHA-256, SHA-512 and of course classic,
974 DES-based method of crypting passwords.
975
976
977 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +0100978 userlist L1
979 group G1 users tiger,scott
980 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100981
Cyril Bontéf0c60612010-02-06 14:44:47 +0100982 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
983 user scott insecure-password elgato
984 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100985
Cyril Bontéf0c60612010-02-06 14:44:47 +0100986 userlist L2
987 group G1
988 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100989
Cyril Bontéf0c60612010-02-06 14:44:47 +0100990 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
991 user scott insecure-password elgato groups G1,G2
992 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100993
994 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200995
Emeric Brunf099e792010-09-27 12:05:28 +0200996
9973.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +0200998----------
Emeric Brunf099e792010-09-27 12:05:28 +0200999It is possible to synchronize server entries in stick tables between several
1000haproxy instances over TCP connections in a multi-master fashion. Each instance
1001pushes its local updates and insertions to remote peers. Server IDs are used to
1002identify servers remotely, so it is important that configurations look similar
1003or at least that the same IDs are forced on each server on all participants.
1004Interrupted exchanges are automatically detected and recovered from the last
1005known point. In addition, during a soft restart, the old process connects to
1006the new one using such a TCP connection to push all its entries before the new
1007process tries to connect to other peers. That ensures very fast replication
1008during a reload, it typically takes a fraction of a second even for large
1009tables.
1010
1011peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001012 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +02001013 which is referenced by one or more stick-tables.
1014
1015peer <peername> <ip>:<port>
1016 Defines a peer inside a peers section.
1017 If <peername> is set to the local peer name (by default hostname, or forced
1018 using "-L" command line option), haproxy will listen for incoming remote peer
1019 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
1020 to join the remote peer, and <peername> is used at the protocol level to
1021 identify and validate the remote peer on the server side.
1022
1023 During a soft restart, local peer <ip>:<port> is used by the old instance to
1024 connect the new one and initiate a complete replication (teaching process).
1025
1026 It is strongly recommended to have the exact same peers declaration on all
1027 peers and to only rely on the "-L" command line argument to change the local
1028 peer name. This makes it easier to maintain coherent configuration files
1029 across all peers.
1030
Willy Tarreaudad36a32013-03-11 01:20:04 +01001031 Any part of the address string may reference any number of environment
1032 variables by preceding their name with a dollar sign ('$') and optionally
1033 enclosing them with braces ('{}'), similarly to what is done in Bourne shell.
1034
Cyril Bontédc4d9032012-04-08 21:57:39 +02001035 Example:
Emeric Brunf099e792010-09-27 12:05:28 +02001036 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001037 peer haproxy1 192.168.0.1:1024
1038 peer haproxy2 192.168.0.2:1024
1039 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +02001040
1041 backend mybackend
1042 mode tcp
1043 balance roundrobin
1044 stick-table type ip size 20k peers mypeers
1045 stick on src
1046
Willy Tarreauf7b30a92010-12-06 22:59:17 +01001047 server srv1 192.168.0.30:80
1048 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +02001049
1050
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010514. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +02001052----------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001053
Willy Tarreau6a06a402007-07-15 20:15:28 +02001054Proxy configuration can be located in a set of sections :
1055 - defaults <name>
1056 - frontend <name>
1057 - backend <name>
1058 - listen <name>
1059
1060A "defaults" section sets default parameters for all other sections following
1061its declaration. Those default parameters are reset by the next "defaults"
1062section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +01001063section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001064
1065A "frontend" section describes a set of listening sockets accepting client
1066connections.
1067
1068A "backend" section describes a set of servers to which the proxy will connect
1069to forward incoming connections.
1070
1071A "listen" section defines a complete proxy with its frontend and backend
1072parts combined in one section. It is generally useful for TCP-only traffic.
1073
Willy Tarreau0ba27502007-12-24 16:55:16 +01001074All proxy names must be formed from upper and lower case letters, digits,
1075'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
1076case-sensitive, which means that "www" and "WWW" are two different proxies.
1077
1078Historically, all proxy names could overlap, it just caused troubles in the
1079logs. Since the introduction of content switching, it is mandatory that two
1080proxies with overlapping capabilities (frontend/backend) have different names.
1081However, it is still permitted that a frontend and a backend share the same
1082name, as this configuration seems to be commonly encountered.
1083
1084Right now, two major proxy modes are supported : "tcp", also known as layer 4,
1085and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001086bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01001087protocol, and can interact with it by allowing, blocking, switching, adding,
1088modifying, or removing arbitrary contents in requests or responses, based on
1089arbitrary criteria.
1090
Willy Tarreau0ba27502007-12-24 16:55:16 +01001091
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010924.1. Proxy keywords matrix
1093--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001094
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001095The following list of keywords is supported. Most of them may only be used in a
1096limited set of section types. Some of them are marked as "deprecated" because
1097they are inherited from an old syntax which may be confusing or functionally
1098limited, and there are new recommended keywords to replace them. Keywords
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001099marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001100option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02001101and must be disabled for a specific instance. Such options may also be prefixed
1102with "default" in order to restore default settings regardless of what has been
1103specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001104
Willy Tarreau6a06a402007-07-15 20:15:28 +02001105
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001106 keyword defaults frontend listen backend
1107------------------------------------+----------+----------+---------+---------
1108acl - X X X
1109appsession - - X X
1110backlog X X X -
1111balance X - X X
1112bind - X X -
1113bind-process X X X X
1114block - X X X
1115capture cookie - X X -
1116capture request header - X X -
1117capture response header - X X -
1118clitimeout (deprecated) X X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02001119compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001120contimeout (deprecated) X - X X
1121cookie X - X X
1122default-server X - X X
1123default_backend X X X -
1124description - X X X
1125disabled X X X X
1126dispatch - - X X
1127enabled X X X X
1128errorfile X X X X
1129errorloc X X X X
1130errorloc302 X X X X
1131-- keyword -------------------------- defaults - frontend - listen -- backend -
1132errorloc303 X X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001133force-persist - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001134fullconn X - X X
1135grace X X X X
1136hash-type X - X X
1137http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +01001138http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02001139http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001140http-request - X X X
1141id - X X X
Cyril Bonté0d4bf012010-04-25 23:21:46 +02001142ignore-persist - X X X
William Lallemand0f99e342011-10-12 17:50:54 +02001143log (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001144maxconn X X X -
1145mode X X X X
1146monitor fail - X X -
1147monitor-net X X X -
1148monitor-uri X X X -
1149option abortonclose (*) X - X X
1150option accept-invalid-http-request (*) X X X -
1151option accept-invalid-http-response (*) X - X X
1152option allbackups (*) X - X X
1153option checkcache (*) X - X X
1154option clitcpka (*) X X X -
1155option contstats (*) X X X -
1156option dontlog-normal (*) X X X -
1157option dontlognull (*) X X X -
1158option forceclose (*) X X X X
1159-- keyword -------------------------- defaults - frontend - listen -- backend -
1160option forwardfor X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02001161option http-no-delay (*) X X X X
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02001162option http-pretend-keepalive (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001163option http-server-close (*) X X X X
1164option http-use-proxy-header (*) X X X -
1165option httpchk X - X X
1166option httpclose (*) X X X X
1167option httplog X X X X
1168option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001169option independent-streams (*) X X X X
Simon Hormana2b9dad2013-02-12 10:45:54 +09001170option lb-agent-chk X - X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02001171option ldap-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001172option log-health-checks (*) X - X X
1173option log-separate-errors (*) X X X -
1174option logasap (*) X X X -
1175option mysql-check X - X X
Rauf Kuliyev38b41562011-01-04 15:14:13 +01001176option pgsql-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001177option nolinger (*) X X X X
1178option originalto X X X X
1179option persist (*) X - X X
1180option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02001181option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001182option smtpchk X - X X
1183option socket-stats (*) X X X -
1184option splice-auto (*) X X X X
1185option splice-request (*) X X X X
1186option splice-response (*) X X X X
1187option srvtcpka (*) X - X X
1188option ssl-hello-chk X - X X
1189-- keyword -------------------------- defaults - frontend - listen -- backend -
1190option tcp-smart-accept (*) X X X -
1191option tcp-smart-connect (*) X - X X
1192option tcpka X X X X
1193option tcplog X X X X
1194option transparent (*) X - X X
1195persist rdp-cookie X - X X
1196rate-limit sessions X X X -
1197redirect - X X X
1198redisp (deprecated) X - X X
1199redispatch (deprecated) X - X X
1200reqadd - X X X
1201reqallow - X X X
1202reqdel - X X X
1203reqdeny - X X X
1204reqiallow - X X X
1205reqidel - X X X
1206reqideny - X X X
1207reqipass - X X X
1208reqirep - X X X
1209reqisetbe - X X X
1210reqitarpit - X X X
1211reqpass - X X X
1212reqrep - X X X
1213-- keyword -------------------------- defaults - frontend - listen -- backend -
1214reqsetbe - X X X
1215reqtarpit - X X X
1216retries X - X X
1217rspadd - X X X
1218rspdel - X X X
1219rspdeny - X X X
1220rspidel - X X X
1221rspideny - X X X
1222rspirep - X X X
1223rsprep - X X X
1224server - - X X
1225source X - X X
1226srvtimeout (deprecated) X - X X
Cyril Bonté66c327d2010-10-12 00:14:37 +02001227stats admin - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001228stats auth X - X X
1229stats enable X - X X
1230stats hide-version X - X X
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02001231stats http-request - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001232stats realm X - X X
1233stats refresh X - X X
1234stats scope X - X X
1235stats show-desc X - X X
1236stats show-legends X - X X
1237stats show-node X - X X
1238stats uri X - X X
1239-- keyword -------------------------- defaults - frontend - listen -- backend -
1240stick match - - X X
1241stick on - - X X
1242stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02001243stick store-response - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001244stick-table - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02001245tcp-request connection - X X -
1246tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02001247tcp-request inspect-delay - X X X
Emeric Brun0a3b67f2010-09-24 15:34:53 +02001248tcp-response content - - X X
1249tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001250timeout check X - X X
1251timeout client X X X -
1252timeout clitimeout (deprecated) X X X -
1253timeout connect X - X X
1254timeout contimeout (deprecated) X - X X
1255timeout http-keep-alive X X X X
1256timeout http-request X X X X
1257timeout queue X - X X
1258timeout server X - X X
1259timeout srvtimeout (deprecated) X - X X
1260timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02001261timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001262transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01001263unique-id-format X X X -
1264unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001265use_backend - X X -
Willy Tarreau4a5cade2012-04-05 21:09:48 +02001266use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01001267------------------------------------+----------+----------+---------+---------
1268 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02001269
Willy Tarreau0ba27502007-12-24 16:55:16 +01001270
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012714.2. Alphabetically sorted keywords reference
1272---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01001273
1274This section provides a description of each keyword and its usage.
1275
1276
1277acl <aclname> <criterion> [flags] [operator] <value> ...
1278 Declare or complete an access list.
1279 May be used in sections : defaults | frontend | listen | backend
1280 no | yes | yes | yes
1281 Example:
1282 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1283 acl invalid_src src_port 0:1023
1284 acl local_dst hdr(host) -i localhost
1285
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001286 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001287
1288
Cyril Bontéb21570a2009-11-29 20:04:48 +01001289appsession <cookie> len <length> timeout <holdtime>
1290 [request-learn] [prefix] [mode <path-parameters|query-string>]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001291 Define session stickiness on an existing application cookie.
1292 May be used in sections : defaults | frontend | listen | backend
1293 no | no | yes | yes
1294 Arguments :
1295 <cookie> this is the name of the cookie used by the application and which
1296 HAProxy will have to learn for each new session.
1297
Cyril Bontéb21570a2009-11-29 20:04:48 +01001298 <length> this is the max number of characters that will be memorized and
Willy Tarreau0ba27502007-12-24 16:55:16 +01001299 checked in each cookie value.
1300
1301 <holdtime> this is the time after which the cookie will be removed from
1302 memory if unused. If no unit is specified, this time is in
1303 milliseconds.
1304
Cyril Bontébf47aeb2009-10-15 00:15:40 +02001305 request-learn
1306 If this option is specified, then haproxy will be able to learn
1307 the cookie found in the request in case the server does not
1308 specify any in response. This is typically what happens with
1309 PHPSESSID cookies, or when haproxy's session expires before
1310 the application's session and the correct server is selected.
1311 It is recommended to specify this option to improve reliability.
1312
Cyril Bontéb21570a2009-11-29 20:04:48 +01001313 prefix When this option is specified, haproxy will match on the cookie
1314 prefix (or URL parameter prefix). The appsession value is the
1315 data following this prefix.
1316
1317 Example :
1318 appsession ASPSESSIONID len 64 timeout 3h prefix
1319
1320 This will match the cookie ASPSESSIONIDXXXX=XXXXX,
1321 the appsession value will be XXXX=XXXXX.
1322
1323 mode This option allows to change the URL parser mode.
1324 2 modes are currently supported :
1325 - path-parameters :
1326 The parser looks for the appsession in the path parameters
1327 part (each parameter is separated by a semi-colon), which is
1328 convenient for JSESSIONID for example.
1329 This is the default mode if the option is not set.
1330 - query-string :
1331 In this mode, the parser will look for the appsession in the
1332 query string.
1333
Willy Tarreau0ba27502007-12-24 16:55:16 +01001334 When an application cookie is defined in a backend, HAProxy will check when
1335 the server sets such a cookie, and will store its value in a table, and
1336 associate it with the server's identifier. Up to <length> characters from
1337 the value will be retained. On each connection, haproxy will look for this
Cyril Bontéb21570a2009-11-29 20:04:48 +01001338 cookie both in the "Cookie:" headers, and as a URL parameter (depending on
1339 the mode used). If a known value is found, the client will be directed to the
1340 server associated with this value. Otherwise, the load balancing algorithm is
Willy Tarreau0ba27502007-12-24 16:55:16 +01001341 applied. Cookies are automatically removed from memory when they have been
1342 unused for a duration longer than <holdtime>.
1343
1344 The definition of an application cookie is limited to one per backend.
1345
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001346 Note : Consider not using this feature in multi-process mode (nbproc > 1)
1347 unless you know what you do : memory is not shared between the
1348 processes, which can result in random behaviours.
1349
Willy Tarreau0ba27502007-12-24 16:55:16 +01001350 Example :
1351 appsession JSESSIONID len 52 timeout 3h
1352
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01001353 See also : "cookie", "capture cookie", "balance", "stick", "stick-table",
1354 "ignore-persist", "nbproc" and "bind-process".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001355
1356
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001357backlog <conns>
1358 Give hints to the system about the approximate listen backlog desired size
1359 May be used in sections : defaults | frontend | listen | backend
1360 yes | yes | yes | no
1361 Arguments :
1362 <conns> is the number of pending connections. Depending on the operating
1363 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02001364 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01001365
1366 In order to protect against SYN flood attacks, one solution is to increase
1367 the system's SYN backlog size. Depending on the system, sometimes it is just
1368 tunable via a system parameter, sometimes it is not adjustable at all, and
1369 sometimes the system relies on hints given by the application at the time of
1370 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
1371 to the listen() syscall. On systems which can make use of this value, it can
1372 sometimes be useful to be able to specify a different value, hence this
1373 backlog parameter.
1374
1375 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
1376 used as a hint and the system accepts up to the smallest greater power of
1377 two, and never more than some limits (usually 32768).
1378
1379 See also : "maxconn" and the target operating system's tuning guide.
1380
1381
Willy Tarreau0ba27502007-12-24 16:55:16 +01001382balance <algorithm> [ <arguments> ]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001383balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001384 Define the load balancing algorithm to be used in a backend.
1385 May be used in sections : defaults | frontend | listen | backend
1386 yes | no | yes | yes
1387 Arguments :
1388 <algorithm> is the algorithm used to select a server when doing load
1389 balancing. This only applies when no persistence information
1390 is available, or when a connection is redispatched to another
1391 server. <algorithm> may be one of the following :
1392
1393 roundrobin Each server is used in turns, according to their weights.
1394 This is the smoothest and fairest algorithm when the server's
1395 processing time remains equally distributed. This algorithm
1396 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02001397 on the fly for slow starts for instance. It is limited by
1398 design to 4128 active servers per backend. Note that in some
1399 large farms, when a server becomes up after having been down
1400 for a very short time, it may sometimes take a few hundreds
1401 requests for it to be re-integrated into the farm and start
1402 receiving traffic. This is normal, though very rare. It is
1403 indicated here in case you would have the chance to observe
1404 it, so that you don't worry.
1405
1406 static-rr Each server is used in turns, according to their weights.
1407 This algorithm is as similar to roundrobin except that it is
1408 static, which means that changing a server's weight on the
1409 fly will have no effect. On the other hand, it has no design
1410 limitation on the number of servers, and when a server goes
1411 up, it is always immediately reintroduced into the farm, once
1412 the full map is recomputed. It also uses slightly less CPU to
1413 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01001414
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01001415 leastconn The server with the lowest number of connections receives the
1416 connection. Round-robin is performed within groups of servers
1417 of the same load to ensure that all servers will be used. Use
1418 of this algorithm is recommended where very long sessions are
1419 expected, such as LDAP, SQL, TSE, etc... but is not very well
1420 suited for protocols using short sessions such as HTTP. This
1421 algorithm is dynamic, which means that server weights may be
1422 adjusted on the fly for slow starts for instance.
1423
Willy Tarreauf09c6602012-02-13 17:12:08 +01001424 first The first server with available connection slots receives the
1425 connection. The servers are choosen from the lowest numeric
1426 identifier to the highest (see server parameter "id"), which
1427 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02001428 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01001429 not make sense to use this algorithm without setting maxconn.
1430 The purpose of this algorithm is to always use the smallest
1431 number of servers so that extra servers can be powered off
1432 during non-intensive hours. This algorithm ignores the server
1433 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02001434 or IMAP than HTTP, though it can be useful there too. In
1435 order to use this algorithm efficiently, it is recommended
1436 that a cloud controller regularly checks server usage to turn
1437 them off when unused, and regularly checks backend queue to
1438 turn new servers on when the queue inflates. Alternatively,
1439 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01001440
Willy Tarreau0ba27502007-12-24 16:55:16 +01001441 source The source IP address is hashed and divided by the total
1442 weight of the running servers to designate which server will
1443 receive the request. This ensures that the same client IP
1444 address will always reach the same server as long as no
1445 server goes down or up. If the hash result changes due to the
1446 number of running servers changing, many clients will be
1447 directed to a different server. This algorithm is generally
1448 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001449 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01001450 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001451 static by default, which means that changing a server's
1452 weight on the fly will have no effect, but this can be
1453 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001454
Oskar Stolc8dc41842012-05-19 10:19:54 +01001455 uri This algorithm hashes either the left part of the URI (before
1456 the question mark) or the whole URI (if the "whole" parameter
1457 is present) and divides the hash value by the total weight of
1458 the running servers. The result designates which server will
1459 receive the request. This ensures that the same URI will
1460 always be directed to the same server as long as no server
1461 goes up or down. This is used with proxy caches and
1462 anti-virus proxies in order to maximize the cache hit rate.
1463 Note that this algorithm may only be used in an HTTP backend.
1464 This algorithm is static by default, which means that
1465 changing a server's weight on the fly will have no effect,
1466 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001467
Oskar Stolc8dc41842012-05-19 10:19:54 +01001468 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001469 "depth", both followed by a positive integer number. These
1470 options may be helpful when it is needed to balance servers
1471 based on the beginning of the URI only. The "len" parameter
1472 indicates that the algorithm should only consider that many
1473 characters at the beginning of the URI to compute the hash.
1474 Note that having "len" set to 1 rarely makes sense since most
1475 URIs start with a leading "/".
1476
1477 The "depth" parameter indicates the maximum directory depth
1478 to be used to compute the hash. One level is counted for each
1479 slash in the request. If both parameters are specified, the
1480 evaluation stops when either is reached.
1481
Willy Tarreau0ba27502007-12-24 16:55:16 +01001482 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001483 the query string of each HTTP GET request.
1484
1485 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02001486 request entity will be searched for the parameter argument,
1487 when it is not found in a query string after a question mark
1488 ('?') in the URL. Optionally, specify a number of octets to
1489 wait for before attempting to search the message body. If the
1490 entity can not be searched, then round robin is used for each
1491 request. For instance, if your clients always send the LB
1492 parameter in the first 128 bytes, then specify that. The
1493 default is 48. The entity data will not be scanned until the
1494 required number of octets have arrived at the gateway, this
1495 is the minimum of: (default/max_wait, Content-Length or first
1496 chunk length). If Content-Length is missing or zero, it does
1497 not need to wait for more data than the client promised to
1498 send. When Content-Length is present and larger than
1499 <max_wait>, then waiting is limited to <max_wait> and it is
1500 assumed that this will be enough data to search for the
1501 presence of the parameter. In the unlikely event that
1502 Transfer-Encoding: chunked is used, only the first chunk is
1503 scanned. Parameter values separated by a chunk boundary, may
1504 be randomly balanced if at all.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001505
1506 If the parameter is found followed by an equal sign ('=') and
1507 a value, then the value is hashed and divided by the total
1508 weight of the running servers. The result designates which
1509 server will receive the request.
1510
1511 This is used to track user identifiers in requests and ensure
1512 that a same user ID will always be sent to the same server as
1513 long as no server goes up or down. If no value is found or if
1514 the parameter is not found, then a round robin algorithm is
1515 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001516 backend. This algorithm is static by default, which means
1517 that changing a server's weight on the fly will have no
1518 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001519
Cyril Bontédc4d9032012-04-08 21:57:39 +02001520 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
1521 request. Just as with the equivalent ACL 'hdr()' function,
1522 the header name in parenthesis is not case sensitive. If the
1523 header is absent or if it does not contain any value, the
1524 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01001525
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001526 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01001527 reducing the hash algorithm to the main domain part with some
1528 specific headers such as 'Host'. For instance, in the Host
1529 value "haproxy.1wt.eu", only "1wt" will be considered.
1530
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001531 This algorithm is static by default, which means that
1532 changing a server's weight on the fly will have no effect,
1533 but this can be changed using "hash-type".
1534
Emeric Brun736aa232009-06-30 17:56:00 +02001535 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02001536 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02001537 The RDP cookie <name> (or "mstshash" if omitted) will be
1538 looked up and hashed for each incoming TCP request. Just as
1539 with the equivalent ACL 'req_rdp_cookie()' function, the name
1540 is not case-sensitive. This mechanism is useful as a degraded
1541 persistence mode, as it makes it possible to always send the
1542 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001543 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02001544 used instead.
1545
1546 Note that for this to work, the frontend must ensure that an
1547 RDP cookie is already present in the request buffer. For this
1548 you must use 'tcp-request content accept' rule combined with
1549 a 'req_rdp_cookie_cnt' ACL.
1550
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001551 This algorithm is static by default, which means that
1552 changing a server's weight on the fly will have no effect,
1553 but this can be changed using "hash-type".
1554
Cyril Bontédc4d9032012-04-08 21:57:39 +02001555 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09001556
Willy Tarreau0ba27502007-12-24 16:55:16 +01001557 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001558 algorithms. Right now, only "url_param" and "uri" support an
1559 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001560
Marek Majkowski9c30fc12008-04-27 23:25:55 +02001561 balance uri [len <len>] [depth <depth>]
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001562 balance url_param <param> [check_post [<max_wait>]]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001563
Willy Tarreau3cd9af22009-03-15 14:06:41 +01001564 The load balancing algorithm of a backend is set to roundrobin when no other
1565 algorithm, mode nor option have been set. The algorithm may only be set once
1566 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001567
1568 Examples :
1569 balance roundrobin
1570 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001571 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01001572 balance hdr(User-Agent)
1573 balance hdr(host)
1574 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001575
1576 Note: the following caveats and limitations on using the "check_post"
1577 extension with "url_param" must be considered :
1578
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001579 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001580 to determine if the parameters will be found in the body or entity which
1581 may contain binary data. Therefore another method may be required to
1582 restrict consideration of POST requests that have no URL parameters in
1583 the body. (see acl reqideny http_end)
1584
1585 - using a <max_wait> value larger than the request buffer size does not
1586 make sense and is useless. The buffer size is set at build time, and
1587 defaults to 16 kB.
1588
1589 - Content-Encoding is not supported, the parameter search will probably
1590 fail; and load balancing will fall back to Round Robin.
1591
1592 - Expect: 100-continue is not supported, load balancing will fall back to
1593 Round Robin.
1594
1595 - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk.
1596 If the entire parameter value is not present in the first chunk, the
1597 selection of server is undefined (actually, defined by how little
1598 actually appeared in the first chunk).
1599
1600 - This feature does not support generation of a 100, 411 or 501 response.
1601
1602 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001603 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001604 white space or control characters are found, indicating the end of what
1605 might be a URL parameter list. This is probably not a concern with SGML
1606 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001607
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02001608 See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and
1609 "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001610
1611
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001612bind [<address>]:<port_range> [, ...] [param*]
1613bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01001614 Define one or several listening addresses and/or ports in a frontend.
1615 May be used in sections : defaults | frontend | listen | backend
1616 no | yes | yes | no
1617 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001618 <address> is optional and can be a host name, an IPv4 address, an IPv6
1619 address, or '*'. It designates the address the frontend will
1620 listen on. If unset, all IPv4 addresses of the system will be
1621 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01001622 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreau24709282013-03-10 21:32:12 +01001623 Optionally, an address family prefix may be used before the
1624 address to force the family regardless of the address format,
1625 which can be useful to specify a path to a unix socket with
1626 no slash ('/'). Currently supported prefixes are :
1627 - 'ipv4@' -> address is always IPv4
1628 - 'ipv6@' -> address is always IPv6
1629 - 'unix@' -> address is a path to a local unix socket
Willy Tarreau40aa0702013-03-10 23:51:38 +01001630 - 'fd@<n>' -> use file descriptor <n> inherited from the
1631 parent. The fd must be bound and may or may not already
1632 be listening.
Willy Tarreaudad36a32013-03-11 01:20:04 +01001633 Any part of the address string may reference any number of
1634 environment variables by preceding their name with a dollar
1635 sign ('$') and optionally enclosing them with braces ('{}'),
1636 similarly to what is done in Bourne shell.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01001637
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001638 <port_range> is either a unique TCP port, or a port range for which the
1639 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001640 above. The port is mandatory for TCP listeners. Note that in
1641 the case of an IPv6 address, the port is always the number
1642 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001643 - a numerical port (ex: '80')
1644 - a dash-delimited ports range explicitly stating the lower
1645 and upper bounds (ex: '2000-2100') which are included in
1646 the range.
1647
1648 Particular care must be taken against port ranges, because
1649 every <address:port> couple consumes one socket (= a file
1650 descriptor), so it's easy to consume lots of descriptors
1651 with a simple range, and to run out of sockets. Also, each
1652 <address:port> couple must be used only once among all
1653 instances running on a same system. Please note that binding
1654 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04001655 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01001656 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001657
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001658 <path> is a UNIX socket path beginning with a slash ('/'). This is
1659 alternative to the TCP listening port. Haproxy will then
1660 receive UNIX connections on the socket located at this place.
1661 The path must begin with a slash and by default is absolute.
1662 It can be relative to the prefix defined by "unix-bind" in
1663 the global section. Note that the total length of the prefix
1664 followed by the socket path cannot exceed some system limits
1665 for UNIX sockets, which commonly are set to 107 characters.
1666
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001667 <param*> is a list of parameters common to all sockets declared on the
1668 same line. These numerous parameters depend on OS and build
1669 options and have a complete section dedicated to them. Please
1670 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001671
Willy Tarreau0ba27502007-12-24 16:55:16 +01001672 It is possible to specify a list of address:port combinations delimited by
1673 commas. The frontend will then listen on all of these addresses. There is no
1674 fixed limit to the number of addresses and ports which can be listened on in
1675 a frontend, as well as there is no limit to the number of "bind" statements
1676 in a frontend.
1677
1678 Example :
1679 listen http_proxy
1680 bind :80,:443
1681 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001682 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01001683
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001684 listen http_https_proxy
1685 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02001686 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02001687
Willy Tarreau24709282013-03-10 21:32:12 +01001688 listen http_https_proxy_explicit
1689 bind ipv6@:80
1690 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
1691 bind unix@ssl-frontend.sock user root mode 600 accept-proxy
1692
Willy Tarreaudad36a32013-03-11 01:20:04 +01001693 listen external_bind_app1
1694 bind fd@${FD_APP1}
1695
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001696 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02001697 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001698
1699
Willy Tarreau110ecc12012-11-15 17:50:01 +01001700bind-process [ all | odd | even | <number 1-32>[-<number 1-32>] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001701 Limit visibility of an instance to a certain set of processes numbers.
1702 May be used in sections : defaults | frontend | listen | backend
1703 yes | yes | yes | yes
1704 Arguments :
1705 all All process will see this instance. This is the default. It
1706 may be used to override a default value.
1707
1708 odd This instance will be enabled on processes 1,3,5,...31. This
1709 option may be combined with other numbers.
1710
1711 even This instance will be enabled on processes 2,4,6,...32. This
1712 option may be combined with other numbers. Do not use it
1713 with less than 2 processes otherwise some instances might be
1714 missing from all processes.
1715
Willy Tarreau110ecc12012-11-15 17:50:01 +01001716 number The instance will be enabled on this process number or range,
1717 whose values must all be between 1 and 32. You must be
1718 careful not to reference a process number greater than the
1719 configured global.nbproc, otherwise some instances might be
1720 missing from all processes.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001721
1722 This keyword limits binding of certain instances to certain processes. This
1723 is useful in order not to have too many processes listening to the same
1724 ports. For instance, on a dual-core machine, it might make sense to set
1725 'nbproc 2' in the global section, then distributes the listeners among 'odd'
1726 and 'even' instances.
1727
1728 At the moment, it is not possible to reference more than 32 processes using
1729 this keyword, but this should be more than enough for most setups. Please
1730 note that 'all' really means all processes and is not limited to the first
1731 32.
1732
1733 If some backends are referenced by frontends bound to other processes, the
1734 backend automatically inherits the frontend's processes.
1735
1736 Example :
1737 listen app_ip1
1738 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001739 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001740
1741 listen app_ip2
1742 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001743 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001744
1745 listen management
1746 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02001747 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001748
Willy Tarreau110ecc12012-11-15 17:50:01 +01001749 listen management
1750 bind 10.0.0.4:80
1751 bind-process 1-4
1752
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01001753 See also : "nbproc" in global section.
1754
1755
Willy Tarreau0ba27502007-12-24 16:55:16 +01001756block { if | unless } <condition>
1757 Block a layer 7 request if/unless a condition is matched
1758 May be used in sections : defaults | frontend | listen | backend
1759 no | yes | yes | yes
1760
1761 The HTTP request will be blocked very early in the layer 7 processing
1762 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001763 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02001764 typically used to deny access to certain sensitive resources if some
Willy Tarreau0ba27502007-12-24 16:55:16 +01001765 conditions are met or not met. There is no fixed limit to the number of
1766 "block" statements per instance.
1767
1768 Example:
1769 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
1770 acl invalid_src src_port 0:1023
1771 acl local_dst hdr(host) -i localhost
1772 block if invalid_src || local_dst
1773
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001774 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001775
1776
1777capture cookie <name> len <length>
1778 Capture and log a cookie in the request and in the response.
1779 May be used in sections : defaults | frontend | listen | backend
1780 no | yes | yes | no
1781 Arguments :
1782 <name> is the beginning of the name of the cookie to capture. In order
1783 to match the exact name, simply suffix the name with an equal
1784 sign ('='). The full name will appear in the logs, which is
1785 useful with application servers which adjust both the cookie name
1786 and value (eg: ASPSESSIONXXXXX).
1787
1788 <length> is the maximum number of characters to report in the logs, which
1789 include the cookie name, the equal sign and the value, all in the
1790 standard "name=value" form. The string will be truncated on the
1791 right if it exceeds <length>.
1792
1793 Only the first cookie is captured. Both the "cookie" request headers and the
1794 "set-cookie" response headers are monitored. This is particularly useful to
1795 check for application bugs causing session crossing or stealing between
1796 users, because generally the user's cookies can only change on a login page.
1797
1798 When the cookie was not presented by the client, the associated log column
1799 will report "-". When a request does not cause a cookie to be assigned by the
1800 server, a "-" is reported in the response column.
1801
1802 The capture is performed in the frontend only because it is necessary that
1803 the log format does not change for a given frontend depending on the
1804 backends. This may change in the future. Note that there can be only one
Willy Tarreau193b8c62012-11-22 00:17:38 +01001805 "capture cookie" statement in a frontend. The maximum capture length is set
1806 by the global "tune.http.cookielen" setting and defaults to 63 characters. It
1807 is not possible to specify a capture in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001808
1809 Example:
1810 capture cookie ASPSESSION len 32
1811
1812 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001813 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001814
1815
1816capture request header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01001817 Capture and log the last occurrence of the specified request header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001818 May be used in sections : defaults | frontend | listen | backend
1819 no | yes | yes | no
1820 Arguments :
1821 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001822 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001823 appear in the requests, with the first letter of each word in
1824 upper case. The header name will not appear in the logs, only the
1825 value is reported, but the position in the logs is respected.
1826
1827 <length> is the maximum number of characters to extract from the value and
1828 report in the logs. The string will be truncated on the right if
1829 it exceeds <length>.
1830
Willy Tarreau4460d032012-11-21 23:37:37 +01001831 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001832 value will be added to the logs between braces ('{}'). If multiple headers
1833 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001834 in the same order they were declared in the configuration. Non-existent
1835 headers will be logged just as an empty string. Common uses for request
1836 header captures include the "Host" field in virtual hosting environments, the
1837 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001838 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001839 environments to find where the request came from.
1840
1841 Note that when capturing headers such as "User-agent", some spaces may be
1842 logged, making the log analysis more difficult. Thus be careful about what
1843 you log if you know your log parser is not smart enough to rely on the
1844 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001845
Willy Tarreau0900abb2012-11-22 00:21:46 +01001846 There is no limit to the number of captured request headers nor to their
1847 length, though it is wise to keep them low to limit memory usage per session.
1848 In order to keep log format consistent for a same frontend, header captures
1849 can only be declared in a frontend. It is not possible to specify a capture
1850 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001851
1852 Example:
1853 capture request header Host len 15
1854 capture request header X-Forwarded-For len 15
1855 capture request header Referrer len 15
1856
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001857 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001858 about logging.
1859
1860
1861capture response header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01001862 Capture and log the last occurrence of the specified response header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001863 May be used in sections : defaults | frontend | listen | backend
1864 no | yes | yes | no
1865 Arguments :
1866 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001867 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01001868 appear in the response, with the first letter of each word in
1869 upper case. The header name will not appear in the logs, only the
1870 value is reported, but the position in the logs is respected.
1871
1872 <length> is the maximum number of characters to extract from the value and
1873 report in the logs. The string will be truncated on the right if
1874 it exceeds <length>.
1875
Willy Tarreau4460d032012-11-21 23:37:37 +01001876 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01001877 result will be added to the logs between braces ('{}') after the captured
1878 request headers. If multiple headers are captured, they will be delimited by
1879 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01001880 the configuration. Non-existent headers will be logged just as an empty
1881 string. Common uses for response header captures include the "Content-length"
1882 header which indicates how many bytes are expected to be returned, the
1883 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001884
Willy Tarreau0900abb2012-11-22 00:21:46 +01001885 There is no limit to the number of captured response headers nor to their
1886 length, though it is wise to keep them low to limit memory usage per session.
1887 In order to keep log format consistent for a same frontend, header captures
1888 can only be declared in a frontend. It is not possible to specify a capture
1889 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01001890
1891 Example:
1892 capture response header Content-length len 9
1893 capture response header Location len 15
1894
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001895 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01001896 about logging.
1897
1898
Cyril Bontéf0c60612010-02-06 14:44:47 +01001899clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01001900 Set the maximum inactivity time on the client side.
1901 May be used in sections : defaults | frontend | listen | backend
1902 yes | yes | yes | no
1903 Arguments :
1904 <timeout> is the timeout value is specified in milliseconds by default, but
1905 can be in any other unit if the number is suffixed by the unit,
1906 as explained at the top of this document.
1907
1908 The inactivity timeout applies when the client is expected to acknowledge or
1909 send data. In HTTP mode, this timeout is particularly important to consider
1910 during the first phase, when the client sends the request, and during the
1911 response while it is reading data sent by the server. The value is specified
1912 in milliseconds by default, but can be in any other unit if the number is
1913 suffixed by the unit, as specified at the top of this document. In TCP mode
1914 (and to a lesser extent, in HTTP mode), it is highly recommended that the
1915 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01001916 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01001917 losses by specifying timeouts that are slightly above multiples of 3 seconds
1918 (eg: 4 or 5 seconds).
1919
1920 This parameter is specific to frontends, but can be specified once for all in
1921 "defaults" sections. This is in fact one of the easiest solutions not to
1922 forget about it. An unspecified timeout results in an infinite timeout, which
1923 is not recommended. Such a usage is accepted and works but reports a warning
1924 during startup because it may results in accumulation of expired sessions in
1925 the system if the system's timeouts are not configured either.
1926
1927 This parameter is provided for compatibility but is currently deprecated.
1928 Please use "timeout client" instead.
1929
Willy Tarreau036fae02008-01-06 13:24:40 +01001930 See also : "timeout client", "timeout http-request", "timeout server", and
1931 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001932
Cyril Bonté316a8cf2012-11-11 13:38:27 +01001933compression algo <algorithm> ...
1934compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02001935compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02001936 Enable HTTP compression.
1937 May be used in sections : defaults | frontend | listen | backend
1938 yes | yes | yes | yes
1939 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01001940 algo is followed by the list of supported compression algorithms.
1941 type is followed by the list of MIME types that will be compressed.
1942 offload makes haproxy work as a compression offloader only (see notes).
1943
1944 The currently supported algorithms are :
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04001945 identity this is mostly for debugging, and it was useful for developing
Cyril Bonté316a8cf2012-11-11 13:38:27 +01001946 the compression feature. Identity does not apply any change on
1947 data.
1948
1949 gzip applies gzip compression. This setting is only available when
1950 support for zlib was built in.
1951
1952 deflate same as gzip, but with deflate algorithm and zlib format.
1953 Note that this algorithm has ambiguous support on many browsers
1954 and no support at all from recent ones. It is strongly
1955 recommended not to use it for anything else than experimentation.
1956 This setting is only available when support for zlib was built
1957 in.
1958
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04001959 Compression will be activated depending on the Accept-Encoding request
Cyril Bonté316a8cf2012-11-11 13:38:27 +01001960 header. With identity, it does not take care of that header.
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04001961 If backend servers support HTTP compression, these directives
1962 will be no-op: haproxy will see the compressed response and will not
1963 compress again. If backend servers do not support HTTP compression and
1964 there is Accept-Encoding header in request, haproxy will compress the
1965 matching response.
Willy Tarreau70737d12012-10-27 00:34:28 +02001966
1967 The "offload" setting makes haproxy remove the Accept-Encoding header to
1968 prevent backend servers from compressing responses. It is strongly
1969 recommended not to do this because this means that all the compression work
1970 will be done on the single point where haproxy is located. However in some
1971 deployment scenarios, haproxy may be installed in front of a buggy gateway
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04001972 with broken HTTP compression implementation which can't be turned off.
1973 In that case haproxy can be used to prevent that gateway from emitting
1974 invalid payloads. In this case, simply removing the header in the
1975 configuration does not work because it applies before the header is parsed,
1976 so that prevents haproxy from compressing. The "offload" setting should
1977 then be used for such scenarios.
William Lallemand82fe75c2012-10-23 10:25:10 +02001978
William Lallemand05097442012-11-20 12:14:28 +01001979 Compression is disabled when:
Baptiste Assmann650d53d2013-01-05 15:44:44 +01001980 * the request does not advertise a supported compression algorithm in the
1981 "Accept-Encoding" header
1982 * the response message is not HTTP/1.1
William Lallemandd3002612012-11-26 14:34:47 +01001983 * HTTP status code is not 200
Baptiste Assmann650d53d2013-01-05 15:44:44 +01001984 * response contain neither a "Content-Length" header nor a
1985 "Transfer-Encoding" whose last value is "chunked"
1986 * response contains a "Content-Type" header whose first value starts with
1987 "multipart"
1988 * the response contains the "no-transform" value in the "Cache-control"
1989 header
1990 * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7
1991 and later
1992 * The response contains a "Content-Encoding" header, indicating that the
1993 response is already compressed (see compression offload)
William Lallemand05097442012-11-20 12:14:28 +01001994
Baptiste Assmann650d53d2013-01-05 15:44:44 +01001995 Note: The compression does not rewrite Etag headers, and does not emit the
1996 Warning header.
William Lallemand05097442012-11-20 12:14:28 +01001997
William Lallemand82fe75c2012-10-23 10:25:10 +02001998 Examples :
1999 compression algo gzip
2000 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01002001
Cyril Bontéf0c60612010-02-06 14:44:47 +01002002contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01002003 Set the maximum time to wait for a connection attempt to a server to succeed.
2004 May be used in sections : defaults | frontend | listen | backend
2005 yes | no | yes | yes
2006 Arguments :
2007 <timeout> is the timeout value is specified in milliseconds by default, but
2008 can be in any other unit if the number is suffixed by the unit,
2009 as explained at the top of this document.
2010
2011 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002012 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01002013 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01002014 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
2015 connect timeout also presets the queue timeout to the same value if this one
2016 has not been specified. Historically, the contimeout was also used to set the
2017 tarpit timeout in a listen section, which is not possible in a pure frontend.
2018
2019 This parameter is specific to backends, but can be specified once for all in
2020 "defaults" sections. This is in fact one of the easiest solutions not to
2021 forget about it. An unspecified timeout results in an infinite timeout, which
2022 is not recommended. Such a usage is accepted and works but reports a warning
2023 during startup because it may results in accumulation of failed sessions in
2024 the system if the system's timeouts are not configured either.
2025
2026 This parameter is provided for backwards compatibility but is currently
2027 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
2028 instead.
2029
2030 See also : "timeout connect", "timeout queue", "timeout tarpit",
2031 "timeout server", "contimeout".
2032
2033
Willy Tarreau55165fe2009-05-10 12:02:55 +02002034cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02002035 [ postonly ] [ preserve ] [ httponly ] [ secure ]
2036 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002037 Enable cookie-based persistence in a backend.
2038 May be used in sections : defaults | frontend | listen | backend
2039 yes | no | yes | yes
2040 Arguments :
2041 <name> is the name of the cookie which will be monitored, modified or
2042 inserted in order to bring persistence. This cookie is sent to
2043 the client via a "Set-Cookie" header in the response, and is
2044 brought back by the client in a "Cookie" header in all requests.
2045 Special care should be taken to choose a name which does not
2046 conflict with any likely application cookie. Also, if the same
2047 backends are subject to be used by the same clients (eg:
2048 HTTP/HTTPS), care should be taken to use different cookie names
2049 between all backends if persistence between them is not desired.
2050
2051 rewrite This keyword indicates that the cookie will be provided by the
2052 server and that haproxy will have to modify its value to set the
2053 server's identifier in it. This mode is handy when the management
2054 of complex combinations of "Set-cookie" and "Cache-control"
2055 headers is left to the application. The application can then
2056 decide whether or not it is appropriate to emit a persistence
2057 cookie. Since all responses should be monitored, this mode only
2058 works in HTTP close mode. Unless the application behaviour is
2059 very complex and/or broken, it is advised not to start with this
2060 mode for new deployments. This keyword is incompatible with
2061 "insert" and "prefix".
2062
2063 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02002064 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002065
Willy Tarreaua79094d2010-08-31 22:54:15 +02002066 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002067 server. When used without the "preserve" option, if the server
2068 emits a cookie with the same name, it will be remove before
2069 processing. For this reason, this mode can be used to upgrade
2070 existing configurations running in the "rewrite" mode. The cookie
2071 will only be a session cookie and will not be stored on the
2072 client's disk. By default, unless the "indirect" option is added,
2073 the server will see the cookies emitted by the client. Due to
2074 caching effects, it is generally wise to add the "nocache" or
2075 "postonly" keywords (see below). The "insert" keyword is not
2076 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002077
2078 prefix This keyword indicates that instead of relying on a dedicated
2079 cookie for the persistence, an existing one will be completed.
2080 This may be needed in some specific environments where the client
2081 does not support more than one single cookie and the application
2082 already needs it. In this case, whenever the server sets a cookie
2083 named <name>, it will be prefixed with the server's identifier
2084 and a delimiter. The prefix will be removed from all client
2085 requests so that the server still finds the cookie it emitted.
2086 Since all requests and responses are subject to being modified,
2087 this mode requires the HTTP close mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02002088 not compatible with "rewrite" and "insert". Note: it is highly
2089 recommended not to use "indirect" with "prefix", otherwise server
2090 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002091
Willy Tarreaua79094d2010-08-31 22:54:15 +02002092 indirect When this option is specified, no cookie will be emitted to a
2093 client which already has a valid one for the server which has
2094 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002095 it will be removed, unless the "preserve" option is also set. In
2096 "insert" mode, this will additionally remove cookies from the
2097 requests transmitted to the server, making the persistence
2098 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02002099 Note: it is highly recommended not to use "indirect" with
2100 "prefix", otherwise server cookie updates would not be sent to
2101 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002102
2103 nocache This option is recommended in conjunction with the insert mode
2104 when there is a cache between the client and HAProxy, as it
2105 ensures that a cacheable response will be tagged non-cacheable if
2106 a cookie needs to be inserted. This is important because if all
2107 persistence cookies are added on a cacheable home page for
2108 instance, then all customers will then fetch the page from an
2109 outer cache and will all share the same persistence cookie,
2110 leading to one server receiving much more traffic than others.
2111 See also the "insert" and "postonly" options.
2112
2113 postonly This option ensures that cookie insertion will only be performed
2114 on responses to POST requests. It is an alternative to the
2115 "nocache" option, because POST responses are not cacheable, so
2116 this ensures that the persistence cookie will never get cached.
2117 Since most sites do not need any sort of persistence before the
2118 first POST which generally is a login request, this is a very
2119 efficient method to optimize caching without risking to find a
2120 persistence cookie in the cache.
2121 See also the "insert" and "nocache" options.
2122
Willy Tarreauba4c5be2010-10-23 12:46:42 +02002123 preserve This option may only be used with "insert" and/or "indirect". It
2124 allows the server to emit the persistence cookie itself. In this
2125 case, if a cookie is found in the response, haproxy will leave it
2126 untouched. This is useful in order to end persistence after a
2127 logout request for instance. For this, the server just has to
2128 emit a cookie with an invalid value (eg: empty) or with a date in
2129 the past. By combining this mechanism with the "disable-on-404"
2130 check option, it is possible to perform a completely graceful
2131 shutdown because users will definitely leave the server after
2132 they logout.
2133
Willy Tarreau4992dd22012-05-31 21:02:17 +02002134 httponly This option tells haproxy to add an "HttpOnly" cookie attribute
2135 when a cookie is inserted. This attribute is used so that a
2136 user agent doesn't share the cookie with non-HTTP components.
2137 Please check RFC6265 for more information on this attribute.
2138
2139 secure This option tells haproxy to add a "Secure" cookie attribute when
2140 a cookie is inserted. This attribute is used so that a user agent
2141 never emits this cookie over non-secure channels, which means
2142 that a cookie learned with this flag will be presented only over
2143 SSL/TLS connections. Please check RFC6265 for more information on
2144 this attribute.
2145
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002146 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002147 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01002148 name. If the domain begins with a dot, the browser is allowed to
2149 use it for any host ending with that name. It is also possible to
2150 specify several domain names by invoking this option multiple
2151 times. Some browsers might have small limits on the number of
2152 domains, so be careful when doing that. For the record, sending
2153 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02002154
Willy Tarreau996a92c2010-10-13 19:30:47 +02002155 maxidle This option allows inserted cookies to be ignored after some idle
2156 time. It only works with insert-mode cookies. When a cookie is
2157 sent to the client, the date this cookie was emitted is sent too.
2158 Upon further presentations of this cookie, if the date is older
2159 than the delay indicated by the parameter (in seconds), it will
2160 be ignored. Otherwise, it will be refreshed if needed when the
2161 response is sent to the client. This is particularly useful to
2162 prevent users who never close their browsers from remaining for
2163 too long on the same server (eg: after a farm size change). When
2164 this option is set and a cookie has no date, it is always
2165 accepted, but gets refreshed in the response. This maintains the
2166 ability for admins to access their sites. Cookies that have a
2167 date in the future further than 24 hours are ignored. Doing so
2168 lets admins fix timezone issues without risking kicking users off
2169 the site.
2170
2171 maxlife This option allows inserted cookies to be ignored after some life
2172 time, whether they're in use or not. It only works with insert
2173 mode cookies. When a cookie is first sent to the client, the date
2174 this cookie was emitted is sent too. Upon further presentations
2175 of this cookie, if the date is older than the delay indicated by
2176 the parameter (in seconds), it will be ignored. If the cookie in
2177 the request has no date, it is accepted and a date will be set.
2178 Cookies that have a date in the future further than 24 hours are
2179 ignored. Doing so lets admins fix timezone issues without risking
2180 kicking users off the site. Contrary to maxidle, this value is
2181 not refreshed, only the first visit date counts. Both maxidle and
2182 maxlife may be used at the time. This is particularly useful to
2183 prevent users who never close their browsers from remaining for
2184 too long on the same server (eg: after a farm size change). This
2185 is stronger than the maxidle method in that it forces a
2186 redispatch after some absolute delay.
2187
Willy Tarreau0ba27502007-12-24 16:55:16 +01002188 There can be only one persistence cookie per HTTP backend, and it can be
2189 declared in a defaults section. The value of the cookie will be the value
2190 indicated after the "cookie" keyword in a "server" statement. If no cookie
2191 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002192
Willy Tarreau0ba27502007-12-24 16:55:16 +01002193 Examples :
2194 cookie JSESSIONID prefix
2195 cookie SRV insert indirect nocache
2196 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02002197 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01002198
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002199 See also : "appsession", "balance source", "capture cookie", "server"
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002200 and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002201
Willy Tarreau983e01e2010-01-11 18:42:06 +01002202
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002203default-server [param*]
2204 Change default options for a server in a backend
2205 May be used in sections : defaults | frontend | listen | backend
2206 yes | no | yes | yes
2207 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01002208 <param*> is a list of parameters for this server. The "default-server"
2209 keyword accepts an important number of options and has a complete
2210 section dedicated to it. Please refer to section 5 for more
2211 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002212
Willy Tarreau983e01e2010-01-11 18:42:06 +01002213 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01002214 default-server inter 1000 weight 13
2215
2216 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01002217
Willy Tarreau983e01e2010-01-11 18:42:06 +01002218
Willy Tarreau0ba27502007-12-24 16:55:16 +01002219default_backend <backend>
2220 Specify the backend to use when no "use_backend" rule has been matched.
2221 May be used in sections : defaults | frontend | listen | backend
2222 yes | yes | yes | no
2223 Arguments :
2224 <backend> is the name of the backend to use.
2225
2226 When doing content-switching between frontend and backends using the
2227 "use_backend" keyword, it is often useful to indicate which backend will be
2228 used when no rule has matched. It generally is the dynamic backend which
2229 will catch all undetermined requests.
2230
Willy Tarreau0ba27502007-12-24 16:55:16 +01002231 Example :
2232
2233 use_backend dynamic if url_dyn
2234 use_backend static if url_css url_img extension_img
2235 default_backend dynamic
2236
Willy Tarreau2769aa02007-12-27 18:26:09 +01002237 See also : "use_backend", "reqsetbe", "reqisetbe"
2238
Willy Tarreau0ba27502007-12-24 16:55:16 +01002239
2240disabled
2241 Disable a proxy, frontend or backend.
2242 May be used in sections : defaults | frontend | listen | backend
2243 yes | yes | yes | yes
2244 Arguments : none
2245
2246 The "disabled" keyword is used to disable an instance, mainly in order to
2247 liberate a listening port or to temporarily disable a service. The instance
2248 will still be created and its configuration will be checked, but it will be
2249 created in the "stopped" state and will appear as such in the statistics. It
2250 will not receive any traffic nor will it send any health-checks or logs. It
2251 is possible to disable many instances at once by adding the "disabled"
2252 keyword in a "defaults" section.
2253
2254 See also : "enabled"
2255
2256
Willy Tarreau5ce94572010-06-07 14:35:41 +02002257dispatch <address>:<port>
2258 Set a default server address
2259 May be used in sections : defaults | frontend | listen | backend
2260 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002261 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02002262
2263 <address> is the IPv4 address of the default server. Alternatively, a
2264 resolvable hostname is supported, but this name will be resolved
2265 during start-up.
2266
2267 <ports> is a mandatory port specification. All connections will be sent
2268 to this port, and it is not permitted to use port offsets as is
2269 possible with normal servers.
2270
Willy Tarreau787aed52011-04-15 06:45:37 +02002271 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02002272 server can take the connection. In the past it was used to forward non
2273 persistent connections to an auxiliary load balancer. Due to its simple
2274 syntax, it has also been used for simple TCP relays. It is recommended not to
2275 use it for more clarity, and to use the "server" directive instead.
2276
2277 See also : "server"
2278
2279
Willy Tarreau0ba27502007-12-24 16:55:16 +01002280enabled
2281 Enable a proxy, frontend or backend.
2282 May be used in sections : defaults | frontend | listen | backend
2283 yes | yes | yes | yes
2284 Arguments : none
2285
2286 The "enabled" keyword is used to explicitly enable an instance, when the
2287 defaults has been set to "disabled". This is very rarely used.
2288
2289 See also : "disabled"
2290
2291
2292errorfile <code> <file>
2293 Return a file contents instead of errors generated by HAProxy
2294 May be used in sections : defaults | frontend | listen | backend
2295 yes | yes | yes | yes
2296 Arguments :
2297 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002298 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002299
2300 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002301 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01002302 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01002303 error pages, and to use absolute paths, since files are read
2304 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002305
2306 It is important to understand that this keyword is not meant to rewrite
2307 errors returned by the server, but errors detected and returned by HAProxy.
2308 This is why the list of supported errors is limited to a small set.
2309
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002310 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2311
Willy Tarreau0ba27502007-12-24 16:55:16 +01002312 The files are returned verbatim on the TCP socket. This allows any trick such
2313 as redirections to another URL or site, as well as tricks to clean cookies,
2314 force enable or disable caching, etc... The package provides default error
2315 files returning the same contents as default errors.
2316
Willy Tarreau59140a22009-02-22 12:02:30 +01002317 The files should not exceed the configured buffer size (BUFSIZE), which
2318 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
2319 not to put any reference to local contents (eg: images) in order to avoid
2320 loops between the client and HAProxy when all servers are down, causing an
2321 error to be returned instead of an image. For better HTTP compliance, it is
2322 recommended that all header lines end with CR-LF and not LF alone.
2323
Willy Tarreau0ba27502007-12-24 16:55:16 +01002324 The files are read at the same time as the configuration and kept in memory.
2325 For this reason, the errors continue to be returned even when the process is
2326 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01002327 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002328 403 status code and interrogating a blocked URL.
2329
2330 See also : "errorloc", "errorloc302", "errorloc303"
2331
Willy Tarreau59140a22009-02-22 12:02:30 +01002332 Example :
2333 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
2334 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
2335 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
2336
Willy Tarreau2769aa02007-12-27 18:26:09 +01002337
2338errorloc <code> <url>
2339errorloc302 <code> <url>
2340 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2341 May be used in sections : defaults | frontend | listen | backend
2342 yes | yes | yes | yes
2343 Arguments :
2344 <code> is the HTTP status code. Currently, HAProxy is capable of
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002345 generating codes 200, 400, 403, 408, 500, 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002346
2347 <url> it is the exact contents of the "Location" header. It may contain
2348 either a relative URI to an error page hosted on the same site,
2349 or an absolute URI designating an error page on another site.
2350 Special care should be given to relative URIs to avoid redirect
2351 loops if the URI itself may generate the same error (eg: 500).
2352
2353 It is important to understand that this keyword is not meant to rewrite
2354 errors returned by the server, but errors detected and returned by HAProxy.
2355 This is why the list of supported errors is limited to a small set.
2356
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002357 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2358
Willy Tarreau2769aa02007-12-27 18:26:09 +01002359 Note that both keyword return the HTTP 302 status code, which tells the
2360 client to fetch the designated URL using the same HTTP method. This can be
2361 quite problematic in case of non-GET methods such as POST, because the URL
2362 sent to the client might not be allowed for something other than GET. To
2363 workaround this problem, please use "errorloc303" which send the HTTP 303
2364 status code, indicating to the client that the URL must be fetched with a GET
2365 request.
2366
2367 See also : "errorfile", "errorloc303"
2368
2369
2370errorloc303 <code> <url>
2371 Return an HTTP redirection to a URL instead of errors generated by HAProxy
2372 May be used in sections : defaults | frontend | listen | backend
2373 yes | yes | yes | yes
2374 Arguments :
2375 <code> is the HTTP status code. Currently, HAProxy is capable of
2376 generating codes 400, 403, 408, 500, 502, 503, and 504.
2377
2378 <url> it is the exact contents of the "Location" header. It may contain
2379 either a relative URI to an error page hosted on the same site,
2380 or an absolute URI designating an error page on another site.
2381 Special care should be given to relative URIs to avoid redirect
2382 loops if the URI itself may generate the same error (eg: 500).
2383
2384 It is important to understand that this keyword is not meant to rewrite
2385 errors returned by the server, but errors detected and returned by HAProxy.
2386 This is why the list of supported errors is limited to a small set.
2387
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002388 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
2389
Willy Tarreau2769aa02007-12-27 18:26:09 +01002390 Note that both keyword return the HTTP 303 status code, which tells the
2391 client to fetch the designated URL using the same HTTP GET method. This
2392 solves the usual problems associated with "errorloc" and the 302 code. It is
2393 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01002394 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002395
2396 See also : "errorfile", "errorloc", "errorloc302"
2397
2398
Willy Tarreau4de91492010-01-22 19:10:05 +01002399force-persist { if | unless } <condition>
2400 Declare a condition to force persistence on down servers
2401 May be used in sections: defaults | frontend | listen | backend
2402 no | yes | yes | yes
2403
2404 By default, requests are not dispatched to down servers. It is possible to
2405 force this using "option persist", but it is unconditional and redispatches
2406 to a valid server if "option redispatch" is set. That leaves with very little
2407 possibilities to force some requests to reach a server which is artificially
2408 marked down for maintenance operations.
2409
2410 The "force-persist" statement allows one to declare various ACL-based
2411 conditions which, when met, will cause a request to ignore the down status of
2412 a server and still try to connect to it. That makes it possible to start a
2413 server, still replying an error to the health checks, and run a specially
2414 configured browser to test the service. Among the handy methods, one could
2415 use a specific source IP address, or a specific cookie. The cookie also has
2416 the advantage that it can easily be added/removed on the browser from a test
2417 page. Once the service is validated, it is then possible to open the service
2418 to the world by returning a valid response to health checks.
2419
2420 The forced persistence is enabled when an "if" condition is met, or unless an
2421 "unless" condition is met. The final redispatch is always disabled when this
2422 is used.
2423
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002424 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02002425 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01002426
2427
Willy Tarreau2769aa02007-12-27 18:26:09 +01002428fullconn <conns>
2429 Specify at what backend load the servers will reach their maxconn
2430 May be used in sections : defaults | frontend | listen | backend
2431 yes | no | yes | yes
2432 Arguments :
2433 <conns> is the number of connections on the backend which will make the
2434 servers use the maximal number of connections.
2435
Willy Tarreau198a7442008-01-17 12:05:32 +01002436 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01002437 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01002438 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01002439 load. The server will then always accept at least <minconn> connections,
2440 never more than <maxconn>, and the limit will be on the ramp between both
2441 values when the backend has less than <conns> concurrent connections. This
2442 makes it possible to limit the load on the servers during normal loads, but
2443 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002444 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002445
Willy Tarreaufbb78422011-06-05 15:38:35 +02002446 Since it's hard to get this value right, haproxy automatically sets it to
2447 10% of the sum of the maxconns of all frontends that may branch to this
2448 backend. That way it's safe to leave it unset.
2449
Willy Tarreau2769aa02007-12-27 18:26:09 +01002450 Example :
2451 # The servers will accept between 100 and 1000 concurrent connections each
2452 # and the maximum of 1000 will be reached when the backend reaches 10000
2453 # connections.
2454 backend dynamic
2455 fullconn 10000
2456 server srv1 dyn1:80 minconn 100 maxconn 1000
2457 server srv2 dyn2:80 minconn 100 maxconn 1000
2458
2459 See also : "maxconn", "server"
2460
2461
2462grace <time>
2463 Maintain a proxy operational for some time after a soft stop
2464 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01002465 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01002466 Arguments :
2467 <time> is the time (by default in milliseconds) for which the instance
2468 will remain operational with the frontend sockets still listening
2469 when a soft-stop is received via the SIGUSR1 signal.
2470
2471 This may be used to ensure that the services disappear in a certain order.
2472 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002473 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01002474 needed by the equipment to detect the failure.
2475
2476 Note that currently, there is very little benefit in using this parameter,
2477 and it may in fact complicate the soft-reconfiguration process more than
2478 simplify it.
2479
Willy Tarreau0ba27502007-12-24 16:55:16 +01002480
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002481hash-type <method>
2482 Specify a method to use for mapping hashes to servers
2483 May be used in sections : defaults | frontend | listen | backend
2484 yes | no | yes | yes
2485 Arguments :
2486 map-based the hash table is a static array containing all alive servers.
2487 The hashes will be very smooth, will consider weights, but will
2488 be static in that weight changes while a server is up will be
2489 ignored. This means that there will be no slow start. Also,
2490 since a server is selected by its position in the array, most
2491 mappings are changed when the server count changes. This means
2492 that when a server goes up or down, or when a server is added
2493 to a farm, most connections will be redistributed to different
2494 servers. This can be inconvenient with caches for instance.
2495
Willy Tarreau798a39c2010-11-24 15:04:29 +01002496 avalanche this mechanism uses the default map-based hashing described
2497 above but applies a full avalanche hash before performing the
2498 mapping. The result is a slightly less smooth hash for most
2499 situations, but the hash becomes better than pure map-based
2500 hashes when the number of servers is a multiple of the size of
2501 the input set. When using URI hash with a number of servers
2502 multiple of 64, it's desirable to change the hash type to
2503 this value.
2504
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002505 consistent the hash table is a tree filled with many occurrences of each
2506 server. The hash key is looked up in the tree and the closest
2507 server is chosen. This hash is dynamic, it supports changing
2508 weights while the servers are up, so it is compatible with the
2509 slow start feature. It has the advantage that when a server
2510 goes up or down, only its associations are moved. When a server
2511 is added to the farm, only a few part of the mappings are
2512 redistributed, making it an ideal algorithm for caches.
2513 However, due to its principle, the algorithm will never be very
2514 smooth and it may sometimes be necessary to adjust a server's
2515 weight or its ID to get a more balanced distribution. In order
2516 to get the same distribution on multiple load balancers, it is
2517 important that all servers have the same IDs.
2518
2519 The default hash type is "map-based" and is recommended for most usages.
2520
2521 See also : "balance", "server"
2522
2523
Willy Tarreau0ba27502007-12-24 16:55:16 +01002524http-check disable-on-404
2525 Enable a maintenance mode upon HTTP/404 response to health-checks
2526 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01002527 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01002528 Arguments : none
2529
2530 When this option is set, a server which returns an HTTP code 404 will be
2531 excluded from further load-balancing, but will still receive persistent
2532 connections. This provides a very convenient method for Web administrators
2533 to perform a graceful shutdown of their servers. It is also important to note
2534 that a server which is detected as failed while it was in this mode will not
2535 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
2536 will immediately be reinserted into the farm. The status on the stats page
2537 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01002538 option only works in conjunction with the "httpchk" option. If this option
2539 is used with "http-check expect", then it has precedence over it so that 404
2540 responses will still be considered as soft-stop.
2541
2542 See also : "option httpchk", "http-check expect"
2543
2544
2545http-check expect [!] <match> <pattern>
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002546 Make HTTP health checks consider response contents or specific status codes
Willy Tarreaubd741542010-03-16 18:46:54 +01002547 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau1ee51a62011-08-19 20:04:17 +02002548 yes | no | yes | yes
Willy Tarreaubd741542010-03-16 18:46:54 +01002549 Arguments :
2550 <match> is a keyword indicating how to look for a specific pattern in the
2551 response. The keyword may be one of "status", "rstatus",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002552 "string", or "rstring". The keyword may be preceded by an
Willy Tarreaubd741542010-03-16 18:46:54 +01002553 exclamation mark ("!") to negate the match. Spaces are allowed
2554 between the exclamation mark and the keyword. See below for more
2555 details on the supported keywords.
2556
2557 <pattern> is the pattern to look for. It may be a string or a regular
2558 expression. If the pattern contains spaces, they must be escaped
2559 with the usual backslash ('\').
2560
2561 By default, "option httpchk" considers that response statuses 2xx and 3xx
2562 are valid, and that others are invalid. When "http-check expect" is used,
2563 it defines what is considered valid or invalid. Only one "http-check"
2564 statement is supported in a backend. If a server fails to respond or times
2565 out, the check obviously fails. The available matches are :
2566
2567 status <string> : test the exact string match for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002568 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002569 response's status code is exactly this string. If the
2570 "status" keyword is prefixed with "!", then the response
2571 will be considered invalid if the status code matches.
2572
2573 rstatus <regex> : test a regular expression for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002574 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002575 response's status code matches the expression. If the
2576 "rstatus" keyword is prefixed with "!", then the response
2577 will be considered invalid if the status code matches.
2578 This is mostly used to check for multiple codes.
2579
2580 string <string> : test the exact string match in the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002581 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002582 response's body contains this exact string. If the
2583 "string" keyword is prefixed with "!", then the response
2584 will be considered invalid if the body contains this
2585 string. This can be used to look for a mandatory word at
2586 the end of a dynamic page, or to detect a failure when a
2587 specific error appears on the check page (eg: a stack
2588 trace).
2589
2590 rstring <regex> : test a regular expression on the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04002591 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01002592 response's body matches this expression. If the "rstring"
2593 keyword is prefixed with "!", then the response will be
2594 considered invalid if the body matches the expression.
2595 This can be used to look for a mandatory word at the end
2596 of a dynamic page, or to detect a failure when a specific
2597 error appears on the check page (eg: a stack trace).
2598
2599 It is important to note that the responses will be limited to a certain size
2600 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
2601 Thus, too large responses may not contain the mandatory pattern when using
2602 "string" or "rstring". If a large response is absolutely required, it is
2603 possible to change the default max size by setting the global variable.
2604 However, it is worth keeping in mind that parsing very large responses can
2605 waste some CPU cycles, especially when regular expressions are used, and that
2606 it is always better to focus the checks on smaller resources.
2607
2608 Last, if "http-check expect" is combined with "http-check disable-on-404",
2609 then this last one has precedence when the server responds with 404.
2610
2611 Examples :
2612 # only accept status 200 as valid
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002613 http-check expect status 200
Willy Tarreaubd741542010-03-16 18:46:54 +01002614
2615 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002616 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01002617
2618 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002619 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01002620
2621 # check that we have a correct hexadecimal tag before /html
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01002622 http-check expect rstring <!--tag:[0-9a-f]*</html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01002623
Willy Tarreaubd741542010-03-16 18:46:54 +01002624 See also : "option httpchk", "http-check disable-on-404"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002625
2626
Willy Tarreauef781042010-01-27 11:53:01 +01002627http-check send-state
2628 Enable emission of a state header with HTTP health checks
2629 May be used in sections : defaults | frontend | listen | backend
2630 yes | no | yes | yes
2631 Arguments : none
2632
2633 When this option is set, haproxy will systematically send a special header
2634 "X-Haproxy-Server-State" with a list of parameters indicating to each server
2635 how they are seen by haproxy. This can be used for instance when a server is
2636 manipulated without access to haproxy and the operator needs to know whether
2637 haproxy still sees it up or not, or if the server is the last one in a farm.
2638
2639 The header is composed of fields delimited by semi-colons, the first of which
2640 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
2641 checks on the total number before transition, just as appears in the stats
2642 interface. Next headers are in the form "<variable>=<value>", indicating in
2643 no specific order some values available in the stats interface :
2644 - a variable "name", containing the name of the backend followed by a slash
2645 ("/") then the name of the server. This can be used when a server is
2646 checked in multiple backends.
2647
2648 - a variable "node" containing the name of the haproxy node, as set in the
2649 global "node" variable, otherwise the system's hostname if unspecified.
2650
2651 - a variable "weight" indicating the weight of the server, a slash ("/")
2652 and the total weight of the farm (just counting usable servers). This
2653 helps to know if other servers are available to handle the load when this
2654 one fails.
2655
2656 - a variable "scur" indicating the current number of concurrent connections
2657 on the server, followed by a slash ("/") then the total number of
2658 connections on all servers of the same backend.
2659
2660 - a variable "qcur" indicating the current number of requests in the
2661 server's queue.
2662
2663 Example of a header received by the application server :
2664 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
2665 scur=13/22; qcur=0
2666
2667 See also : "option httpchk", "http-check disable-on-404"
2668
Willy Tarreauccbcc372012-12-27 12:37:57 +01002669http-request { allow | deny | tarpit | auth [realm <realm>] | redirect <rule> |
Willy Tarreau20b0de52012-12-24 15:45:22 +01002670 add-header <name> <fmt> | set-header <name> <fmt> }
Cyril Bontéf0c60612010-02-06 14:44:47 +01002671 [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002672 Access control for Layer 7 requests
2673
2674 May be used in sections: defaults | frontend | listen | backend
2675 no | yes | yes | yes
2676
Willy Tarreau20b0de52012-12-24 15:45:22 +01002677 The http-request statement defines a set of rules which apply to layer 7
2678 processing. The rules are evaluated in their declaration order when they are
2679 met in a frontend, listen or backend section. Any rule may optionally be
2680 followed by an ACL-based condition, in which case it will only be evaluated
2681 if the condition is true.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002682
Willy Tarreau20b0de52012-12-24 15:45:22 +01002683 The first keyword is the rule's action. Currently supported actions include :
2684 - "allow" : this stops the evaluation of the rules and lets the request
2685 pass the check. No further "http-request" rules are evaluated.
2686
2687 - "deny" : this stops the evaluation of the rules and immediately rejects
2688 the request and emits an HTTP 403 error. No further "http-request" rules
2689 are evaluated.
2690
Willy Tarreauccbcc372012-12-27 12:37:57 +01002691 - "tarpit" : this stops the evaluation of the rules and immediately blocks
2692 the request without responding for a delay specified by "timeout tarpit"
2693 or "timeout connect" if the former is not set. After that delay, if the
2694 client is still connected, an HTTP error 500 is returned so that the
2695 client does not suspect it has been tarpitted. Logs will report the flags
2696 "PT". The goal of the tarpit rule is to slow down robots during an attack
2697 when they're limited on the number of concurrent requests. It can be very
2698 efficient against very dumb robots, and will significantly reduce the
2699 load on firewalls compared to a "deny" rule. But when facing "correctly"
2700 developped robots, it can make things worse by forcing haproxy and the
2701 front firewall to support insane number of concurrent connections.
2702
Willy Tarreau20b0de52012-12-24 15:45:22 +01002703 - "auth" : this stops the evaluation of the rules and immediately responds
2704 with an HTTP 401 or 407 error code to invite the user to present a valid
2705 user name and password. No further "http-request" rules are evaluated. An
2706 optional "realm" parameter is supported, it sets the authentication realm
2707 that is returned with the response (typically the application's name).
2708
Willy Tarreau81499eb2012-12-27 12:19:02 +01002709 - "redirect" : this performs an HTTP redirection based on a redirect rule.
2710 This is exactly the same as the "redirect" statement except that it
2711 inserts a redirect rule which can be processed in the middle of other
2712 "http-request" rules. See the "redirect" keyword for the rule's syntax.
2713
Willy Tarreau20b0de52012-12-24 15:45:22 +01002714 - "add-header" appends an HTTP header field whose name is specified in
2715 <name> and whose value is defined by <fmt> which follows the log-format
2716 rules (see Custom Log Format in section 8.2.4). This is particularly
2717 useful to pass connection-specific information to the server (eg: the
2718 client's SSL certificate), or to combine several headers into one. This
2719 rule is not final, so it is possible to add other similar rules. Note
2720 that header addition is performed immediately, so one rule might reuse
2721 the resulting header from a previous rule.
2722
2723 - "set-header" does the same as "add-header" except that the header name
2724 is first removed if it existed. This is useful when passing security
2725 information to the server, where the header must not be manipulated by
2726 external users.
2727
2728 There is no limit to the number of http-request statements per instance.
2729
2730 It is important to know that http-request rules are processed very early in
2731 the HTTP processing, just after "block" rules and before "reqdel" or "reqrep"
2732 rules. That way, headers added by "add-header"/"set-header" are visible by
2733 almost all further ACL rules.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002734
2735 Example:
Cyril Bonté78caf842010-03-10 22:41:43 +01002736 acl nagios src 192.168.129.3
2737 acl local_net src 192.168.0.0/16
2738 acl auth_ok http_auth(L1)
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002739
Cyril Bonté78caf842010-03-10 22:41:43 +01002740 http-request allow if nagios
2741 http-request allow if local_net auth_ok
2742 http-request auth realm Gimme if local_net auth_ok
2743 http-request deny
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002744
Cyril Bonté78caf842010-03-10 22:41:43 +01002745 Example:
2746 acl auth_ok http_auth_group(L1) G1
Cyril Bonté78caf842010-03-10 22:41:43 +01002747 http-request auth unless auth_ok
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002748
Willy Tarreau20b0de52012-12-24 15:45:22 +01002749 Example:
2750 http-request set-header X-Haproxy-Current-Date %T
2751 http-request set-header X-SSL %[ssl_fc]
2752 http-request set-header X-SSL-Session_ID %[ssl_fc_session_id]
2753 http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
2754 http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
2755 http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
2756 http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
2757 http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
2758 http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
2759
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02002760 See also : "stats http-request", section 3.4 about userlists and section 7
2761 about ACL usage.
Willy Tarreauef781042010-01-27 11:53:01 +01002762
Mark Lamourinec2247f02012-01-04 13:02:01 -05002763http-send-name-header [<header>]
2764 Add the server name to a request. Use the header string given by <header>
2765
2766 May be used in sections: defaults | frontend | listen | backend
2767 yes | no | yes | yes
2768
2769 Arguments :
2770
2771 <header> The header string to use to send the server name
2772
2773 The "http-send-name-header" statement causes the name of the target
2774 server to be added to the headers of an HTTP request. The name
2775 is added with the header string proved.
2776
2777 See also : "server"
2778
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01002779id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02002780 Set a persistent ID to a proxy.
2781 May be used in sections : defaults | frontend | listen | backend
2782 no | yes | yes | yes
2783 Arguments : none
2784
2785 Set a persistent ID for the proxy. This ID must be unique and positive.
2786 An unused ID will automatically be assigned if unset. The first assigned
2787 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01002788
2789
Cyril Bonté0d4bf012010-04-25 23:21:46 +02002790ignore-persist { if | unless } <condition>
2791 Declare a condition to ignore persistence
2792 May be used in sections: defaults | frontend | listen | backend
2793 no | yes | yes | yes
2794
2795 By default, when cookie persistence is enabled, every requests containing
2796 the cookie are unconditionally persistent (assuming the target server is up
2797 and running).
2798
2799 The "ignore-persist" statement allows one to declare various ACL-based
2800 conditions which, when met, will cause a request to ignore persistence.
2801 This is sometimes useful to load balance requests for static files, which
2802 oftenly don't require persistence. This can also be used to fully disable
2803 persistence for a specific User-Agent (for example, some web crawler bots).
2804
2805 Combined with "appsession", it can also help reduce HAProxy memory usage, as
2806 the appsession table won't grow if persistence is ignored.
2807
2808 The persistence is ignored when an "if" condition is met, or unless an
2809 "unless" condition is met.
2810
2811 See also : "force-persist", "cookie", and section 7 about ACL usage.
2812
2813
Willy Tarreau2769aa02007-12-27 18:26:09 +01002814log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002815log <address> <facility> [<level> [<minlevel>]]
William Lallemand0f99e342011-10-12 17:50:54 +02002816no log
Willy Tarreau2769aa02007-12-27 18:26:09 +01002817 Enable per-instance logging of events and traffic.
2818 May be used in sections : defaults | frontend | listen | backend
2819 yes | yes | yes | yes
William Lallemand0f99e342011-10-12 17:50:54 +02002820
2821 Prefix :
2822 no should be used when the logger list must be flushed. For example,
2823 if you don't want to inherit from the default logger list. This
2824 prefix does not allow arguments.
2825
Willy Tarreau2769aa02007-12-27 18:26:09 +01002826 Arguments :
2827 global should be used when the instance's logging parameters are the
2828 same as the global ones. This is the most common usage. "global"
2829 replaces <address>, <facility> and <level> with those of the log
2830 entries found in the "global" section. Only one "log global"
2831 statement may be used per instance, and this form takes no other
2832 parameter.
2833
2834 <address> indicates where to send the logs. It takes the same format as
2835 for the "global" section's logs, and can be one of :
2836
2837 - An IPv4 address optionally followed by a colon (':') and a UDP
2838 port. If no port is specified, 514 is used by default (the
2839 standard syslog port).
2840
David du Colombier24bb5f52011-03-17 10:40:23 +01002841 - An IPv6 address followed by a colon (':') and optionally a UDP
2842 port. If no port is specified, 514 is used by default (the
2843 standard syslog port).
2844
Willy Tarreau2769aa02007-12-27 18:26:09 +01002845 - A filesystem path to a UNIX domain socket, keeping in mind
2846 considerations for chroot (be sure the path is accessible
2847 inside the chroot) and uid/gid (be sure the path is
2848 appropriately writeable).
2849
Willy Tarreaudad36a32013-03-11 01:20:04 +01002850 Any part of the address string may reference any number of
2851 environment variables by preceding their name with a dollar
2852 sign ('$') and optionally enclosing them with braces ('{}'),
2853 similarly to what is done in Bourne shell.
2854
Willy Tarreau2769aa02007-12-27 18:26:09 +01002855 <facility> must be one of the 24 standard syslog facilities :
2856
2857 kern user mail daemon auth syslog lpr news
2858 uucp cron auth2 ftp ntp audit alert cron2
2859 local0 local1 local2 local3 local4 local5 local6 local7
2860
2861 <level> is optional and can be specified to filter outgoing messages. By
2862 default, all messages are sent. If a level is specified, only
2863 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002864 will be sent. An optional minimum level can be specified. If it
2865 is set, logs emitted with a more severe level than this one will
2866 be capped to this level. This is used to avoid sending "emerg"
2867 messages on all terminals on some default syslog configurations.
2868 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01002869
2870 emerg alert crit err warning notice info debug
2871
William Lallemand0f99e342011-10-12 17:50:54 +02002872 It is important to keep in mind that it is the frontend which decides what to
2873 log from a connection, and that in case of content switching, the log entries
2874 from the backend will be ignored. Connections are logged at level "info".
Willy Tarreaucc6c8912009-02-22 10:53:55 +01002875
2876 However, backend log declaration define how and where servers status changes
2877 will be logged. Level "notice" will be used to indicate a server going up,
2878 "warning" will be used for termination signals and definitive service
2879 termination, and "alert" will be used for when a server goes down.
2880
2881 Note : According to RFC3164, messages are truncated to 1024 bytes before
2882 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002883
2884 Example :
2885 log global
Willy Tarreauf7edefa2009-05-10 17:20:05 +02002886 log 127.0.0.1:514 local0 notice # only send important events
2887 log 127.0.0.1:514 local0 notice notice # same but limit output level
Willy Tarreaudad36a32013-03-11 01:20:04 +01002888 log ${LOCAL_SYSLOG}:514 local0 notice # send to local server
2889
Willy Tarreau2769aa02007-12-27 18:26:09 +01002890
William Lallemand48940402012-01-30 16:47:22 +01002891log-format <string>
2892 Allows you to custom a log line.
2893
2894 See also : Custom Log Format (8.2.4)
2895
Willy Tarreau2769aa02007-12-27 18:26:09 +01002896
2897maxconn <conns>
2898 Fix the maximum number of concurrent connections on a frontend
2899 May be used in sections : defaults | frontend | listen | backend
2900 yes | yes | yes | no
2901 Arguments :
2902 <conns> is the maximum number of concurrent connections the frontend will
2903 accept to serve. Excess connections will be queued by the system
2904 in the socket's listen queue and will be served once a connection
2905 closes.
2906
2907 If the system supports it, it can be useful on big sites to raise this limit
2908 very high so that haproxy manages connection queues, instead of leaving the
2909 clients with unanswered connection attempts. This value should not exceed the
2910 global maxconn. Also, keep in mind that a connection contains two buffers
2911 of 8kB each, as well as some other data resulting in about 17 kB of RAM being
2912 consumed per established connection. That means that a medium system equipped
2913 with 1GB of RAM can withstand around 40000-50000 concurrent connections if
2914 properly tuned.
2915
2916 Also, when <conns> is set to large values, it is possible that the servers
2917 are not sized to accept such loads, and for this reason it is generally wise
2918 to assign them some reasonable connection limits.
2919
Vincent Bernat6341be52012-06-27 17:18:30 +02002920 By default, this value is set to 2000.
2921
Willy Tarreau2769aa02007-12-27 18:26:09 +01002922 See also : "server", global section's "maxconn", "fullconn"
2923
2924
2925mode { tcp|http|health }
2926 Set the running mode or protocol of the instance
2927 May be used in sections : defaults | frontend | listen | backend
2928 yes | yes | yes | yes
2929 Arguments :
2930 tcp The instance will work in pure TCP mode. A full-duplex connection
2931 will be established between clients and servers, and no layer 7
2932 examination will be performed. This is the default mode. It
2933 should be used for SSL, SSH, SMTP, ...
2934
2935 http The instance will work in HTTP mode. The client request will be
2936 analyzed in depth before connecting to any server. Any request
2937 which is not RFC-compliant will be rejected. Layer 7 filtering,
2938 processing and switching will be possible. This is the mode which
2939 brings HAProxy most of its value.
2940
2941 health The instance will work in "health" mode. It will just reply "OK"
Willy Tarreau82569f92012-09-27 23:48:56 +02002942 to incoming connections and close the connection. Alternatively,
2943 If the "httpchk" option is set, "HTTP/1.0 200 OK" will be sent
2944 instead. Nothing will be logged in either case. This mode is used
2945 to reply to external components health checks. This mode is
2946 deprecated and should not be used anymore as it is possible to do
2947 the same and even better by combining TCP or HTTP modes with the
2948 "monitor" keyword.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002949
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002950 When doing content switching, it is mandatory that the frontend and the
2951 backend are in the same mode (generally HTTP), otherwise the configuration
2952 will be refused.
Willy Tarreau2769aa02007-12-27 18:26:09 +01002953
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002954 Example :
Willy Tarreau2769aa02007-12-27 18:26:09 +01002955 defaults http_instances
2956 mode http
2957
Cyril Bonté108cf6e2012-04-21 23:30:29 +02002958 See also : "monitor", "monitor-net"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002959
Willy Tarreau0ba27502007-12-24 16:55:16 +01002960
Cyril Bontéf0c60612010-02-06 14:44:47 +01002961monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01002962 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002963 May be used in sections : defaults | frontend | listen | backend
2964 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01002965 Arguments :
2966 if <cond> the monitor request will fail if the condition is satisfied,
2967 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002968 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01002969 are met, for instance a low number of servers both in a
2970 backend and its backup.
2971
2972 unless <cond> the monitor request will succeed only if the condition is
2973 satisfied, and will fail otherwise. Such a condition may be
2974 based on a test on the presence of a minimum number of active
2975 servers in a list of backends.
2976
2977 This statement adds a condition which can force the response to a monitor
2978 request to report a failure. By default, when an external component queries
2979 the URI dedicated to monitoring, a 200 response is returned. When one of the
2980 conditions above is met, haproxy will return 503 instead of 200. This is
2981 very useful to report a site failure to an external component which may base
2982 routing advertisements between multiple sites on the availability reported by
2983 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002984 criterion. Note that "monitor fail" only works in HTTP mode. Both status
2985 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002986
2987 Example:
2988 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01002989 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01002990 acl site_dead nbsrv(dynamic) lt 2
2991 acl site_dead nbsrv(static) lt 2
2992 monitor-uri /site_alive
2993 monitor fail if site_dead
2994
Willy Tarreauae94d4d2011-05-11 16:28:49 +02002995 See also : "monitor-net", "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01002996
2997
2998monitor-net <source>
2999 Declare a source network which is limited to monitor requests
3000 May be used in sections : defaults | frontend | listen | backend
3001 yes | yes | yes | no
3002 Arguments :
3003 <source> is the source IPv4 address or network which will only be able to
3004 get monitor responses to any request. It can be either an IPv4
3005 address, a host name, or an address followed by a slash ('/')
3006 followed by a mask.
3007
3008 In TCP mode, any connection coming from a source matching <source> will cause
3009 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003010 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01003011 forwarding the connection to a remote server.
3012
3013 In HTTP mode, a connection coming from a source matching <source> will be
3014 accepted, the following response will be sent without waiting for a request,
3015 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
3016 enough for any front-end HTTP probe to detect that the service is UP and
Willy Tarreau82569f92012-09-27 23:48:56 +02003017 running without forwarding the request to a backend server. Note that this
3018 response is sent in raw format, without any transformation. This is important
3019 as it means that it will not be SSL-encrypted on SSL listeners.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003020
Willy Tarreau82569f92012-09-27 23:48:56 +02003021 Monitor requests are processed very early, just after tcp-request connection
3022 ACLs which are the only ones able to block them. These connections are short
3023 lived and never wait for any data from the client. They cannot be logged, and
3024 it is the intended purpose. They are only used to report HAProxy's health to
3025 an upper component, nothing more. Please note that "monitor fail" rules do
3026 not apply to connections intercepted by "monitor-net".
Willy Tarreau2769aa02007-12-27 18:26:09 +01003027
Willy Tarreau95cd2832010-03-04 23:36:33 +01003028 Last, please note that only one "monitor-net" statement can be specified in
3029 a frontend. If more than one is found, only the last one will be considered.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003030
Willy Tarreau2769aa02007-12-27 18:26:09 +01003031 Example :
3032 # addresses .252 and .253 are just probing us.
3033 frontend www
3034 monitor-net 192.168.0.252/31
3035
3036 See also : "monitor fail", "monitor-uri"
3037
3038
3039monitor-uri <uri>
3040 Intercept a URI used by external components' monitor requests
3041 May be used in sections : defaults | frontend | listen | backend
3042 yes | yes | yes | no
3043 Arguments :
3044 <uri> is the exact URI which we want to intercept to return HAProxy's
3045 health status instead of forwarding the request.
3046
3047 When an HTTP request referencing <uri> will be received on a frontend,
3048 HAProxy will not forward it nor log it, but instead will return either
3049 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
3050 conditions defined with "monitor fail". This is normally enough for any
3051 front-end HTTP probe to detect that the service is UP and running without
3052 forwarding the request to a backend server. Note that the HTTP method, the
3053 version and all headers are ignored, but the request must at least be valid
3054 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
3055
3056 Monitor requests are processed very early. It is not possible to block nor
3057 divert them using ACLs. They cannot be logged either, and it is the intended
3058 purpose. They are only used to report HAProxy's health to an upper component,
3059 nothing more. However, it is possible to add any number of conditions using
3060 "monitor fail" and ACLs so that the result can be adjusted to whatever check
3061 can be imagined (most often the number of available servers in a backend).
3062
3063 Example :
3064 # Use /haproxy_test to report haproxy's status
3065 frontend www
3066 mode http
3067 monitor-uri /haproxy_test
3068
3069 See also : "monitor fail", "monitor-net"
3070
Willy Tarreau0ba27502007-12-24 16:55:16 +01003071
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003072option abortonclose
3073no option abortonclose
3074 Enable or disable early dropping of aborted requests pending in queues.
3075 May be used in sections : defaults | frontend | listen | backend
3076 yes | no | yes | yes
3077 Arguments : none
3078
3079 In presence of very high loads, the servers will take some time to respond.
3080 The per-instance connection queue will inflate, and the response time will
3081 increase respective to the size of the queue times the average per-session
3082 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01003083 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003084 the queue, and slowing down other users, and the servers as well, because the
3085 request will eventually be served, then aborted at the first error
3086 encountered while delivering the response.
3087
3088 As there is no way to distinguish between a full STOP and a simple output
3089 close on the client side, HTTP agents should be conservative and consider
3090 that the client might only have closed its output channel while waiting for
3091 the response. However, this introduces risks of congestion when lots of users
3092 do the same, and is completely useless nowadays because probably no client at
3093 all will close the session while waiting for the response. Some HTTP agents
Willy Tarreaud72758d2010-01-12 10:42:19 +01003094 support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003095 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01003096 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003097 of being the single component to break rare but valid traffic is extremely
3098 low, which adds to the temptation to be able to abort a session early while
3099 still not served and not pollute the servers.
3100
3101 In HAProxy, the user can choose the desired behaviour using the option
3102 "abortonclose". By default (without the option) the behaviour is HTTP
3103 compliant and aborted requests will be served. But when the option is
3104 specified, a session with an incoming channel closed will be aborted while
3105 it is still possible, either pending in the queue for a connection slot, or
3106 during the connection establishment if the server has not yet acknowledged
3107 the connection request. This considerably reduces the queue size and the load
3108 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01003109 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003110
3111 If this option has been enabled in a "defaults" section, it can be disabled
3112 in a specific instance by prepending the "no" keyword before it.
3113
3114 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
3115
3116
Willy Tarreau4076a152009-04-02 15:18:36 +02003117option accept-invalid-http-request
3118no option accept-invalid-http-request
3119 Enable or disable relaxing of HTTP request parsing
3120 May be used in sections : defaults | frontend | listen | backend
3121 yes | yes | yes | no
3122 Arguments : none
3123
3124 By default, HAProxy complies with RFC2616 in terms of message parsing. This
3125 means that invalid characters in header names are not permitted and cause an
3126 error to be returned to the client. This is the desired behaviour as such
3127 forbidden characters are essentially used to build attacks exploiting server
3128 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
3129 server will emit invalid header names for whatever reason (configuration,
3130 implementation) and the issue will not be immediately fixed. In such a case,
3131 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau422246e2012-01-07 23:54:13 +01003132 even if that does not make sense, by specifying this option. Similarly, the
3133 list of characters allowed to appear in a URI is well defined by RFC3986, and
3134 chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
3135 ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
3136 not allowed at all. Haproxy always blocks a number of them (0..32, 127). The
3137 remaining ones are blocked by default unless this option is enabled.
Willy Tarreau4076a152009-04-02 15:18:36 +02003138
3139 This option should never be enabled by default as it hides application bugs
3140 and open security breaches. It should only be deployed after a problem has
3141 been confirmed.
3142
3143 When this option is enabled, erroneous header names will still be accepted in
3144 requests, but the complete request will be captured in order to permit later
Willy Tarreau422246e2012-01-07 23:54:13 +01003145 analysis using the "show errors" request on the UNIX stats socket. Similarly,
3146 requests containing invalid chars in the URI part will be logged. Doing this
Willy Tarreau4076a152009-04-02 15:18:36 +02003147 also helps confirming that the issue has been solved.
3148
3149 If this option has been enabled in a "defaults" section, it can be disabled
3150 in a specific instance by prepending the "no" keyword before it.
3151
3152 See also : "option accept-invalid-http-response" and "show errors" on the
3153 stats socket.
3154
3155
3156option accept-invalid-http-response
3157no option accept-invalid-http-response
3158 Enable or disable relaxing of HTTP response parsing
3159 May be used in sections : defaults | frontend | listen | backend
3160 yes | no | yes | yes
3161 Arguments : none
3162
3163 By default, HAProxy complies with RFC2616 in terms of message parsing. This
3164 means that invalid characters in header names are not permitted and cause an
3165 error to be returned to the client. This is the desired behaviour as such
3166 forbidden characters are essentially used to build attacks exploiting server
3167 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
3168 server will emit invalid header names for whatever reason (configuration,
3169 implementation) and the issue will not be immediately fixed. In such a case,
3170 it is possible to relax HAProxy's header name parser to accept any character
3171 even if that does not make sense, by specifying this option.
3172
3173 This option should never be enabled by default as it hides application bugs
3174 and open security breaches. It should only be deployed after a problem has
3175 been confirmed.
3176
3177 When this option is enabled, erroneous header names will still be accepted in
3178 responses, but the complete response will be captured in order to permit
3179 later analysis using the "show errors" request on the UNIX stats socket.
3180 Doing this also helps confirming that the issue has been solved.
3181
3182 If this option has been enabled in a "defaults" section, it can be disabled
3183 in a specific instance by prepending the "no" keyword before it.
3184
3185 See also : "option accept-invalid-http-request" and "show errors" on the
3186 stats socket.
3187
3188
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003189option allbackups
3190no option allbackups
3191 Use either all backup servers at a time or only the first one
3192 May be used in sections : defaults | frontend | listen | backend
3193 yes | no | yes | yes
3194 Arguments : none
3195
3196 By default, the first operational backup server gets all traffic when normal
3197 servers are all down. Sometimes, it may be preferred to use multiple backups
3198 at once, because one will not be enough. When "option allbackups" is enabled,
3199 the load balancing will be performed among all backup servers when all normal
3200 ones are unavailable. The same load balancing algorithm will be used and the
3201 servers' weights will be respected. Thus, there will not be any priority
3202 order between the backup servers anymore.
3203
3204 This option is mostly used with static server farms dedicated to return a
3205 "sorry" page when an application is completely offline.
3206
3207 If this option has been enabled in a "defaults" section, it can be disabled
3208 in a specific instance by prepending the "no" keyword before it.
3209
3210
3211option checkcache
3212no option checkcache
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003213 Analyze all server responses and block requests with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003214 May be used in sections : defaults | frontend | listen | backend
3215 yes | no | yes | yes
3216 Arguments : none
3217
3218 Some high-level frameworks set application cookies everywhere and do not
3219 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003220 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003221 high risk of session crossing or stealing between users traversing the same
3222 caches. In some situations, it is better to block the response than to let
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02003223 some sensitive session information go in the wild.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003224
3225 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003226 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01003227 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003228 response to check if there's a risk of caching a cookie on a client-side
3229 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01003230 to the client are :
3231 - all those without "Set-Cookie" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003232 - all those with a return code other than 200, 203, 206, 300, 301, 410,
Willy Tarreau198a7442008-01-17 12:05:32 +01003233 provided that the server has not set a "Cache-control: public" header ;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003234 - all those that come from a POST request, provided that the server has not
3235 set a 'Cache-Control: public' header ;
3236 - those with a 'Pragma: no-cache' header
3237 - those with a 'Cache-control: private' header
3238 - those with a 'Cache-control: no-store' header
3239 - those with a 'Cache-control: max-age=0' header
3240 - those with a 'Cache-control: s-maxage=0' header
3241 - those with a 'Cache-control: no-cache' header
3242 - those with a 'Cache-control: no-cache="set-cookie"' header
3243 - those with a 'Cache-control: no-cache="set-cookie,' header
3244 (allowing other fields after set-cookie)
3245
3246 If a response doesn't respect these requirements, then it will be blocked
Willy Tarreau198a7442008-01-17 12:05:32 +01003247 just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003248 The session state shows "PH--" meaning that the proxy blocked the response
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003249 during headers processing. Additionally, an alert will be sent in the logs so
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003250 that admins are informed that there's something to be fixed.
3251
3252 Due to the high impact on the application, the application should be tested
3253 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003254 good practice to always activate it during tests, even if it is not used in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003255 production, as it will report potentially dangerous application behaviours.
3256
3257 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
3260
3261option clitcpka
3262no option clitcpka
3263 Enable or disable the sending of TCP keepalive packets on the client side
3264 May be used in sections : defaults | frontend | listen | backend
3265 yes | yes | yes | no
3266 Arguments : none
3267
3268 When there is a firewall or any session-aware component between a client and
3269 a server, and when the protocol involves very long sessions with long idle
3270 periods (eg: remote desktops), there is a risk that one of the intermediate
3271 components decides to expire a session which has remained idle for too long.
3272
3273 Enabling socket-level TCP keep-alives makes the system regularly send packets
3274 to the other end of the connection, leaving it active. The delay between
3275 keep-alive probes is controlled by the system only and depends both on the
3276 operating system and its tuning parameters.
3277
3278 It is important to understand that keep-alive packets are neither emitted nor
3279 received at the application level. It is only the network stacks which sees
3280 them. For this reason, even if one side of the proxy already uses keep-alives
3281 to maintain its connection alive, those keep-alive packets will not be
3282 forwarded to the other side of the proxy.
3283
3284 Please note that this has nothing to do with HTTP keep-alive.
3285
3286 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
3287 client side of a connection, which should help when session expirations are
3288 noticed between HAProxy and a client.
3289
3290 If this option has been enabled in a "defaults" section, it can be disabled
3291 in a specific instance by prepending the "no" keyword before it.
3292
3293 See also : "option srvtcpka", "option tcpka"
3294
3295
Willy Tarreau0ba27502007-12-24 16:55:16 +01003296option contstats
3297 Enable continuous traffic statistics updates
3298 May be used in sections : defaults | frontend | listen | backend
3299 yes | yes | yes | no
3300 Arguments : none
3301
3302 By default, counters used for statistics calculation are incremented
3303 only when a session finishes. It works quite well when serving small
3304 objects, but with big ones (for example large images or archives) or
3305 with A/V streaming, a graph generated from haproxy counters looks like
3306 a hedgehog. With this option enabled counters get incremented continuously,
3307 during a whole session. Recounting touches a hotpath directly so
3308 it is not enabled by default, as it has small performance impact (~0.5%).
3309
3310
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003311option dontlog-normal
3312no option dontlog-normal
3313 Enable or disable logging of normal, successful connections
3314 May be used in sections : defaults | frontend | listen | backend
3315 yes | yes | yes | no
3316 Arguments : none
3317
3318 There are large sites dealing with several thousand connections per second
3319 and for which logging is a major pain. Some of them are even forced to turn
3320 logs off and cannot debug production issues. Setting this option ensures that
3321 normal connections, those which experience no error, no timeout, no retry nor
3322 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
3323 mode, the response status code is checked and return codes 5xx will still be
3324 logged.
3325
3326 It is strongly discouraged to use this option as most of the time, the key to
3327 complex issues is in the normal logs which will not be logged here. If you
3328 need to separate logs, see the "log-separate-errors" option instead.
3329
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003330 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003331 logging.
3332
3333
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003334option dontlognull
3335no option dontlognull
3336 Enable or disable logging of null connections
3337 May be used in sections : defaults | frontend | listen | backend
3338 yes | yes | yes | no
3339 Arguments : none
3340
3341 In certain environments, there are components which will regularly connect to
3342 various systems to ensure that they are still alive. It can be the case from
3343 another load balancer as well as from monitoring systems. By default, even a
3344 simple port probe or scan will produce a log. If those connections pollute
3345 the logs too much, it is possible to enable option "dontlognull" to indicate
3346 that a connection on which no data has been transferred will not be logged,
3347 which typically corresponds to those probes.
3348
3349 It is generally recommended not to use this option in uncontrolled
3350 environments (eg: internet), otherwise scans and other malicious activities
3351 would not be logged.
3352
3353 If this option has been enabled in a "defaults" section, it can be disabled
3354 in a specific instance by prepending the "no" keyword before it.
3355
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003356 See also : "log", "monitor-net", "monitor-uri" and section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003357
3358
3359option forceclose
3360no option forceclose
3361 Enable or disable active connection closing after response is transferred.
3362 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaua31e5df2009-12-30 01:10:35 +01003363 yes | yes | yes | yes
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003364 Arguments : none
3365
3366 Some HTTP servers do not necessarily close the connections when they receive
3367 the "Connection: close" set by "option httpclose", and if the client does not
3368 close either, then the connection remains open till the timeout expires. This
3369 causes high number of simultaneous connections on the servers and shows high
3370 global session times in the logs.
3371
3372 When this happens, it is possible to use "option forceclose". It will
Willy Tarreau82eeaf22009-12-29 12:09:05 +01003373 actively close the outgoing server channel as soon as the server has finished
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003374 to respond. This option implicitly enables the "httpclose" option. Note that
3375 this option also enables the parsing of the full request and response, which
3376 means we can close the connection to the server very quickly, releasing some
3377 resources earlier than with httpclose.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003378
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003379 This option may also be combined with "option http-pretend-keepalive", which
3380 will disable sending of the "Connection: close" header, but will still cause
3381 the connection to be closed once the whole response is received.
3382
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003383 If this option has been enabled in a "defaults" section, it can be disabled
3384 in a specific instance by prepending the "no" keyword before it.
3385
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003386 See also : "option httpclose" and "option http-pretend-keepalive"
Willy Tarreaubf1f8162007-12-28 17:42:56 +01003387
3388
Willy Tarreau87cf5142011-08-19 22:57:24 +02003389option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003390 Enable insertion of the X-Forwarded-For header to requests sent to servers
3391 May be used in sections : defaults | frontend | listen | backend
3392 yes | yes | yes | yes
3393 Arguments :
3394 <network> is an optional argument used to disable this option for sources
3395 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02003396 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01003397 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003398
3399 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
3400 their client address. This is sometimes annoying when the client's IP address
3401 is expected in server logs. To solve this problem, the well-known HTTP header
3402 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
3403 This header contains a value representing the client's IP address. Since this
3404 header is always appended at the end of the existing header list, the server
3405 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02003406 the server's manual to find how to enable use of this standard header. Note
3407 that only the last occurrence of the header must be used, since it is really
3408 possible that the client has already brought one.
3409
Willy Tarreaud72758d2010-01-12 10:42:19 +01003410 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02003411 the default "X-Forwarded-For". This can be useful where you might already
Willy Tarreaud72758d2010-01-12 10:42:19 +01003412 have a "X-Forwarded-For" header from a different application (eg: stunnel),
3413 and you need preserve it. Also if your backend server doesn't use the
Ross Westaf72a1d2008-08-03 10:51:45 +02003414 "X-Forwarded-For" header and requires different one (eg: Zeus Web Servers
3415 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01003416
3417 Sometimes, a same HAProxy instance may be shared between a direct client
3418 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
3419 used to decrypt HTTPS traffic). It is possible to disable the addition of the
3420 header for a known source address or network by adding the "except" keyword
3421 followed by the network address. In this case, any source IP matching the
3422 network will not cause an addition of this header. Most common uses are with
3423 private networks or 127.0.0.1.
3424
Willy Tarreau87cf5142011-08-19 22:57:24 +02003425 Alternatively, the keyword "if-none" states that the header will only be
3426 added if it is not present. This should only be used in perfectly trusted
3427 environment, as this might cause a security issue if headers reaching haproxy
3428 are under the control of the end-user.
3429
Willy Tarreauc27debf2008-01-06 08:57:02 +01003430 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02003431 least one of them uses it, the header will be added. Note that the backend's
3432 setting of the header subargument takes precedence over the frontend's if
Willy Tarreau87cf5142011-08-19 22:57:24 +02003433 both are defined. In the case of the "if-none" argument, if at least one of
3434 the frontend or the backend does not specify it, it wants the addition to be
3435 mandatory, so it wins.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003436
Willy Tarreau87cf5142011-08-19 22:57:24 +02003437 It is important to note that by default, HAProxy works in tunnel mode and
3438 only inspects the first request of a connection, meaning that only the first
3439 request will have the header appended, which is certainly not what you want.
3440 In order to fix this, ensure that any of the "httpclose", "forceclose" or
3441 "http-server-close" options is set when using this option.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003442
Ross Westaf72a1d2008-08-03 10:51:45 +02003443 Examples :
Willy Tarreauc27debf2008-01-06 08:57:02 +01003444 # Public HTTP address also used by stunnel on the same machine
3445 frontend www
3446 mode http
3447 option forwardfor except 127.0.0.1 # stunnel already adds the header
3448
Ross Westaf72a1d2008-08-03 10:51:45 +02003449 # Those servers want the IP Address in X-Client
3450 backend www
3451 mode http
3452 option forwardfor header X-Client
3453
Willy Tarreau87cf5142011-08-19 22:57:24 +02003454 See also : "option httpclose", "option http-server-close",
3455 "option forceclose"
Willy Tarreauc27debf2008-01-06 08:57:02 +01003456
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003457
Willy Tarreau96e31212011-05-30 18:10:30 +02003458option http-no-delay
3459no option http-no-delay
3460 Instruct the system to favor low interactive delays over performance in HTTP
3461 May be used in sections : defaults | frontend | listen | backend
3462 yes | yes | yes | yes
3463 Arguments : none
3464
3465 In HTTP, each payload is unidirectional and has no notion of interactivity.
3466 Any agent is expected to queue data somewhat for a reasonably low delay.
3467 There are some very rare server-to-server applications that abuse the HTTP
3468 protocol and expect the payload phase to be highly interactive, with many
3469 interleaved data chunks in both directions within a single request. This is
3470 absolutely not supported by the HTTP specification and will not work across
3471 most proxies or servers. When such applications attempt to do this through
3472 haproxy, it works but they will experience high delays due to the network
3473 optimizations which favor performance by instructing the system to wait for
3474 enough data to be available in order to only send full packets. Typical
3475 delays are around 200 ms per round trip. Note that this only happens with
3476 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
3477 affected.
3478
3479 When "option http-no-delay" is present in either the frontend or the backend
3480 used by a connection, all such optimizations will be disabled in order to
3481 make the exchanges as fast as possible. Of course this offers no guarantee on
3482 the functionality, as it may break at any other place. But if it works via
3483 HAProxy, it will work as fast as possible. This option should never be used
3484 by default, and should never be used at all unless such a buggy application
3485 is discovered. The impact of using this option is an increase of bandwidth
3486 usage and CPU usage, which may significantly lower performance in high
3487 latency environments.
3488
3489
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003490option http-pretend-keepalive
3491no option http-pretend-keepalive
3492 Define whether haproxy will announce keepalive to the server or not
3493 May be used in sections : defaults | frontend | listen | backend
3494 yes | yes | yes | yes
3495 Arguments : none
3496
3497 When running with "option http-server-close" or "option forceclose", haproxy
3498 adds a "Connection: close" header to the request forwarded to the server.
3499 Unfortunately, when some servers see this header, they automatically refrain
3500 from using the chunked encoding for responses of unknown length, while this
3501 is totally unrelated. The immediate effect is that this prevents haproxy from
3502 maintaining the client connection alive. A second effect is that a client or
3503 a cache could receive an incomplete response without being aware of it, and
3504 consider the response complete.
3505
3506 By setting "option http-pretend-keepalive", haproxy will make the server
3507 believe it will keep the connection alive. The server will then not fall back
3508 to the abnormal undesired above. When haproxy gets the whole response, it
3509 will close the connection with the server just as it would do with the
3510 "forceclose" option. That way the client gets a normal response and the
3511 connection is correctly closed on the server side.
3512
3513 It is recommended not to enable this option by default, because most servers
3514 will more efficiently close the connection themselves after the last packet,
3515 and release its buffers slightly earlier. Also, the added packet on the
3516 network could slightly reduce the overall peak performance. However it is
3517 worth noting that when this option is enabled, haproxy will have slightly
3518 less work to do. So if haproxy is the bottleneck on the whole architecture,
3519 enabling this option might save a few CPU cycles.
3520
3521 This option may be set both in a frontend and in a backend. It is enabled if
3522 at least one of the frontend or backend holding a connection has it enabled.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003523 This option may be combined with "option httpclose", which will cause
Willy Tarreau22a95342010-09-29 14:31:41 +02003524 keepalive to be announced to the server and close to be announced to the
3525 client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02003526
3527 If this option has been enabled in a "defaults" section, it can be disabled
3528 in a specific instance by prepending the "no" keyword before it.
3529
3530 See also : "option forceclose" and "option http-server-close"
3531
Willy Tarreauc27debf2008-01-06 08:57:02 +01003532
Willy Tarreaub608feb2010-01-02 22:47:18 +01003533option http-server-close
3534no option http-server-close
3535 Enable or disable HTTP connection closing on the server side
3536 May be used in sections : defaults | frontend | listen | backend
3537 yes | yes | yes | yes
3538 Arguments : none
3539
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003540 By default, when a client communicates with a server, HAProxy will only
3541 analyze, log, and process the first request of each connection. Setting
3542 "option http-server-close" enables HTTP connection-close mode on the server
3543 side while keeping the ability to support HTTP keep-alive and pipelining on
3544 the client side. This provides the lowest latency on the client side (slow
3545 network) and the fastest session reuse on the server side to save server
3546 resources, similarly to "option forceclose". It also permits non-keepalive
3547 capable servers to be served in keep-alive mode to the clients if they
3548 conform to the requirements of RFC2616. Please note that some servers do not
3549 always conform to those requirements when they see "Connection: close" in the
3550 request. The effect will be that keep-alive will never be used. A workaround
3551 consists in enabling "option http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003552
3553 At the moment, logs will not indicate whether requests came from the same
3554 session or not. The accept date reported in the logs corresponds to the end
3555 of the previous request, and the request time corresponds to the time spent
3556 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01003557 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
3558 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01003559
3560 This option may be set both in a frontend and in a backend. It is enabled if
3561 at least one of the frontend or backend holding a connection has it enabled.
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003562 It is worth noting that "option forceclose" has precedence over "option
3563 http-server-close" and that combining "http-server-close" with "httpclose"
3564 basically achieve the same result as "forceclose".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003565
3566 If this option has been enabled in a "defaults" section, it can be disabled
3567 in a specific instance by prepending the "no" keyword before it.
3568
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003569 See also : "option forceclose", "option http-pretend-keepalive",
3570 "option httpclose" and "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01003571
3572
Willy Tarreau88d349d2010-01-25 12:15:43 +01003573option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01003574no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01003575 Make use of non-standard Proxy-Connection header instead of Connection
3576 May be used in sections : defaults | frontend | listen | backend
3577 yes | yes | yes | no
3578 Arguments : none
3579
3580 While RFC2616 explicitly states that HTTP/1.1 agents must use the
3581 Connection header to indicate their wish of persistent or non-persistent
3582 connections, both browsers and proxies ignore this header for proxied
3583 connections and make use of the undocumented, non-standard Proxy-Connection
3584 header instead. The issue begins when trying to put a load balancer between
3585 browsers and such proxies, because there will be a difference between what
3586 haproxy understands and what the client and the proxy agree on.
3587
3588 By setting this option in a frontend, haproxy can automatically switch to use
3589 that non-standard header if it sees proxied requests. A proxied request is
3590 defined here as one where the URI begins with neither a '/' nor a '*'. The
3591 choice of header only affects requests passing through proxies making use of
3592 one of the "httpclose", "forceclose" and "http-server-close" options. Note
3593 that this option can only be specified in a frontend and will affect the
3594 request along its whole life.
3595
Willy Tarreau844a7e72010-01-31 21:46:18 +01003596 Also, when this option is set, a request which requires authentication will
3597 automatically switch to use proxy authentication headers if it is itself a
3598 proxied request. That makes it possible to check or enforce authentication in
3599 front of an existing proxy.
3600
Willy Tarreau88d349d2010-01-25 12:15:43 +01003601 This option should normally never be used, except in front of a proxy.
3602
3603 See also : "option httpclose", "option forceclose" and "option
3604 http-server-close".
3605
3606
Willy Tarreaud63335a2010-02-26 12:56:52 +01003607option httpchk
3608option httpchk <uri>
3609option httpchk <method> <uri>
3610option httpchk <method> <uri> <version>
3611 Enable HTTP protocol to check on the servers health
3612 May be used in sections : defaults | frontend | listen | backend
3613 yes | no | yes | yes
3614 Arguments :
3615 <method> is the optional HTTP method used with the requests. When not set,
3616 the "OPTIONS" method is used, as it generally requires low server
3617 processing and is easy to filter out from the logs. Any method
3618 may be used, though it is not recommended to invent non-standard
3619 ones.
3620
3621 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
3622 which is accessible by default on almost any server, but may be
3623 changed to any other URI. Query strings are permitted.
3624
3625 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
3626 but some servers might behave incorrectly in HTTP 1.0, so turning
3627 it to HTTP/1.1 may sometimes help. Note that the Host field is
3628 mandatory in HTTP/1.1, and as a trick, it is possible to pass it
3629 after "\r\n" following the version string.
3630
3631 By default, server health checks only consist in trying to establish a TCP
3632 connection. When "option httpchk" is specified, a complete HTTP request is
3633 sent once the TCP connection is established, and responses 2xx and 3xx are
3634 considered valid, while all other ones indicate a server failure, including
3635 the lack of any response.
3636
3637 The port and interval are specified in the server configuration.
3638
3639 This option does not necessarily require an HTTP backend, it also works with
3640 plain TCP backends. This is particularly useful to check simple scripts bound
3641 to some dedicated ports using the inetd daemon.
3642
3643 Examples :
3644 # Relay HTTPS traffic to Apache instance and check service availability
3645 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
3646 backend https_relay
3647 mode tcp
3648 option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www
3649 server apache1 192.168.1.1:443 check port 80
3650
Simon Hormana2b9dad2013-02-12 10:45:54 +09003651 See also : "option lb-agent-chk", "option ssl-hello-chk", "option smtpchk",
3652 "option mysql-check", "option pgsql-check", "http-check" and
3653 the "check", "port" and "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01003654
3655
Willy Tarreauc27debf2008-01-06 08:57:02 +01003656option httpclose
3657no option httpclose
3658 Enable or disable passive HTTP connection closing
3659 May be used in sections : defaults | frontend | listen | backend
3660 yes | yes | yes | yes
3661 Arguments : none
3662
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003663 By default, when a client communicates with a server, HAProxy will only
3664 analyze, log, and process the first request of each connection. If "option
3665 httpclose" is set, it will check if a "Connection: close" header is already
3666 set in each direction, and will add one if missing. Each end should react to
3667 this by actively closing the TCP connection after each transfer, thus
3668 resulting in a switch to the HTTP close mode. Any "Connection" header
3669 different from "close" will also be removed.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003670
3671 It seldom happens that some servers incorrectly ignore this header and do not
Jamie Gloudonaaa21002012-08-25 00:18:33 -04003672 close the connection even though they reply "Connection: close". For this
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003673 reason, they are not compatible with older HTTP 1.0 browsers. If this happens
3674 it is possible to use the "option forceclose" which actively closes the
3675 request connection once the server responds. Option "forceclose" also
3676 releases the server connection earlier because it does not have to wait for
3677 the client to acknowledge it.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003678
3679 This option may be set both in a frontend and in a backend. It is enabled if
3680 at least one of the frontend or backend holding a connection has it enabled.
3681 If "option forceclose" is specified too, it has precedence over "httpclose".
Willy Tarreau0dfdf192010-01-05 11:33:11 +01003682 If "option http-server-close" is enabled at the same time as "httpclose", it
3683 basically achieves the same result as "option forceclose".
Willy Tarreauc27debf2008-01-06 08:57:02 +01003684
3685 If this option has been enabled in a "defaults" section, it can be disabled
3686 in a specific instance by prepending the "no" keyword before it.
3687
Patrick Mezard9ec2ec42010-06-12 17:02:45 +02003688 See also : "option forceclose", "option http-server-close" and
3689 "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01003690
3691
Emeric Brun3a058f32009-06-30 18:26:00 +02003692option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01003693 Enable logging of HTTP request, session state and timers
3694 May be used in sections : defaults | frontend | listen | backend
3695 yes | yes | yes | yes
Emeric Brun3a058f32009-06-30 18:26:00 +02003696 Arguments :
3697 clf if the "clf" argument is added, then the output format will be
3698 the CLF format instead of HAProxy's default HTTP format. You can
3699 use this when you need to feed HAProxy's logs through a specific
3700 log analyser which only support the CLF format and which is not
3701 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003702
3703 By default, the log output format is very poor, as it only contains the
3704 source and destination addresses, and the instance name. By specifying
3705 "option httplog", each log line turns into a much richer format including,
3706 but not limited to, the HTTP request, the connection timers, the session
3707 status, the connections numbers, the captured headers and cookies, the
3708 frontend, backend and server name, and of course the source address and
3709 ports.
3710
3711 This option may be set either in the frontend or the backend.
3712
Emeric Brun3a058f32009-06-30 18:26:00 +02003713 If this option has been enabled in a "defaults" section, it can be disabled
3714 in a specific instance by prepending the "no" keyword before it. Specifying
3715 only "option httplog" will automatically clear the 'clf' mode if it was set
3716 by default.
3717
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003718 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01003719
Willy Tarreau55165fe2009-05-10 12:02:55 +02003720
3721option http_proxy
3722no option http_proxy
3723 Enable or disable plain HTTP proxy mode
3724 May be used in sections : defaults | frontend | listen | backend
3725 yes | yes | yes | yes
3726 Arguments : none
3727
3728 It sometimes happens that people need a pure HTTP proxy which understands
3729 basic proxy requests without caching nor any fancy feature. In this case,
3730 it may be worth setting up an HAProxy instance with the "option http_proxy"
3731 set. In this mode, no server is declared, and the connection is forwarded to
3732 the IP address and port found in the URL after the "http://" scheme.
3733
3734 No host address resolution is performed, so this only works when pure IP
3735 addresses are passed. Since this option's usage perimeter is rather limited,
3736 it will probably be used only by experts who know they need exactly it. Last,
3737 if the clients are susceptible of sending keep-alive requests, it will be
Cyril Bonté2409e682010-12-14 22:47:51 +01003738 needed to add "option httpclose" to ensure that all requests will correctly
Willy Tarreau55165fe2009-05-10 12:02:55 +02003739 be analyzed.
3740
3741 If this option has been enabled in a "defaults" section, it can be disabled
3742 in a specific instance by prepending the "no" keyword before it.
3743
3744 Example :
3745 # this backend understands HTTP proxy requests and forwards them directly.
3746 backend direct_forward
3747 option httpclose
3748 option http_proxy
3749
3750 See also : "option httpclose"
3751
Willy Tarreau211ad242009-10-03 21:45:07 +02003752
Jamie Gloudon801a0a32012-08-25 00:18:33 -04003753option independent-streams
3754no option independent-streams
3755 Enable or disable independent timeout processing for both directions
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02003756 May be used in sections : defaults | frontend | listen | backend
3757 yes | yes | yes | yes
3758 Arguments : none
3759
3760 By default, when data is sent over a socket, both the write timeout and the
3761 read timeout for that socket are refreshed, because we consider that there is
3762 activity on that socket, and we have no other means of guessing if we should
3763 receive data or not.
3764
3765 While this default behaviour is desirable for almost all applications, there
3766 exists a situation where it is desirable to disable it, and only refresh the
3767 read timeout if there are incoming data. This happens on sessions with large
3768 timeouts and low amounts of exchanged data such as telnet session. If the
3769 server suddenly disappears, the output data accumulates in the system's
3770 socket buffers, both timeouts are correctly refreshed, and there is no way
3771 to know the server does not receive them, so we don't timeout. However, when
3772 the underlying protocol always echoes sent data, it would be enough by itself
3773 to detect the issue using the read timeout. Note that this problem does not
3774 happen with more verbose protocols because data won't accumulate long in the
3775 socket buffers.
3776
3777 When this option is set on the frontend, it will disable read timeout updates
3778 on data sent to the client. There probably is little use of this case. When
3779 the option is set on the backend, it will disable read timeout updates on
3780 data sent to the server. Doing so will typically break large HTTP posts from
3781 slow lines, so use it with caution.
3782
Jamie Gloudon801a0a32012-08-25 00:18:33 -04003783 Note: older versions used to call this setting "option independant-streams"
3784 with a spelling mistake. This spelling is still supported but
3785 deprecated.
3786
Willy Tarreauce887fd2012-05-12 12:50:00 +02003787 See also : "timeout client", "timeout server" and "timeout tunnel"
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02003788
3789
Simon Hormana2b9dad2013-02-12 10:45:54 +09003790option lb-agent-chk
3791 Use a TCP connection to obtain a metric of server health
3792 May be used in sections : defaults | frontend | listen | backend
3793 yes | no | yes | yes
3794 Arguments : none
3795
3796 This alters health checking behaviour by connecting making a TCP
3797 connection and reading an ASCII string. The string should have one of
3798 the following forms:
3799
3800 * An ASCII representation of an positive integer percentage.
3801 e.g. "75%"
3802
3803 Values in this format will set the weight proportional to the initial
3804 weight of a server as configured when haproxy starts.
3805
3806 * The string "drain".
3807
3808 This will cause the weight of a server to be set to 0, and thus it will
3809 not accept any new connections other than those that are accepted via
3810 persistence.
3811
3812 * The string "down", optionally followed by a description string.
3813
3814 Mark the server as down and log the description string as the reason.
3815
3816 * The string "stopped", optionally followed by a description string.
3817
3818 This currently has the same behaviour as down (iii).
3819
3820 * The string "fail", optionally followed by a description string.
3821
3822 This currently has the same behaviour as down (iii).
3823
3824 The use of an alternate check-port, used to obtain agent heath check
3825 information described above as opposed to the port of the service, may be
3826 useful in conjunction with this option.
3827
3828
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02003829option ldap-check
3830 Use LDAPv3 health checks for server testing
3831 May be used in sections : defaults | frontend | listen | backend
3832 yes | no | yes | yes
3833 Arguments : none
3834
3835 It is possible to test that the server correctly talks LDAPv3 instead of just
3836 testing that it accepts the TCP connection. When this option is set, an
3837 LDAPv3 anonymous simple bind message is sent to the server, and the response
3838 is analyzed to find an LDAPv3 bind response message.
3839
3840 The server is considered valid only when the LDAP response contains success
3841 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
3842
3843 Logging of bind requests is server dependent see your documentation how to
3844 configure it.
3845
3846 Example :
3847 option ldap-check
3848
3849 See also : "option httpchk"
3850
3851
Willy Tarreau211ad242009-10-03 21:45:07 +02003852option log-health-checks
3853no option log-health-checks
3854 Enable or disable logging of health checks
3855 May be used in sections : defaults | frontend | listen | backend
3856 yes | no | yes | yes
3857 Arguments : none
3858
3859 Enable health checks logging so it possible to check for example what
3860 was happening before a server crash. Failed health check are logged if
3861 server is UP and succeeded health checks if server is DOWN, so the amount
3862 of additional information is limited.
3863
3864 If health check logging is enabled no health check status is printed
3865 when servers is set up UP/DOWN/ENABLED/DISABLED.
3866
3867 See also: "log" and section 8 about logging.
3868
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003869
3870option log-separate-errors
3871no option log-separate-errors
3872 Change log level for non-completely successful connections
3873 May be used in sections : defaults | frontend | listen | backend
3874 yes | yes | yes | no
3875 Arguments : none
3876
3877 Sometimes looking for errors in logs is not easy. This option makes haproxy
3878 raise the level of logs containing potentially interesting information such
3879 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
3880 level changes from "info" to "err". This makes it possible to log them
3881 separately to a different file with most syslog daemons. Be careful not to
3882 remove them from the original file, otherwise you would lose ordering which
3883 provides very important information.
3884
3885 Using this option, large sites dealing with several thousand connections per
3886 second may log normal traffic to a rotating buffer and only archive smaller
3887 error logs.
3888
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003889 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02003890 logging.
3891
Willy Tarreauc27debf2008-01-06 08:57:02 +01003892
3893option logasap
3894no option logasap
3895 Enable or disable early logging of HTTP requests
3896 May be used in sections : defaults | frontend | listen | backend
3897 yes | yes | yes | no
3898 Arguments : none
3899
3900 By default, HTTP requests are logged upon termination so that the total
3901 transfer time and the number of bytes appear in the logs. When large objects
3902 are being transferred, it may take a while before the request appears in the
3903 logs. Using "option logasap", the request gets logged as soon as the server
3904 sends the complete headers. The only missing information in the logs will be
3905 the total number of bytes which will indicate everything except the amount
3906 of data transferred, and the total time which will not take the transfer
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003907 time into account. In such a situation, it's a good practice to capture the
Willy Tarreauc27debf2008-01-06 08:57:02 +01003908 "Content-Length" response header so that the logs at least indicate how many
3909 bytes are expected to be transferred.
3910
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003911 Examples :
3912 listen http_proxy 0.0.0.0:80
3913 mode http
3914 option httplog
3915 option logasap
3916 log 192.168.2.200 local3
3917
3918 >>> Feb 6 12:14:14 localhost \
3919 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
3920 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
3921 "GET /image.iso HTTP/1.0"
3922
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003923 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01003924 logging.
3925
3926
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003927option mysql-check [ user <username> ]
3928 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003929 May be used in sections : defaults | frontend | listen | backend
3930 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003931 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003932 <username> This is the username which will be used when connecting to MySQL
3933 server.
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02003934
3935 If you specify a username, the check consists of sending two MySQL packet,
3936 one Client Authentication packet, and one QUIT packet, to correctly close
3937 MySQL session. We then parse the MySQL Handshake Initialisation packet and/or
3938 Error packet. It is a basic but useful test which does not produce error nor
3939 aborted connect on the server. However, it requires adding an authorization
3940 in the MySQL table, like this :
3941
3942 USE mysql;
3943 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
3944 FLUSH PRIVILEGES;
3945
3946 If you don't specify a username (it is deprecated and not recommended), the
3947 check only consists in parsing the Mysql Handshake Initialisation packet or
3948 Error packet, we don't send anything in this mode. It was reported that it
3949 can generate lockout if check is too frequent and/or if there is not enough
3950 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
3951 value as if a connection is established successfully within fewer than MySQL
3952 "max_connect_errors" attempts after a previous connection was interrupted,
3953 the error count for the host is cleared to zero. If HAProxy's server get
3954 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
3955
3956 Remember that this does not check database presence nor database consistency.
3957 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003958
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02003959 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003960
3961 Most often, an incoming MySQL server needs to see the client's IP address for
3962 various purposes, including IP privilege matching and connection logging.
3963 When possible, it is often wise to masquerade the client's IP address when
3964 connecting to the server using the "usesrc" argument of the "source" keyword,
3965 which requires the cttproxy feature to be compiled in, and the MySQL server
3966 to route the client via the machine hosting haproxy.
3967
3968 See also: "option httpchk"
3969
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003970option pgsql-check [ user <username> ]
3971 Use PostgreSQL health checks for server testing
3972 May be used in sections : defaults | frontend | listen | backend
3973 yes | no | yes | yes
3974 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003975 <username> This is the username which will be used when connecting to
3976 PostgreSQL server.
Rauf Kuliyev38b41562011-01-04 15:14:13 +01003977
3978 The check sends a PostgreSQL StartupMessage and waits for either
3979 Authentication request or ErrorResponse message. It is a basic but useful
3980 test which does not produce error nor aborted connect on the server.
3981 This check is identical with the "mysql-check".
3982
3983 See also: "option httpchk"
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01003984
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003985option nolinger
3986no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003987 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003988 May be used in sections: defaults | frontend | listen | backend
3989 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01003990 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01003991
3992 When clients or servers abort connections in a dirty way (eg: they are
3993 physically disconnected), the session timeouts triggers and the session is
3994 closed. But it will remain in FIN_WAIT1 state for some time in the system,
3995 using some resources and possibly limiting the ability to establish newer
3996 connections.
3997
3998 When this happens, it is possible to activate "option nolinger" which forces
3999 the system to immediately remove any socket's pending data on close. Thus,
4000 the session is instantly purged from the system's tables. This usually has
4001 side effects such as increased number of TCP resets due to old retransmits
4002 getting immediately rejected. Some firewalls may sometimes complain about
4003 this too.
4004
4005 For this reason, it is not recommended to use this option when not absolutely
4006 needed. You know that you need it when you have thousands of FIN_WAIT1
4007 sessions on your system (TIME_WAIT ones do not count).
4008
4009 This option may be used both on frontends and backends, depending on the side
4010 where it is required. Use it on the frontend for clients, and on the backend
4011 for servers.
4012
4013 If this option has been enabled in a "defaults" section, it can be disabled
4014 in a specific instance by prepending the "no" keyword before it.
4015
4016
Willy Tarreau55165fe2009-05-10 12:02:55 +02004017option originalto [ except <network> ] [ header <name> ]
4018 Enable insertion of the X-Original-To header to requests sent to servers
4019 May be used in sections : defaults | frontend | listen | backend
4020 yes | yes | yes | yes
4021 Arguments :
4022 <network> is an optional argument used to disable this option for sources
4023 matching <network>
4024 <name> an optional argument to specify a different "X-Original-To"
4025 header name.
4026
4027 Since HAProxy can work in transparent mode, every request from a client can
4028 be redirected to the proxy and HAProxy itself can proxy every request to a
4029 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
4030 be lost. This is annoying when you want access rules based on destination ip
4031 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
4032 added by HAProxy to all requests sent to the server. This header contains a
4033 value representing the original destination IP address. Since this must be
4034 configured to always use the last occurrence of this header only. Note that
4035 only the last occurrence of the header must be used, since it is really
4036 possible that the client has already brought one.
4037
4038 The keyword "header" may be used to supply a different header name to replace
4039 the default "X-Original-To". This can be useful where you might already
4040 have a "X-Original-To" header from a different application, and you need
4041 preserve it. Also if your backend server doesn't use the "X-Original-To"
4042 header and requires different one.
4043
4044 Sometimes, a same HAProxy instance may be shared between a direct client
4045 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
4046 used to decrypt HTTPS traffic). It is possible to disable the addition of the
4047 header for a known source address or network by adding the "except" keyword
4048 followed by the network address. In this case, any source IP matching the
4049 network will not cause an addition of this header. Most common uses are with
4050 private networks or 127.0.0.1.
4051
4052 This option may be specified either in the frontend or in the backend. If at
4053 least one of them uses it, the header will be added. Note that the backend's
4054 setting of the header subargument takes precedence over the frontend's if
4055 both are defined.
4056
Willy Tarreau87cf5142011-08-19 22:57:24 +02004057 It is important to note that by default, HAProxy works in tunnel mode and
4058 only inspects the first request of a connection, meaning that only the first
4059 request will have the header appended, which is certainly not what you want.
4060 In order to fix this, ensure that any of the "httpclose", "forceclose" or
4061 "http-server-close" options is set when using this option.
Willy Tarreau55165fe2009-05-10 12:02:55 +02004062
4063 Examples :
4064 # Original Destination address
4065 frontend www
4066 mode http
4067 option originalto except 127.0.0.1
4068
4069 # Those servers want the IP Address in X-Client-Dst
4070 backend www
4071 mode http
4072 option originalto header X-Client-Dst
4073
Willy Tarreau87cf5142011-08-19 22:57:24 +02004074 See also : "option httpclose", "option http-server-close",
4075 "option forceclose"
Willy Tarreau55165fe2009-05-10 12:02:55 +02004076
4077
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004078option persist
4079no option persist
4080 Enable or disable forced persistence on down servers
4081 May be used in sections: defaults | frontend | listen | backend
4082 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004083 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004084
4085 When an HTTP request reaches a backend with a cookie which references a dead
4086 server, by default it is redispatched to another server. It is possible to
4087 force the request to be sent to the dead server first using "option persist"
4088 if absolutely needed. A common use case is when servers are under extreme
4089 load and spend their time flapping. In this case, the users would still be
4090 directed to the server they opened the session on, in the hope they would be
4091 correctly served. It is recommended to use "option redispatch" in conjunction
4092 with this option so that in the event it would not be possible to connect to
4093 the server at all (server definitely dead), the client would finally be
4094 redirected to another valid server.
4095
4096 If this option has been enabled in a "defaults" section, it can be disabled
4097 in a specific instance by prepending the "no" keyword before it.
4098
Willy Tarreau4de91492010-01-22 19:10:05 +01004099 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004100
4101
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004102option redispatch
4103no option redispatch
4104 Enable or disable session redistribution in case of connection failure
4105 May be used in sections: defaults | frontend | listen | backend
4106 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004107 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004108
4109 In HTTP mode, if a server designated by a cookie is down, clients may
4110 definitely stick to it because they cannot flush the cookie, so they will not
4111 be able to access the service anymore.
4112
4113 Specifying "option redispatch" will allow the proxy to break their
4114 persistence and redistribute them to a working server.
4115
4116 It also allows to retry last connection to another server in case of multiple
4117 connection failures. Of course, it requires having "retries" set to a nonzero
4118 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01004119
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004120 This form is the preferred form, which replaces both the "redispatch" and
4121 "redisp" keywords.
4122
4123 If this option has been enabled in a "defaults" section, it can be disabled
4124 in a specific instance by prepending the "no" keyword before it.
4125
Willy Tarreau4de91492010-01-22 19:10:05 +01004126 See also : "redispatch", "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004127
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004128
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02004129option redis-check
4130 Use redis health checks for server testing
4131 May be used in sections : defaults | frontend | listen | backend
4132 yes | no | yes | yes
4133 Arguments : none
4134
4135 It is possible to test that the server correctly talks REDIS protocol instead
4136 of just testing that it accepts the TCP connection. When this option is set,
4137 a PING redis command is sent to the server, and the response is analyzed to
4138 find the "+PONG" response message.
4139
4140 Example :
4141 option redis-check
4142
4143 See also : "option httpchk"
4144
4145
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004146option smtpchk
4147option smtpchk <hello> <domain>
4148 Use SMTP health checks for server testing
4149 May be used in sections : defaults | frontend | listen | backend
4150 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01004151 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004152 <hello> is an optional argument. It is the "hello" command to use. It can
4153 be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other
4154 values will be turned into the default command ("HELO").
4155
4156 <domain> is the domain name to present to the server. It may only be
4157 specified (and is mandatory) if the hello command has been
4158 specified. By default, "localhost" is used.
4159
4160 When "option smtpchk" is set, the health checks will consist in TCP
4161 connections followed by an SMTP command. By default, this command is
4162 "HELO localhost". The server's return code is analyzed and only return codes
4163 starting with a "2" will be considered as valid. All other responses,
4164 including a lack of response will constitute an error and will indicate a
4165 dead server.
4166
4167 This test is meant to be used with SMTP servers or relays. Depending on the
4168 request, it is possible that some servers do not log each connection attempt,
4169 so you may want to experiment to improve the behaviour. Using telnet on port
4170 25 is often easier than adjusting the configuration.
4171
4172 Most often, an incoming SMTP server needs to see the client's IP address for
4173 various purposes, including spam filtering, anti-spoofing and logging. When
4174 possible, it is often wise to masquerade the client's IP address when
4175 connecting to the server using the "usesrc" argument of the "source" keyword,
4176 which requires the cttproxy feature to be compiled in.
4177
4178 Example :
4179 option smtpchk HELO mydomain.org
4180
4181 See also : "option httpchk", "source"
4182
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004183
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02004184option socket-stats
4185no option socket-stats
4186
4187 Enable or disable collecting & providing separate statistics for each socket.
4188 May be used in sections : defaults | frontend | listen | backend
4189 yes | yes | yes | no
4190
4191 Arguments : none
4192
4193
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004194option splice-auto
4195no option splice-auto
4196 Enable or disable automatic kernel acceleration on sockets in both directions
4197 May be used in sections : defaults | frontend | listen | backend
4198 yes | yes | yes | yes
4199 Arguments : none
4200
4201 When this option is enabled either on a frontend or on a backend, haproxy
4202 will automatically evaluate the opportunity to use kernel tcp splicing to
4203 forward data between the client and the server, in either direction. Haproxy
4204 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004205 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004206 are not much aggressive in order to limit excessive use of splicing. This
4207 option requires splicing to be enabled at compile time, and may be globally
4208 disabled with the global option "nosplice". Since splice uses pipes, using it
4209 requires that there are enough spare pipes.
4210
4211 Important note: kernel-based TCP splicing is a Linux-specific feature which
4212 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
4213 transfer data between sockets without copying these data to user-space, thus
4214 providing noticeable performance gains and CPU cycles savings. Since many
4215 early implementations are buggy, corrupt data and/or are inefficient, this
4216 feature is not enabled by default, and it should be used with extreme care.
4217 While it is not possible to detect the correctness of an implementation,
4218 2.6.29 is the first version offering a properly working implementation. In
4219 case of doubt, splicing may be globally disabled using the global "nosplice"
4220 keyword.
4221
4222 Example :
4223 option splice-auto
4224
4225 If this option has been enabled in a "defaults" section, it can be disabled
4226 in a specific instance by prepending the "no" keyword before it.
4227
4228 See also : "option splice-request", "option splice-response", and global
4229 options "nosplice" and "maxpipes"
4230
4231
4232option splice-request
4233no option splice-request
4234 Enable or disable automatic kernel acceleration on sockets for requests
4235 May be used in sections : defaults | frontend | listen | backend
4236 yes | yes | yes | yes
4237 Arguments : none
4238
4239 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004240 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004241 the client to the server. It might still use the recv/send scheme if there
4242 are no spare pipes left. This option requires splicing to be enabled at
4243 compile time, and may be globally disabled with the global option "nosplice".
4244 Since splice uses pipes, using it requires that there are enough spare pipes.
4245
4246 Important note: see "option splice-auto" for usage limitations.
4247
4248 Example :
4249 option splice-request
4250
4251 If this option has been enabled in a "defaults" section, it can be disabled
4252 in a specific instance by prepending the "no" keyword before it.
4253
4254 See also : "option splice-auto", "option splice-response", and global options
4255 "nosplice" and "maxpipes"
4256
4257
4258option splice-response
4259no option splice-response
4260 Enable or disable automatic kernel acceleration on sockets for responses
4261 May be used in sections : defaults | frontend | listen | backend
4262 yes | yes | yes | yes
4263 Arguments : none
4264
4265 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004266 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01004267 the server to the client. It might still use the recv/send scheme if there
4268 are no spare pipes left. This option requires splicing to be enabled at
4269 compile time, and may be globally disabled with the global option "nosplice".
4270 Since splice uses pipes, using it requires that there are enough spare pipes.
4271
4272 Important note: see "option splice-auto" for usage limitations.
4273
4274 Example :
4275 option splice-response
4276
4277 If this option has been enabled in a "defaults" section, it can be disabled
4278 in a specific instance by prepending the "no" keyword before it.
4279
4280 See also : "option splice-auto", "option splice-request", and global options
4281 "nosplice" and "maxpipes"
4282
4283
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004284option srvtcpka
4285no option srvtcpka
4286 Enable or disable the sending of TCP keepalive packets on the server side
4287 May be used in sections : defaults | frontend | listen | backend
4288 yes | no | yes | yes
4289 Arguments : none
4290
4291 When there is a firewall or any session-aware component between a client and
4292 a server, and when the protocol involves very long sessions with long idle
4293 periods (eg: remote desktops), there is a risk that one of the intermediate
4294 components decides to expire a session which has remained idle for too long.
4295
4296 Enabling socket-level TCP keep-alives makes the system regularly send packets
4297 to the other end of the connection, leaving it active. The delay between
4298 keep-alive probes is controlled by the system only and depends both on the
4299 operating system and its tuning parameters.
4300
4301 It is important to understand that keep-alive packets are neither emitted nor
4302 received at the application level. It is only the network stacks which sees
4303 them. For this reason, even if one side of the proxy already uses keep-alives
4304 to maintain its connection alive, those keep-alive packets will not be
4305 forwarded to the other side of the proxy.
4306
4307 Please note that this has nothing to do with HTTP keep-alive.
4308
4309 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
4310 server side of a connection, which should help when session expirations are
4311 noticed between HAProxy and a server.
4312
4313 If this option has been enabled in a "defaults" section, it can be disabled
4314 in a specific instance by prepending the "no" keyword before it.
4315
4316 See also : "option clitcpka", "option tcpka"
4317
4318
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004319option ssl-hello-chk
4320 Use SSLv3 client hello health checks for server testing
4321 May be used in sections : defaults | frontend | listen | backend
4322 yes | no | yes | yes
4323 Arguments : none
4324
4325 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
4326 possible to test that the server correctly talks SSL instead of just testing
4327 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
4328 SSLv3 client hello messages are sent once the connection is established to
4329 the server, and the response is analyzed to find an SSL server hello message.
4330 The server is considered valid only when the response contains this server
4331 hello message.
4332
4333 All servers tested till there correctly reply to SSLv3 client hello messages,
4334 and most servers tested do not even log the requests containing only hello
4335 messages, which is appreciable.
4336
Willy Tarreau763a95b2012-10-04 23:15:39 +02004337 Note that this check works even when SSL support was not built into haproxy
4338 because it forges the SSL message. When SSL support is available, it is best
4339 to use native SSL health checks instead of this one.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004340
Willy Tarreau763a95b2012-10-04 23:15:39 +02004341 See also: "option httpchk", "check-ssl"
4342
Willy Tarreaua453bdd2008-01-08 19:50:52 +01004343
Willy Tarreau9ea05a72009-06-14 12:07:01 +02004344option tcp-smart-accept
4345no option tcp-smart-accept
4346 Enable or disable the saving of one ACK packet during the accept sequence
4347 May be used in sections : defaults | frontend | listen | backend
4348 yes | yes | yes | no
4349 Arguments : none
4350
4351 When an HTTP connection request comes in, the system acknowledges it on
4352 behalf of HAProxy, then the client immediately sends its request, and the
4353 system acknowledges it too while it is notifying HAProxy about the new
4354 connection. HAProxy then reads the request and responds. This means that we
4355 have one TCP ACK sent by the system for nothing, because the request could
4356 very well be acknowledged by HAProxy when it sends its response.
4357
4358 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
4359 sending this useless ACK on platforms which support it (currently at least
4360 Linux). It must not cause any problem, because the system will send it anyway
4361 after 40 ms if the response takes more time than expected to come.
4362
4363 During complex network debugging sessions, it may be desirable to disable
4364 this optimization because delayed ACKs can make troubleshooting more complex
4365 when trying to identify where packets are delayed. It is then possible to
4366 fall back to normal behaviour by specifying "no option tcp-smart-accept".
4367
4368 It is also possible to force it for non-HTTP proxies by simply specifying
4369 "option tcp-smart-accept". For instance, it can make sense with some services
4370 such as SMTP where the server speaks first.
4371
4372 It is recommended to avoid forcing this option in a defaults section. In case
4373 of doubt, consider setting it back to automatic values by prepending the
4374 "default" keyword before it, or disabling it using the "no" keyword.
4375
Willy Tarreaud88edf22009-06-14 15:48:17 +02004376 See also : "option tcp-smart-connect"
4377
4378
4379option tcp-smart-connect
4380no option tcp-smart-connect
4381 Enable or disable the saving of one ACK packet during the connect sequence
4382 May be used in sections : defaults | frontend | listen | backend
4383 yes | no | yes | yes
4384 Arguments : none
4385
4386 On certain systems (at least Linux), HAProxy can ask the kernel not to
4387 immediately send an empty ACK upon a connection request, but to directly
4388 send the buffer request instead. This saves one packet on the network and
4389 thus boosts performance. It can also be useful for some servers, because they
4390 immediately get the request along with the incoming connection.
4391
4392 This feature is enabled when "option tcp-smart-connect" is set in a backend.
4393 It is not enabled by default because it makes network troubleshooting more
4394 complex.
4395
4396 It only makes sense to enable it with protocols where the client speaks first
4397 such as HTTP. In other situations, if there is no data to send in place of
4398 the ACK, a normal ACK is sent.
4399
4400 If this option has been enabled in a "defaults" section, it can be disabled
4401 in a specific instance by prepending the "no" keyword before it.
4402
4403 See also : "option tcp-smart-accept"
4404
Willy Tarreau9ea05a72009-06-14 12:07:01 +02004405
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004406option tcpka
4407 Enable or disable the sending of TCP keepalive packets on both sides
4408 May be used in sections : defaults | frontend | listen | backend
4409 yes | yes | yes | yes
4410 Arguments : none
4411
4412 When there is a firewall or any session-aware component between a client and
4413 a server, and when the protocol involves very long sessions with long idle
4414 periods (eg: remote desktops), there is a risk that one of the intermediate
4415 components decides to expire a session which has remained idle for too long.
4416
4417 Enabling socket-level TCP keep-alives makes the system regularly send packets
4418 to the other end of the connection, leaving it active. The delay between
4419 keep-alive probes is controlled by the system only and depends both on the
4420 operating system and its tuning parameters.
4421
4422 It is important to understand that keep-alive packets are neither emitted nor
4423 received at the application level. It is only the network stacks which sees
4424 them. For this reason, even if one side of the proxy already uses keep-alives
4425 to maintain its connection alive, those keep-alive packets will not be
4426 forwarded to the other side of the proxy.
4427
4428 Please note that this has nothing to do with HTTP keep-alive.
4429
4430 Using option "tcpka" enables the emission of TCP keep-alive probes on both
4431 the client and server sides of a connection. Note that this is meaningful
4432 only in "defaults" or "listen" sections. If this option is used in a
4433 frontend, only the client side will get keep-alives, and if this option is
4434 used in a backend, only the server side will get keep-alives. For this
4435 reason, it is strongly recommended to explicitly use "option clitcpka" and
4436 "option srvtcpka" when the configuration is split between frontends and
4437 backends.
4438
4439 See also : "option clitcpka", "option srvtcpka"
4440
Willy Tarreau844e3c52008-01-11 16:28:18 +01004441
4442option tcplog
4443 Enable advanced logging of TCP connections with session state and timers
4444 May be used in sections : defaults | frontend | listen | backend
4445 yes | yes | yes | yes
4446 Arguments : none
4447
4448 By default, the log output format is very poor, as it only contains the
4449 source and destination addresses, and the instance name. By specifying
4450 "option tcplog", each log line turns into a much richer format including, but
4451 not limited to, the connection timers, the session status, the connections
4452 numbers, the frontend, backend and server name, and of course the source
4453 address and ports. This option is useful for pure TCP proxies in order to
4454 find which of the client or server disconnects or times out. For normal HTTP
4455 proxies, it's better to use "option httplog" which is even more complete.
4456
4457 This option may be set either in the frontend or the backend.
4458
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004459 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004460
4461
Willy Tarreau844e3c52008-01-11 16:28:18 +01004462option transparent
4463no option transparent
4464 Enable client-side transparent proxying
4465 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01004466 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01004467 Arguments : none
4468
4469 This option was introduced in order to provide layer 7 persistence to layer 3
4470 load balancers. The idea is to use the OS's ability to redirect an incoming
4471 connection for a remote address to a local process (here HAProxy), and let
4472 this process know what address was initially requested. When this option is
4473 used, sessions without cookies will be forwarded to the original destination
4474 IP address of the incoming request (which should match that of another
4475 equipment), while requests with cookies will still be forwarded to the
4476 appropriate server.
4477
4478 Note that contrary to a common belief, this option does NOT make HAProxy
4479 present the client's IP to the server when establishing the connection.
4480
Willy Tarreaua1146052011-03-01 09:51:54 +01004481 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004482 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01004483
Willy Tarreaubf1f8162007-12-28 17:42:56 +01004484
Emeric Brun647caf12009-06-30 17:57:00 +02004485persist rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02004486persist rdp-cookie(<name>)
Emeric Brun647caf12009-06-30 17:57:00 +02004487 Enable RDP cookie-based persistence
4488 May be used in sections : defaults | frontend | listen | backend
4489 yes | no | yes | yes
4490 Arguments :
4491 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02004492 default cookie name "msts" will be used. There currently is no
4493 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02004494
4495 This statement enables persistence based on an RDP cookie. The RDP cookie
4496 contains all information required to find the server in the list of known
4497 servers. So when this option is set in the backend, the request is analysed
4498 and if an RDP cookie is found, it is decoded. If it matches a known server
4499 which is still UP (or if "option persist" is set), then the connection is
4500 forwarded to this server.
4501
4502 Note that this only makes sense in a TCP backend, but for this to work, the
4503 frontend must have waited long enough to ensure that an RDP cookie is present
4504 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004505 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02004506 a single "listen" section.
4507
Willy Tarreau61e28f22010-05-16 22:31:05 +02004508 Also, it is important to understand that the terminal server will emit this
4509 RDP cookie only if it is configured for "token redirection mode", which means
4510 that the "IP address redirection" option is disabled.
4511
Emeric Brun647caf12009-06-30 17:57:00 +02004512 Example :
4513 listen tse-farm
4514 bind :3389
4515 # wait up to 5s for an RDP cookie in the request
4516 tcp-request inspect-delay 5s
4517 tcp-request content accept if RDP_COOKIE
4518 # apply RDP cookie persistence
4519 persist rdp-cookie
4520 # if server is unknown, let's balance on the same cookie.
Cyril Bontédc4d9032012-04-08 21:57:39 +02004521 # alternatively, "balance leastconn" may be useful too.
Emeric Brun647caf12009-06-30 17:57:00 +02004522 balance rdp-cookie
4523 server srv1 1.1.1.1:3389
4524 server srv2 1.1.1.2:3389
4525
Simon Hormanab814e02011-06-24 14:50:20 +09004526 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
4527 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02004528
4529
Willy Tarreau3a7d2072009-03-05 23:48:25 +01004530rate-limit sessions <rate>
4531 Set a limit on the number of new sessions accepted per second on a frontend
4532 May be used in sections : defaults | frontend | listen | backend
4533 yes | yes | yes | no
4534 Arguments :
4535 <rate> The <rate> parameter is an integer designating the maximum number
4536 of new sessions per second to accept on the frontend.
4537
4538 When the frontend reaches the specified number of new sessions per second, it
4539 stops accepting new connections until the rate drops below the limit again.
4540 During this time, the pending sessions will be kept in the socket's backlog
4541 (in system buffers) and haproxy will not even be aware that sessions are
4542 pending. When applying very low limit on a highly loaded service, it may make
4543 sense to increase the socket's backlog using the "backlog" keyword.
4544
4545 This feature is particularly efficient at blocking connection-based attacks
4546 or service abuse on fragile servers. Since the session rate is measured every
4547 millisecond, it is extremely accurate. Also, the limit applies immediately,
4548 no delay is needed at all to detect the threshold.
4549
4550 Example : limit the connection rate on SMTP to 10 per second max
4551 listen smtp
4552 mode tcp
4553 bind :25
4554 rate-limit sessions 10
4555 server 127.0.0.1:1025
4556
Willy Tarreaua17c2d92011-07-25 08:16:20 +02004557 Note : when the maximum rate is reached, the frontend's status is not changed
4558 but its sockets appear as "WAITING" in the statistics if the
4559 "socket-stats" option is enabled.
Willy Tarreau3a7d2072009-03-05 23:48:25 +01004560
4561 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
4562
4563
Willy Tarreau2e1dca82012-09-12 08:43:15 +02004564redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
4565redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
4566redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004567 Return an HTTP redirection if/unless a condition is matched
4568 May be used in sections : defaults | frontend | listen | backend
4569 no | yes | yes | yes
4570
4571 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01004572 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004573
Willy Tarreau0140f252008-11-19 21:07:09 +01004574 Arguments :
Willy Tarreau2e1dca82012-09-12 08:43:15 +02004575 <loc> With "redirect location", the exact value in <loc> is placed into
4576 the HTTP "Location" header.
4577
4578 <pfx> With "redirect prefix", the "Location" header is built from the
4579 concatenation of <pfx> and the complete URI path, including the
4580 query string, unless the "drop-query" option is specified (see
4581 below). As a special case, if <pfx> equals exactly "/", then
4582 nothing is inserted before the original URI. It allows one to
4583 redirect to the same URL (for instance, to insert a cookie).
4584
4585 <sch> With "redirect scheme", then the "Location" header is built by
4586 concatenating <sch> with "://" then the first occurrence of the
4587 "Host" header, and then the URI path, including the query string
4588 unless the "drop-query" option is specified (see below). If no
4589 path is found or if the path is "*", then "/" is used instead. If
4590 no "Host" header is found, then an empty host component will be
4591 returned, which most recent browsers interprete as redirecting to
4592 the same host. This directive is mostly used to redirect HTTP to
4593 HTTPS.
Willy Tarreau0140f252008-11-19 21:07:09 +01004594
4595 <code> The code is optional. It indicates which type of HTTP redirection
Willy Tarreaub67fdc42013-03-29 19:28:11 +01004596 is desired. Only codes 301, 302, 303, 307 and 308 are supported,
4597 with 302 used by default if no code is specified. 301 means
4598 "Moved permanently", and a browser may cache the Location. 302
4599 means "Moved permanently" and means that the browser should not
4600 cache the redirection. 303 is equivalent to 302 except that the
4601 browser will fetch the location with a GET method. 307 is just
4602 like 302 but makes it clear that the same method must be reused.
4603 Likewise, 308 replaces 301 if the same method must be used.
Willy Tarreau0140f252008-11-19 21:07:09 +01004604
4605 <option> There are several options which can be specified to adjust the
4606 expected behaviour of a redirection :
4607
4608 - "drop-query"
4609 When this keyword is used in a prefix-based redirection, then the
4610 location will be set without any possible query-string, which is useful
4611 for directing users to a non-secure page for instance. It has no effect
4612 with a location-type redirect.
4613
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01004614 - "append-slash"
4615 This keyword may be used in conjunction with "drop-query" to redirect
4616 users who use a URL not ending with a '/' to the same one with the '/'.
4617 It can be useful to ensure that search engines will only see one URL.
4618 For this, a return code 301 is preferred.
4619
Willy Tarreau0140f252008-11-19 21:07:09 +01004620 - "set-cookie NAME[=value]"
4621 A "Set-Cookie" header will be added with NAME (and optionally "=value")
4622 to the response. This is sometimes used to indicate that a user has
4623 been seen, for instance to protect against some types of DoS. No other
4624 cookie option is added, so the cookie will be a session cookie. Note
4625 that for a browser, a sole cookie name without an equal sign is
4626 different from a cookie with an equal sign.
4627
4628 - "clear-cookie NAME[=]"
4629 A "Set-Cookie" header will be added with NAME (and optionally "="), but
4630 with the "Max-Age" attribute set to zero. This will tell the browser to
4631 delete this cookie. It is useful for instance on logout pages. It is
4632 important to note that clearing the cookie "NAME" will not remove a
4633 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
4634 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004635
4636 Example: move the login URL only to HTTPS.
4637 acl clear dst_port 80
4638 acl secure dst_port 8080
4639 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01004640 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01004641 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01004642 acl cookie_set hdr_sub(cookie) SEEN=1
4643
4644 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01004645 redirect prefix https://mysite.com if login_page !secure
4646 redirect prefix http://mysite.com drop-query if login_page !uid_given
4647 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01004648 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004649
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01004650 Example: send redirects for request for articles without a '/'.
4651 acl missing_slash path_reg ^/article/[^/]*$
4652 redirect code 301 prefix / drop-query append-slash if missing_slash
4653
Willy Tarreau2e1dca82012-09-12 08:43:15 +02004654 Example: redirect all HTTP traffic to HTTPS when SSL is handled by haproxy.
David BERARDe7153042012-11-03 00:11:31 +01004655 redirect scheme https if !{ ssl_fc }
Willy Tarreau2e1dca82012-09-12 08:43:15 +02004656
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004657 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02004658
4659
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004660redisp (deprecated)
4661redispatch (deprecated)
4662 Enable or disable session redistribution in case of connection failure
4663 May be used in sections: defaults | frontend | listen | backend
4664 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004665 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004666
4667 In HTTP mode, if a server designated by a cookie is down, clients may
4668 definitely stick to it because they cannot flush the cookie, so they will not
4669 be able to access the service anymore.
4670
4671 Specifying "redispatch" will allow the proxy to break their persistence and
4672 redistribute them to a working server.
4673
4674 It also allows to retry last connection to another server in case of multiple
4675 connection failures. Of course, it requires having "retries" set to a nonzero
4676 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01004677
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01004678 This form is deprecated, do not use it in any new configuration, use the new
4679 "option redispatch" instead.
4680
4681 See also : "option redispatch"
4682
Willy Tarreaueabeafa2008-01-16 16:17:06 +01004683
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004684reqadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01004685 Add a header at the end of the HTTP request
4686 May be used in sections : defaults | frontend | listen | backend
4687 no | yes | yes | yes
4688 Arguments :
4689 <string> is the complete line to be added. Any space or known delimiter
4690 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004691 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004692
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004693 <cond> is an optional matching condition built from ACLs. It makes it
4694 possible to ignore this rule when other conditions are not met.
4695
Willy Tarreau303c0352008-01-17 19:01:39 +01004696 A new line consisting in <string> followed by a line feed will be added after
4697 the last header of an HTTP request.
4698
4699 Header transformations only apply to traffic which passes through HAProxy,
4700 and not to traffic generated by HAProxy, such as health-checks or error
4701 responses.
4702
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01004703 Example : add "X-Proto: SSL" to requests coming via port 81
4704 acl is-ssl dst_port 81
4705 reqadd X-Proto:\ SSL if is-ssl
4706
4707 See also: "rspadd", section 6 about HTTP header manipulation, and section 7
4708 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004709
4710
Willy Tarreau5321c422010-01-28 20:35:13 +01004711reqallow <search> [{if | unless} <cond>]
4712reqiallow <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004713 Definitely allow an HTTP request if a line matches a regular expression
4714 May be used in sections : defaults | frontend | listen | backend
4715 no | yes | yes | yes
4716 Arguments :
4717 <search> is the regular expression applied to HTTP headers and to the
4718 request line. This is an extended regular expression. Parenthesis
4719 grouping is supported and no preliminary backslash is required.
4720 Any space or known delimiter must be escaped using a backslash
4721 ('\'). The pattern applies to a full line at a time. The
4722 "reqallow" keyword strictly matches case while "reqiallow"
4723 ignores case.
4724
Willy Tarreau5321c422010-01-28 20:35:13 +01004725 <cond> is an optional matching condition built from ACLs. It makes it
4726 possible to ignore this rule when other conditions are not met.
4727
Willy Tarreau303c0352008-01-17 19:01:39 +01004728 A request containing any line which matches extended regular expression
4729 <search> will mark the request as allowed, even if any later test would
4730 result in a deny. The test applies both to the request line and to request
4731 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01004732 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01004733
4734 It is easier, faster and more powerful to use ACLs to write access policies.
4735 Reqdeny, reqallow and reqpass should be avoided in new designs.
4736
4737 Example :
4738 # allow www.* but refuse *.local
4739 reqiallow ^Host:\ www\.
4740 reqideny ^Host:\ .*\.local
4741
Willy Tarreau5321c422010-01-28 20:35:13 +01004742 See also: "reqdeny", "block", section 6 about HTTP header manipulation, and
4743 section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004744
4745
Willy Tarreau5321c422010-01-28 20:35:13 +01004746reqdel <search> [{if | unless} <cond>]
4747reqidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004748 Delete all headers matching a regular expression in an HTTP request
4749 May be used in sections : defaults | frontend | listen | backend
4750 no | yes | yes | yes
4751 Arguments :
4752 <search> is the regular expression applied to HTTP headers and to the
4753 request line. This is an extended regular expression. Parenthesis
4754 grouping is supported and no preliminary backslash is required.
4755 Any space or known delimiter must be escaped using a backslash
4756 ('\'). The pattern applies to a full line at a time. The "reqdel"
4757 keyword strictly matches case while "reqidel" ignores case.
4758
Willy Tarreau5321c422010-01-28 20:35:13 +01004759 <cond> is an optional matching condition built from ACLs. It makes it
4760 possible to ignore this rule when other conditions are not met.
4761
Willy Tarreau303c0352008-01-17 19:01:39 +01004762 Any header line matching extended regular expression <search> in the request
4763 will be completely deleted. Most common use of this is to remove unwanted
4764 and/or dangerous headers or cookies from a request before passing it to the
4765 next servers.
4766
4767 Header transformations only apply to traffic which passes through HAProxy,
4768 and not to traffic generated by HAProxy, such as health-checks or error
4769 responses. Keep in mind that header names are not case-sensitive.
4770
4771 Example :
4772 # remove X-Forwarded-For header and SERVER cookie
4773 reqidel ^X-Forwarded-For:.*
4774 reqidel ^Cookie:.*SERVER=
4775
Willy Tarreau5321c422010-01-28 20:35:13 +01004776 See also: "reqadd", "reqrep", "rspdel", section 6 about HTTP header
4777 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004778
4779
Willy Tarreau5321c422010-01-28 20:35:13 +01004780reqdeny <search> [{if | unless} <cond>]
4781reqideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004782 Deny an HTTP request if a line matches a regular expression
4783 May be used in sections : defaults | frontend | listen | backend
4784 no | yes | yes | yes
4785 Arguments :
4786 <search> is the regular expression applied to HTTP headers and to the
4787 request line. This is an extended regular expression. Parenthesis
4788 grouping is supported and no preliminary backslash is required.
4789 Any space or known delimiter must be escaped using a backslash
4790 ('\'). The pattern applies to a full line at a time. The
4791 "reqdeny" keyword strictly matches case while "reqideny" ignores
4792 case.
4793
Willy Tarreau5321c422010-01-28 20:35:13 +01004794 <cond> is an optional matching condition built from ACLs. It makes it
4795 possible to ignore this rule when other conditions are not met.
4796
Willy Tarreau303c0352008-01-17 19:01:39 +01004797 A request containing any line which matches extended regular expression
4798 <search> will mark the request as denied, even if any later test would
4799 result in an allow. The test applies both to the request line and to request
4800 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01004801 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01004802
Willy Tarreauced27012008-01-17 20:35:34 +01004803 A denied request will generate an "HTTP 403 forbidden" response once the
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004804 complete request has been parsed. This is consistent with what is practiced
Willy Tarreaud72758d2010-01-12 10:42:19 +01004805 using ACLs.
Willy Tarreauced27012008-01-17 20:35:34 +01004806
Willy Tarreau303c0352008-01-17 19:01:39 +01004807 It is easier, faster and more powerful to use ACLs to write access policies.
4808 Reqdeny, reqallow and reqpass should be avoided in new designs.
4809
4810 Example :
4811 # refuse *.local, then allow www.*
4812 reqideny ^Host:\ .*\.local
4813 reqiallow ^Host:\ www\.
4814
Willy Tarreau5321c422010-01-28 20:35:13 +01004815 See also: "reqallow", "rspdeny", "block", section 6 about HTTP header
4816 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004817
4818
Willy Tarreau5321c422010-01-28 20:35:13 +01004819reqpass <search> [{if | unless} <cond>]
4820reqipass <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004821 Ignore any HTTP request line matching a regular expression in next rules
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 request line. This is an extended regular expression. Parenthesis
4827 grouping is supported and no preliminary backslash is required.
4828 Any space or known delimiter must be escaped using a backslash
4829 ('\'). The pattern applies to a full line at a time. The
4830 "reqpass" keyword strictly matches case while "reqipass" ignores
4831 case.
4832
Willy Tarreau5321c422010-01-28 20:35:13 +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 A request containing any line which matches extended regular expression
4837 <search> will skip next rules, without assigning any deny or allow verdict.
4838 The test applies both to the request line and to request headers. Keep in
4839 mind that URLs in request line are case-sensitive while header names are not.
4840
4841 It is easier, faster and more powerful to use ACLs to write access policies.
4842 Reqdeny, reqallow and reqpass should be avoided in new designs.
4843
4844 Example :
4845 # refuse *.local, then allow www.*, but ignore "www.private.local"
4846 reqipass ^Host:\ www.private\.local
4847 reqideny ^Host:\ .*\.local
4848 reqiallow ^Host:\ www\.
4849
Willy Tarreau5321c422010-01-28 20:35:13 +01004850 See also: "reqallow", "reqdeny", "block", section 6 about HTTP header
4851 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004852
4853
Willy Tarreau5321c422010-01-28 20:35:13 +01004854reqrep <search> <string> [{if | unless} <cond>]
4855reqirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004856 Replace a regular expression with a string in an HTTP request line
4857 May be used in sections : defaults | frontend | listen | backend
4858 no | yes | yes | yes
4859 Arguments :
4860 <search> is the regular expression applied to HTTP headers and to the
4861 request line. This is an extended regular expression. Parenthesis
4862 grouping is supported and no preliminary backslash is required.
4863 Any space or known delimiter must be escaped using a backslash
4864 ('\'). The pattern applies to a full line at a time. The "reqrep"
4865 keyword strictly matches case while "reqirep" ignores case.
4866
4867 <string> is the complete line to be added. Any space or known delimiter
4868 must be escaped using a backslash ('\'). References to matched
4869 pattern groups are possible using the common \N form, with N
4870 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004871 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004872
Willy Tarreau5321c422010-01-28 20:35:13 +01004873 <cond> is an optional matching condition built from ACLs. It makes it
4874 possible to ignore this rule when other conditions are not met.
4875
Willy Tarreau303c0352008-01-17 19:01:39 +01004876 Any line matching extended regular expression <search> in the request (both
4877 the request line and header lines) will be completely replaced with <string>.
4878 Most common use of this is to rewrite URLs or domain names in "Host" headers.
4879
4880 Header transformations only apply to traffic which passes through HAProxy,
4881 and not to traffic generated by HAProxy, such as health-checks or error
4882 responses. Note that for increased readability, it is suggested to add enough
4883 spaces between the request and the response. Keep in mind that URLs in
4884 request line are case-sensitive while header names are not.
4885
4886 Example :
4887 # replace "/static/" with "/" at the beginning of any request path.
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04004888 reqrep ^([^\ :]*)\ /static/(.*) \1\ /\2
Willy Tarreau303c0352008-01-17 19:01:39 +01004889 # replace "www.mydomain.com" with "www" in the host name.
4890 reqirep ^Host:\ www.mydomain.com Host:\ www
4891
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +04004892 See also: "reqadd", "reqdel", "rsprep", "tune.bufsize", section 6 about
4893 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004894
4895
Willy Tarreau5321c422010-01-28 20:35:13 +01004896reqtarpit <search> [{if | unless} <cond>]
4897reqitarpit <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004898 Tarpit an HTTP request containing a line matching a regular expression
4899 May be used in sections : defaults | frontend | listen | backend
4900 no | yes | yes | yes
4901 Arguments :
4902 <search> is the regular expression applied to HTTP headers and to the
4903 request line. This is an extended regular expression. Parenthesis
4904 grouping is supported and no preliminary backslash is required.
4905 Any space or known delimiter must be escaped using a backslash
4906 ('\'). The pattern applies to a full line at a time. The
4907 "reqtarpit" keyword strictly matches case while "reqitarpit"
4908 ignores case.
4909
Willy Tarreau5321c422010-01-28 20:35:13 +01004910 <cond> is an optional matching condition built from ACLs. It makes it
4911 possible to ignore this rule when other conditions are not met.
4912
Willy Tarreau303c0352008-01-17 19:01:39 +01004913 A request containing any line which matches extended regular expression
4914 <search> will be tarpitted, which means that it will connect to nowhere, will
Willy Tarreauced27012008-01-17 20:35:34 +01004915 be kept open for a pre-defined time, then will return an HTTP error 500 so
4916 that the attacker does not suspect it has been tarpitted. The status 500 will
4917 be reported in the logs, but the completion flags will indicate "PT". The
Willy Tarreau303c0352008-01-17 19:01:39 +01004918 delay is defined by "timeout tarpit", or "timeout connect" if the former is
4919 not set.
4920
4921 The goal of the tarpit is to slow down robots attacking servers with
4922 identifiable requests. Many robots limit their outgoing number of connections
4923 and stay connected waiting for a reply which can take several minutes to
4924 come. Depending on the environment and attack, it may be particularly
4925 efficient at reducing the load on the network and firewalls.
4926
Willy Tarreau5321c422010-01-28 20:35:13 +01004927 Examples :
Willy Tarreau303c0352008-01-17 19:01:39 +01004928 # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but
4929 # block all others.
4930 reqipass ^User-Agent:\.*(Mozilla|MSIE)
4931 reqitarpit ^User-Agent:
4932
Willy Tarreau5321c422010-01-28 20:35:13 +01004933 # block bad guys
4934 acl badguys src 10.1.0.3 172.16.13.20/28
4935 reqitarpit . if badguys
4936
4937 See also: "reqallow", "reqdeny", "reqpass", section 6 about HTTP header
4938 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004939
4940
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02004941retries <value>
4942 Set the number of retries to perform on a server after a connection failure
4943 May be used in sections: defaults | frontend | listen | backend
4944 yes | no | yes | yes
4945 Arguments :
4946 <value> is the number of times a connection attempt should be retried on
4947 a server when a connection either is refused or times out. The
4948 default value is 3.
4949
4950 It is important to understand that this value applies to the number of
4951 connection attempts, not full requests. When a connection has effectively
4952 been established to a server, there will be no more retry.
4953
4954 In order to avoid immediate reconnections to a server which is restarting,
4955 a turn-around timer of 1 second is applied before a retry occurs.
4956
4957 When "option redispatch" is set, the last retry may be performed on another
4958 server even if a cookie references a different server.
4959
4960 See also : "option redispatch"
4961
4962
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004963rspadd <string> [{if | unless} <cond>]
Willy Tarreau303c0352008-01-17 19:01:39 +01004964 Add a header at the end of the HTTP response
4965 May be used in sections : defaults | frontend | listen | backend
4966 no | yes | yes | yes
4967 Arguments :
4968 <string> is the complete line to be added. Any space or known delimiter
4969 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02004970 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01004971
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004972 <cond> is an optional matching condition built from ACLs. It makes it
4973 possible to ignore this rule when other conditions are not met.
4974
Willy Tarreau303c0352008-01-17 19:01:39 +01004975 A new line consisting in <string> followed by a line feed will be added after
4976 the last header of an HTTP response.
4977
4978 Header transformations only apply to traffic which passes through HAProxy,
4979 and not to traffic generated by HAProxy, such as health-checks or error
4980 responses.
4981
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004982 See also: "reqadd", section 6 about HTTP header manipulation, and section 7
4983 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01004984
4985
Willy Tarreaufdb563c2010-01-31 15:43:27 +01004986rspdel <search> [{if | unless} <cond>]
4987rspidel <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01004988 Delete all headers matching a regular expression in an HTTP response
4989 May be used in sections : defaults | frontend | listen | backend
4990 no | yes | yes | yes
4991 Arguments :
4992 <search> is the regular expression applied to HTTP headers and to the
4993 response line. This is an extended regular expression, so
4994 parenthesis grouping is supported and no preliminary backslash
4995 is required. Any space or known delimiter must be escaped using
4996 a backslash ('\'). The pattern applies to a full line at a time.
4997 The "rspdel" keyword strictly matches case while "rspidel"
4998 ignores case.
4999
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005000 <cond> is an optional matching condition built from ACLs. It makes it
5001 possible to ignore this rule when other conditions are not met.
5002
Willy Tarreau303c0352008-01-17 19:01:39 +01005003 Any header line matching extended regular expression <search> in the response
5004 will be completely deleted. Most common use of this is to remove unwanted
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02005005 and/or sensitive headers or cookies from a response before passing it to the
Willy Tarreau303c0352008-01-17 19:01:39 +01005006 client.
5007
5008 Header transformations only apply to traffic which passes through HAProxy,
5009 and not to traffic generated by HAProxy, such as health-checks or error
5010 responses. Keep in mind that header names are not case-sensitive.
5011
5012 Example :
5013 # remove the Server header from responses
5014 reqidel ^Server:.*
5015
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005016 See also: "rspadd", "rsprep", "reqdel", section 6 about HTTP header
5017 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005018
5019
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005020rspdeny <search> [{if | unless} <cond>]
5021rspideny <search> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01005022 Block an HTTP response if a line matches a regular expression
5023 May be used in sections : defaults | frontend | listen | backend
5024 no | yes | yes | yes
5025 Arguments :
5026 <search> is the regular expression applied to HTTP headers and to the
5027 response line. This is an extended regular expression, so
5028 parenthesis grouping is supported and no preliminary backslash
5029 is required. Any space or known delimiter must be escaped using
5030 a backslash ('\'). The pattern applies to a full line at a time.
5031 The "rspdeny" keyword strictly matches case while "rspideny"
5032 ignores case.
5033
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005034 <cond> is an optional matching condition built from ACLs. It makes it
5035 possible to ignore this rule when other conditions are not met.
5036
Willy Tarreau303c0352008-01-17 19:01:39 +01005037 A response containing any line which matches extended regular expression
5038 <search> will mark the request as denied. The test applies both to the
5039 response line and to response headers. Keep in mind that header names are not
5040 case-sensitive.
5041
5042 Main use of this keyword is to prevent sensitive information leak and to
Willy Tarreauced27012008-01-17 20:35:34 +01005043 block the response before it reaches the client. If a response is denied, it
5044 will be replaced with an HTTP 502 error so that the client never retrieves
5045 any sensitive data.
Willy Tarreau303c0352008-01-17 19:01:39 +01005046
5047 It is easier, faster and more powerful to use ACLs to write access policies.
5048 Rspdeny should be avoided in new designs.
5049
5050 Example :
5051 # Ensure that no content type matching ms-word will leak
5052 rspideny ^Content-type:\.*/ms-word
5053
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005054 See also: "reqdeny", "acl", "block", section 6 about HTTP header manipulation
5055 and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005056
5057
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005058rsprep <search> <string> [{if | unless} <cond>]
5059rspirep <search> <string> [{if | unless} <cond>] (ignore case)
Willy Tarreau303c0352008-01-17 19:01:39 +01005060 Replace a regular expression with a string in an HTTP response line
5061 May be used in sections : defaults | frontend | listen | backend
5062 no | yes | yes | yes
5063 Arguments :
5064 <search> is the regular expression applied to HTTP headers and to the
5065 response line. This is an extended regular expression, so
5066 parenthesis grouping is supported and no preliminary backslash
5067 is required. Any space or known delimiter must be escaped using
5068 a backslash ('\'). The pattern applies to a full line at a time.
5069 The "rsprep" keyword strictly matches case while "rspirep"
5070 ignores case.
5071
5072 <string> is the complete line to be added. Any space or known delimiter
5073 must be escaped using a backslash ('\'). References to matched
5074 pattern groups are possible using the common \N form, with N
5075 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005076 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01005077
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005078 <cond> is an optional matching condition built from ACLs. It makes it
5079 possible to ignore this rule when other conditions are not met.
5080
Willy Tarreau303c0352008-01-17 19:01:39 +01005081 Any line matching extended regular expression <search> in the response (both
5082 the response line and header lines) will be completely replaced with
5083 <string>. Most common use of this is to rewrite Location headers.
5084
5085 Header transformations only apply to traffic which passes through HAProxy,
5086 and not to traffic generated by HAProxy, such as health-checks or error
5087 responses. Note that for increased readability, it is suggested to add enough
5088 spaces between the request and the response. Keep in mind that header names
5089 are not case-sensitive.
5090
5091 Example :
5092 # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com"
5093 rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com
5094
Willy Tarreaufdb563c2010-01-31 15:43:27 +01005095 See also: "rspadd", "rspdel", "reqrep", section 6 about HTTP header
5096 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01005097
5098
David du Colombier486df472011-03-17 10:40:26 +01005099server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005100 Declare a server in a backend
5101 May be used in sections : defaults | frontend | listen | backend
5102 no | no | yes | yes
5103 Arguments :
5104 <name> is the internal name assigned to this server. This name will
Cyril Bonté941a0c62012-10-15 19:44:24 +02005105 appear in logs and alerts. If "http-send-name-header" is
Mark Lamourinec2247f02012-01-04 13:02:01 -05005106 set, it will be added to the request header sent to the server.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005107
David du Colombier486df472011-03-17 10:40:26 +01005108 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
5109 resolvable hostname is supported, but this name will be resolved
5110 during start-up. Address "0.0.0.0" or "*" has a special meaning.
5111 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +02005112 address as the one from the client connection. This is useful in
5113 transparent proxy architectures where the client's connection is
5114 intercepted and haproxy must forward to the original destination
5115 address. This is more or less what the "transparent" keyword does
5116 except that with a server it's possible to limit concurrency and
Willy Tarreau24709282013-03-10 21:32:12 +01005117 to report statistics. Optionally, an address family prefix may be
5118 used before the address to force the family regardless of the
5119 address format, which can be useful to specify a path to a unix
5120 socket with no slash ('/'). Currently supported prefixes are :
5121 - 'ipv4@' -> address is always IPv4
5122 - 'ipv6@' -> address is always IPv6
5123 - 'unix@' -> address is a path to a local unix socket
Willy Tarreaudad36a32013-03-11 01:20:04 +01005124 Any part of the address string may reference any number of
5125 environment variables by preceding their name with a dollar
5126 sign ('$') and optionally enclosing them with braces ('{}'),
5127 similarly to what is done in Bourne shell.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005128
Willy Tarreaub6205fd2012-09-24 12:27:33 +02005129 <port> is an optional port specification. If set, all connections will
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005130 be sent to this port. If unset, the same port the client
5131 connected to will be used. The port may also be prefixed by a "+"
5132 or a "-". In this case, the server's port will be determined by
5133 adding this value to the client's port.
5134
5135 <param*> is a list of parameters for this server. The "server" keywords
5136 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005137 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005138
5139 Examples :
5140 server first 10.1.1.1:1080 cookie first check inter 1000
5141 server second 10.1.1.2:1080 cookie second check inter 1000
Willy Tarreau24709282013-03-10 21:32:12 +01005142 server transp ipv4@
Willy Tarreaudad36a32013-03-11 01:20:04 +01005143 server backup ${SRV_BACKUP}:1080 backup
5144 server www1_dc1 ${LAN_DC1}.101:80
5145 server www1_dc2 ${LAN_DC2}.101:80
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005146
Mark Lamourinec2247f02012-01-04 13:02:01 -05005147 See also: "default-server", "http-send-name-header" and section 5 about
5148 server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005149
5150
5151source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02005152source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01005153source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005154 Set the source address for outgoing connections
5155 May be used in sections : defaults | frontend | listen | backend
5156 yes | no | yes | yes
5157 Arguments :
5158 <addr> is the IPv4 address HAProxy will bind to before connecting to a
5159 server. This address is also used as a source for health checks.
Willy Tarreau24709282013-03-10 21:32:12 +01005160
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005161 The default value of 0.0.0.0 means that the system will select
Willy Tarreau24709282013-03-10 21:32:12 +01005162 the most appropriate address to reach its destination. Optionally
5163 an address family prefix may be used before the address to force
5164 the family regardless of the address format, which can be useful
5165 to specify a path to a unix socket with no slash ('/'). Currently
5166 supported prefixes are :
5167 - 'ipv4@' -> address is always IPv4
5168 - 'ipv6@' -> address is always IPv6
5169 - 'unix@' -> address is a path to a local unix socket
Willy Tarreaudad36a32013-03-11 01:20:04 +01005170 Any part of the address string may reference any number of
5171 environment variables by preceding their name with a dollar
5172 sign ('$') and optionally enclosing them with braces ('{}'),
5173 similarly to what is done in Bourne shell.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005174
5175 <port> is an optional port. It is normally not needed but may be useful
5176 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02005177 the system will select a free port. Note that port ranges are not
5178 supported in the backend. If you want to force port ranges, you
5179 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005180
5181 <addr2> is the IP address to present to the server when connections are
5182 forwarded in full transparent proxy mode. This is currently only
5183 supported on some patched Linux kernels. When this address is
5184 specified, clients connecting to the server will be presented
5185 with this address, while health checks will still use the address
5186 <addr>.
5187
5188 <port2> is the optional port to present to the server when connections
5189 are forwarded in full transparent proxy mode (see <addr2> above).
5190 The default value of zero means the system will select a free
5191 port.
5192
Willy Tarreaubce70882009-09-07 11:51:47 +02005193 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
5194 This is the name of a comma-separated header list which can
5195 contain multiple IP addresses. By default, the last occurrence is
5196 used. This is designed to work with the X-Forwarded-For header
Baptiste Assmannea3e73b2013-02-02 23:47:49 +01005197 and to automatically bind to the client's IP address as seen
Willy Tarreaubce70882009-09-07 11:51:47 +02005198 by previous proxy, typically Stunnel. In order to use another
5199 occurrence from the last one, please see the <occ> parameter
5200 below. When the header (or occurrence) is not found, no binding
5201 is performed so that the proxy's default IP address is used. Also
5202 keep in mind that the header name is case insensitive, as for any
5203 HTTP header.
5204
5205 <occ> is the occurrence number of a value to be used in a multi-value
5206 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04005207 in order to specify which occurrence to use for the source IP
Willy Tarreaubce70882009-09-07 11:51:47 +02005208 address. Positive values indicate a position from the first
5209 occurrence, 1 being the first one. Negative values indicate
5210 positions relative to the last one, -1 being the last one. This
5211 is helpful for situations where an X-Forwarded-For header is set
5212 at the entry point of an infrastructure and must be used several
5213 proxy layers away. When this value is not specified, -1 is
5214 assumed. Passing a zero here disables the feature.
5215
Willy Tarreaud53f96b2009-02-04 18:46:54 +01005216 <name> is an optional interface name to which to bind to for outgoing
5217 traffic. On systems supporting this features (currently, only
5218 Linux), this allows one to bind all traffic to the server to
5219 this interface even if it is not the one the system would select
5220 based on routing tables. This should be used with extreme care.
5221 Note that using this option requires root privileges.
5222
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005223 The "source" keyword is useful in complex environments where a specific
5224 address only is allowed to connect to the servers. It may be needed when a
5225 private address must be used through a public gateway for instance, and it is
5226 known that the system cannot determine the adequate source address by itself.
5227
5228 An extension which is available on certain patched Linux kernels may be used
5229 through the "usesrc" optional keyword. It makes it possible to connect to the
5230 servers with an IP address which does not belong to the system itself. This
5231 is called "full transparent proxy mode". For this to work, the destination
5232 servers have to route their traffic back to this address through the machine
5233 running HAProxy, and IP forwarding must generally be enabled on this machine.
5234
5235 In this "full transparent proxy" mode, it is possible to force a specific IP
5236 address to be presented to the servers. This is not much used in fact. A more
5237 common use is to tell HAProxy to present the client's IP address. For this,
5238 there are two methods :
5239
5240 - present the client's IP and port addresses. This is the most transparent
5241 mode, but it can cause problems when IP connection tracking is enabled on
5242 the machine, because a same connection may be seen twice with different
5243 states. However, this solution presents the huge advantage of not
5244 limiting the system to the 64k outgoing address+port couples, because all
5245 of the client ranges may be used.
5246
5247 - present only the client's IP address and select a spare port. This
5248 solution is still quite elegant but slightly less transparent (downstream
5249 firewalls logs will not match upstream's). It also presents the downside
5250 of limiting the number of concurrent connections to the usual 64k ports.
5251 However, since the upstream and downstream ports are different, local IP
5252 connection tracking on the machine will not be upset by the reuse of the
5253 same session.
5254
5255 Note that depending on the transparent proxy technology used, it may be
5256 required to force the source address. In fact, cttproxy version 2 requires an
5257 IP address in <addr> above, and does not support setting of "0.0.0.0" as the
5258 IP address because it creates NAT entries which much match the exact outgoing
5259 address. Tproxy version 4 and some other kernel patches which work in pure
5260 forwarding mode generally will not have this limitation.
5261
5262 This option sets the default source for all servers in the backend. It may
5263 also be specified in a "defaults" section. Finer source address specification
5264 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005265 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005266
5267 Examples :
5268 backend private
5269 # Connect to the servers using our 192.168.1.200 source address
5270 source 192.168.1.200
5271
5272 backend transparent_ssl1
5273 # Connect to the SSL farm from the client's source address
5274 source 192.168.1.200 usesrc clientip
5275
5276 backend transparent_ssl2
5277 # Connect to the SSL farm from the client's source address and port
5278 # not recommended if IP conntrack is present on the local machine.
5279 source 192.168.1.200 usesrc client
5280
5281 backend transparent_ssl3
5282 # Connect to the SSL farm from the client's source address. It
5283 # is more conntrack-friendly.
5284 source 192.168.1.200 usesrc clientip
5285
5286 backend transparent_smtp
5287 # Connect to the SMTP farm from the client's source address/port
5288 # with Tproxy version 4.
5289 source 0.0.0.0 usesrc clientip
5290
Willy Tarreaubce70882009-09-07 11:51:47 +02005291 backend transparent_http
5292 # Connect to the servers using the client's IP as seen by previous
5293 # proxy.
5294 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
5295
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005296 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005297 the Linux kernel on www.balabit.com, the "bind" keyword.
5298
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01005299
Willy Tarreau844e3c52008-01-11 16:28:18 +01005300srvtimeout <timeout> (deprecated)
5301 Set the maximum inactivity time on the server side.
5302 May be used in sections : defaults | frontend | listen | backend
5303 yes | no | yes | yes
5304 Arguments :
5305 <timeout> is the timeout value specified in milliseconds by default, but
5306 can be in any other unit if the number is suffixed by the unit,
5307 as explained at the top of this document.
5308
5309 The inactivity timeout applies when the server is expected to acknowledge or
5310 send data. In HTTP mode, this timeout is particularly important to consider
5311 during the first phase of the server's response, when it has to send the
5312 headers, as it directly represents the server's processing time for the
5313 request. To find out what value to put there, it's often good to start with
5314 what would be considered as unacceptable response times, then check the logs
5315 to observe the response time distribution, and adjust the value accordingly.
5316
5317 The value is specified in milliseconds by default, but can be in any other
5318 unit if the number is suffixed by the unit, as specified at the top of this
5319 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
5320 recommended that the client timeout remains equal to the server timeout in
5321 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01005322 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01005323 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreaud72758d2010-01-12 10:42:19 +01005324 seconds (eg: 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01005325
5326 This parameter is specific to backends, but can be specified once for all in
5327 "defaults" sections. This is in fact one of the easiest solutions not to
5328 forget about it. An unspecified timeout results in an infinite timeout, which
5329 is not recommended. Such a usage is accepted and works but reports a warning
5330 during startup because it may results in accumulation of expired sessions in
5331 the system if the system's timeouts are not configured either.
5332
5333 This parameter is provided for compatibility but is currently deprecated.
5334 Please use "timeout server" instead.
5335
Willy Tarreauce887fd2012-05-12 12:50:00 +02005336 See also : "timeout server", "timeout tunnel", "timeout client" and
5337 "clitimeout".
Willy Tarreau844e3c52008-01-11 16:28:18 +01005338
5339
Cyril Bonté66c327d2010-10-12 00:14:37 +02005340stats admin { if | unless } <cond>
5341 Enable statistics admin level if/unless a condition is matched
5342 May be used in sections : defaults | frontend | listen | backend
5343 no | no | yes | yes
5344
5345 This statement enables the statistics admin level if/unless a condition is
5346 matched.
5347
5348 The admin level allows to enable/disable servers from the web interface. By
5349 default, statistics page is read-only for security reasons.
5350
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005351 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5352 unless you know what you do : memory is not shared between the
5353 processes, which can result in random behaviours.
5354
Cyril Bonté23b39d92011-02-10 22:54:44 +01005355 Currently, the POST request is limited to the buffer size minus the reserved
5356 buffer space, which means that if the list of servers is too long, the
5357 request won't be processed. It is recommended to alter few servers at a
5358 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02005359
5360 Example :
5361 # statistics admin level only for localhost
5362 backend stats_localhost
5363 stats enable
5364 stats admin if LOCALHOST
5365
5366 Example :
5367 # statistics admin level always enabled because of the authentication
5368 backend stats_auth
5369 stats enable
5370 stats auth admin:AdMiN123
5371 stats admin if TRUE
5372
5373 Example :
5374 # statistics admin level depends on the authenticated user
5375 userlist stats-auth
5376 group admin users admin
5377 user admin insecure-password AdMiN123
5378 group readonly users haproxy
5379 user haproxy insecure-password haproxy
5380
5381 backend stats_auth
5382 stats enable
5383 acl AUTH http_auth(stats-auth)
5384 acl AUTH_ADMIN http_auth_group(stats-auth) admin
5385 stats http-request auth unless AUTH
5386 stats admin if AUTH_ADMIN
5387
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005388 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
5389 "bind-process", section 3.4 about userlists and section 7 about
5390 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02005391
5392
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005393stats auth <user>:<passwd>
5394 Enable statistics with authentication and grant access to an account
5395 May be used in sections : defaults | frontend | listen | backend
5396 yes | no | yes | yes
5397 Arguments :
5398 <user> is a user name to grant access to
5399
5400 <passwd> is the cleartext password associated to this user
5401
5402 This statement enables statistics with default settings, and restricts access
5403 to declared users only. It may be repeated as many times as necessary to
5404 allow as many users as desired. When a user tries to access the statistics
5405 without a valid account, a "401 Forbidden" response will be returned so that
5406 the browser asks the user to provide a valid user and password. The real
5407 which will be returned to the browser is configurable using "stats realm".
5408
5409 Since the authentication method is HTTP Basic Authentication, the passwords
5410 circulate in cleartext on the network. Thus, it was decided that the
5411 configuration file would also use cleartext passwords to remind the users
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02005412 that those ones should not be sensitive and not shared with any other account.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005413
5414 It is also possible to reduce the scope of the proxies which appear in the
5415 report using "stats scope".
5416
5417 Though this statement alone is enough to enable statistics reporting, it is
5418 recommended to set all other settings in order to avoid relying on default
5419 unobvious parameters.
5420
5421 Example :
5422 # public access (limited to this backend only)
5423 backend public_www
5424 server srv1 192.168.0.1:80
5425 stats enable
5426 stats hide-version
5427 stats scope .
5428 stats uri /admin?stats
5429 stats realm Haproxy\ Statistics
5430 stats auth admin1:AdMiN123
5431 stats auth admin2:AdMiN321
5432
5433 # internal monitoring access (unlimited)
5434 backend private_monitoring
5435 stats enable
5436 stats uri /admin?stats
5437 stats refresh 5s
5438
5439 See also : "stats enable", "stats realm", "stats scope", "stats uri"
5440
5441
5442stats enable
5443 Enable statistics reporting with default settings
5444 May be used in sections : defaults | frontend | listen | backend
5445 yes | no | yes | yes
5446 Arguments : none
5447
5448 This statement enables statistics reporting with default settings defined
5449 at build time. Unless stated otherwise, these settings are used :
5450 - stats uri : /haproxy?stats
5451 - stats realm : "HAProxy Statistics"
5452 - stats auth : no authentication
5453 - stats scope : no restriction
5454
5455 Though this statement alone is enough to enable statistics reporting, it is
5456 recommended to set all other settings in order to avoid relying on default
5457 unobvious parameters.
5458
5459 Example :
5460 # public access (limited to this backend only)
5461 backend public_www
5462 server srv1 192.168.0.1:80
5463 stats enable
5464 stats hide-version
5465 stats scope .
5466 stats uri /admin?stats
5467 stats realm Haproxy\ Statistics
5468 stats auth admin1:AdMiN123
5469 stats auth admin2:AdMiN321
5470
5471 # internal monitoring access (unlimited)
5472 backend private_monitoring
5473 stats enable
5474 stats uri /admin?stats
5475 stats refresh 5s
5476
5477 See also : "stats auth", "stats realm", "stats uri"
5478
5479
Willy Tarreaud63335a2010-02-26 12:56:52 +01005480stats hide-version
5481 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005482 May be used in sections : defaults | frontend | listen | backend
5483 yes | no | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01005484 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005485
Willy Tarreaud63335a2010-02-26 12:56:52 +01005486 By default, the stats page reports some useful status information along with
5487 the statistics. Among them is HAProxy's version. However, it is generally
5488 considered dangerous to report precise version to anyone, as it can help them
5489 target known weaknesses with specific attacks. The "stats hide-version"
5490 statement removes the version from the statistics report. This is recommended
5491 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005492
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02005493 Though this statement alone is enough to enable statistics reporting, it is
5494 recommended to set all other settings in order to avoid relying on default
5495 unobvious parameters.
5496
Willy Tarreaud63335a2010-02-26 12:56:52 +01005497 Example :
5498 # public access (limited to this backend only)
5499 backend public_www
5500 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02005501 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01005502 stats hide-version
5503 stats scope .
5504 stats uri /admin?stats
5505 stats realm Haproxy\ Statistics
5506 stats auth admin1:AdMiN123
5507 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005508
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005509 # internal monitoring access (unlimited)
5510 backend private_monitoring
5511 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01005512 stats uri /admin?stats
5513 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01005514
Willy Tarreaud63335a2010-02-26 12:56:52 +01005515 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02005516
Willy Tarreau983e01e2010-01-11 18:42:06 +01005517
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02005518stats http-request { allow | deny | auth [realm <realm>] }
5519 [ { if | unless } <condition> ]
5520 Access control for statistics
5521
5522 May be used in sections: defaults | frontend | listen | backend
5523 no | no | yes | yes
5524
5525 As "http-request", these set of options allow to fine control access to
5526 statistics. Each option may be followed by if/unless and acl.
5527 First option with matched condition (or option without condition) is final.
5528 For "deny" a 403 error will be returned, for "allow" normal processing is
5529 performed, for "auth" a 401/407 error code is returned so the client
5530 should be asked to enter a username and password.
5531
5532 There is no fixed limit to the number of http-request statements per
5533 instance.
5534
5535 See also : "http-request", section 3.4 about userlists and section 7
5536 about ACL usage.
5537
5538
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005539stats realm <realm>
5540 Enable statistics and set authentication realm
5541 May be used in sections : defaults | frontend | listen | backend
5542 yes | no | yes | yes
5543 Arguments :
5544 <realm> is the name of the HTTP Basic Authentication realm reported to
5545 the browser. The browser uses it to display it in the pop-up
5546 inviting the user to enter a valid username and password.
5547
5548 The realm is read as a single word, so any spaces in it should be escaped
5549 using a backslash ('\').
5550
5551 This statement is useful only in conjunction with "stats auth" since it is
5552 only related to authentication.
5553
5554 Though this statement alone is enough to enable statistics reporting, it is
5555 recommended to set all other settings in order to avoid relying on default
5556 unobvious parameters.
5557
5558 Example :
5559 # public access (limited to this backend only)
5560 backend public_www
5561 server srv1 192.168.0.1:80
5562 stats enable
5563 stats hide-version
5564 stats scope .
5565 stats uri /admin?stats
5566 stats realm Haproxy\ Statistics
5567 stats auth admin1:AdMiN123
5568 stats auth admin2:AdMiN321
5569
5570 # internal monitoring access (unlimited)
5571 backend private_monitoring
5572 stats enable
5573 stats uri /admin?stats
5574 stats refresh 5s
5575
5576 See also : "stats auth", "stats enable", "stats uri"
5577
5578
5579stats refresh <delay>
5580 Enable statistics with automatic refresh
5581 May be used in sections : defaults | frontend | listen | backend
5582 yes | no | yes | yes
5583 Arguments :
5584 <delay> is the suggested refresh delay, specified in seconds, which will
5585 be returned to the browser consulting the report page. While the
5586 browser is free to apply any delay, it will generally respect it
5587 and refresh the page this every seconds. The refresh interval may
5588 be specified in any other non-default time unit, by suffixing the
5589 unit after the value, as explained at the top of this document.
5590
5591 This statement is useful on monitoring displays with a permanent page
5592 reporting the load balancer's activity. When set, the HTML report page will
5593 include a link "refresh"/"stop refresh" so that the user can select whether
5594 he wants automatic refresh of the page or not.
5595
5596 Though this statement alone is enough to enable statistics reporting, it is
5597 recommended to set all other settings in order to avoid relying on default
5598 unobvious parameters.
5599
5600 Example :
5601 # public access (limited to this backend only)
5602 backend public_www
5603 server srv1 192.168.0.1:80
5604 stats enable
5605 stats hide-version
5606 stats scope .
5607 stats uri /admin?stats
5608 stats realm Haproxy\ Statistics
5609 stats auth admin1:AdMiN123
5610 stats auth admin2:AdMiN321
5611
5612 # internal monitoring access (unlimited)
5613 backend private_monitoring
5614 stats enable
5615 stats uri /admin?stats
5616 stats refresh 5s
5617
5618 See also : "stats auth", "stats enable", "stats realm", "stats uri"
5619
5620
5621stats scope { <name> | "." }
5622 Enable statistics and limit access scope
5623 May be used in sections : defaults | frontend | listen | backend
5624 yes | no | yes | yes
5625 Arguments :
5626 <name> is the name of a listen, frontend or backend section to be
5627 reported. The special name "." (a single dot) designates the
5628 section in which the statement appears.
5629
5630 When this statement is specified, only the sections enumerated with this
5631 statement will appear in the report. All other ones will be hidden. This
5632 statement may appear as many times as needed if multiple sections need to be
5633 reported. Please note that the name checking is performed as simple string
5634 comparisons, and that it is never checked that a give section name really
5635 exists.
5636
5637 Though this statement alone is enough to enable statistics reporting, it is
5638 recommended to set all other settings in order to avoid relying on default
5639 unobvious parameters.
5640
5641 Example :
5642 # public access (limited to this backend only)
5643 backend public_www
5644 server srv1 192.168.0.1:80
5645 stats enable
5646 stats hide-version
5647 stats scope .
5648 stats uri /admin?stats
5649 stats realm Haproxy\ Statistics
5650 stats auth admin1:AdMiN123
5651 stats auth admin2:AdMiN321
5652
5653 # internal monitoring access (unlimited)
5654 backend private_monitoring
5655 stats enable
5656 stats uri /admin?stats
5657 stats refresh 5s
5658
5659 See also : "stats auth", "stats enable", "stats realm", "stats uri"
5660
Willy Tarreaud63335a2010-02-26 12:56:52 +01005661
Willy Tarreauc9705a12010-07-27 20:05:50 +02005662stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01005663 Enable reporting of a description on the statistics page.
5664 May be used in sections : defaults | frontend | listen | backend
5665 yes | no | yes | yes
5666
Willy Tarreauc9705a12010-07-27 20:05:50 +02005667 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01005668 description from global section is automatically used instead.
5669
5670 This statement is useful for users that offer shared services to their
5671 customers, where node or description should be different for each customer.
5672
5673 Though this statement alone is enough to enable statistics reporting, it is
5674 recommended to set all other settings in order to avoid relying on default
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04005675 unobvious parameters. By default description is not shown.
Willy Tarreaud63335a2010-02-26 12:56:52 +01005676
5677 Example :
5678 # internal monitoring access (unlimited)
5679 backend private_monitoring
5680 stats enable
5681 stats show-desc Master node for Europe, Asia, Africa
5682 stats uri /admin?stats
5683 stats refresh 5s
5684
5685 See also: "show-node", "stats enable", "stats uri" and "description" in
5686 global section.
5687
5688
5689stats show-legends
5690 Enable reporting additional informations on the statistics page :
5691 - cap: capabilities (proxy)
5692 - mode: one of tcp, http or health (proxy)
5693 - id: SNMP ID (proxy, socket, server)
5694 - IP (socket, server)
5695 - cookie (backend, server)
5696
5697 Though this statement alone is enough to enable statistics reporting, it is
5698 recommended to set all other settings in order to avoid relying on default
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04005699 unobvious parameters. Default behaviour is not to show this information.
Willy Tarreaud63335a2010-02-26 12:56:52 +01005700
5701 See also: "stats enable", "stats uri".
5702
5703
5704stats show-node [ <name> ]
5705 Enable reporting of a host name on the statistics page.
5706 May be used in sections : defaults | frontend | listen | backend
5707 yes | no | yes | yes
5708 Arguments:
5709 <name> is an optional name to be reported. If unspecified, the
5710 node name from global section is automatically used instead.
5711
5712 This statement is useful for users that offer shared services to their
5713 customers, where node or description might be different on a stats page
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04005714 provided for each customer. Default behaviour is not to show host name.
Willy Tarreaud63335a2010-02-26 12:56:52 +01005715
5716 Though this statement alone is enough to enable statistics reporting, it is
5717 recommended to set all other settings in order to avoid relying on default
5718 unobvious parameters.
5719
5720 Example:
5721 # internal monitoring access (unlimited)
5722 backend private_monitoring
5723 stats enable
5724 stats show-node Europe-1
5725 stats uri /admin?stats
5726 stats refresh 5s
5727
5728 See also: "show-desc", "stats enable", "stats uri", and "node" in global
5729 section.
5730
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005731
5732stats uri <prefix>
5733 Enable statistics and define the URI prefix to access them
5734 May be used in sections : defaults | frontend | listen | backend
5735 yes | no | yes | yes
5736 Arguments :
5737 <prefix> is the prefix of any URI which will be redirected to stats. This
5738 prefix may contain a question mark ('?') to indicate part of a
5739 query string.
5740
5741 The statistics URI is intercepted on the relayed traffic, so it appears as a
5742 page within the normal application. It is strongly advised to ensure that the
5743 selected URI will never appear in the application, otherwise it will never be
5744 possible to reach it in the application.
5745
5746 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005747 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005748 It is generally a good idea to include a question mark in the URI so that
5749 intermediate proxies refrain from caching the results. Also, since any string
5750 beginning with the prefix will be accepted as a stats request, the question
5751 mark helps ensuring that no valid URI will begin with the same words.
5752
5753 It is sometimes very convenient to use "/" as the URI prefix, and put that
5754 statement in a "listen" instance of its own. That makes it easy to dedicate
5755 an address or a port to statistics only.
5756
5757 Though this statement alone is enough to enable statistics reporting, it is
5758 recommended to set all other settings in order to avoid relying on default
5759 unobvious parameters.
5760
5761 Example :
5762 # public access (limited to this backend only)
5763 backend public_www
5764 server srv1 192.168.0.1:80
5765 stats enable
5766 stats hide-version
5767 stats scope .
5768 stats uri /admin?stats
5769 stats realm Haproxy\ Statistics
5770 stats auth admin1:AdMiN123
5771 stats auth admin2:AdMiN321
5772
5773 # internal monitoring access (unlimited)
5774 backend private_monitoring
5775 stats enable
5776 stats uri /admin?stats
5777 stats refresh 5s
5778
5779 See also : "stats auth", "stats enable", "stats realm"
5780
5781
Willy Tarreaud63335a2010-02-26 12:56:52 +01005782stick match <pattern> [table <table>] [{if | unless} <cond>]
5783 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +01005784 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +01005785 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005786
5787 Arguments :
5788 <pattern> is a pattern extraction rule as described in section 7.8. It
5789 describes what elements of the incoming request or connection
5790 will be analysed in the hope to find a matching entry in a
5791 stickiness table. This rule is mandatory.
5792
5793 <table> is an optional stickiness table name. If unspecified, the same
5794 backend's table is used. A stickiness table is declared using
5795 the "stick-table" statement.
5796
5797 <cond> is an optional matching condition. It makes it possible to match
5798 on a certain criterion only when other conditions are met (or
5799 not met). For instance, it could be used to match on a source IP
5800 address except when a request passes through a known proxy, in
5801 which case we'd match on a header containing that IP address.
5802
5803 Some protocols or applications require complex stickiness rules and cannot
5804 always simply rely on cookies nor hashing. The "stick match" statement
5805 describes a rule to extract the stickiness criterion from an incoming request
5806 or connection. See section 7 for a complete list of possible patterns and
5807 transformation rules.
5808
5809 The table has to be declared using the "stick-table" statement. It must be of
5810 a type compatible with the pattern. By default it is the one which is present
5811 in the same backend. It is possible to share a table with other backends by
5812 referencing it using the "table" keyword. If another table is referenced,
5813 the server's ID inside the backends are used. By default, all server IDs
5814 start at 1 in each backend, so the server ordering is enough. But in case of
5815 doubt, it is highly recommended to force server IDs using their "id" setting.
5816
5817 It is possible to restrict the conditions where a "stick match" statement
5818 will apply, using "if" or "unless" followed by a condition. See section 7 for
5819 ACL based conditions.
5820
5821 There is no limit on the number of "stick match" statements. The first that
5822 applies and matches will cause the request to be directed to the same server
5823 as was used for the request which created the entry. That way, multiple
5824 matches can be used as fallbacks.
5825
5826 The stick rules are checked after the persistence cookies, so they will not
5827 affect stickiness if a cookie has already been used to select a server. That
5828 way, it becomes very easy to insert cookies and match on IP addresses in
5829 order to maintain stickiness between HTTP and HTTPS.
5830
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005831 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5832 unless you know what you do : memory is not shared between the
5833 processes, which can result in random behaviours.
5834
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005835 Example :
5836 # forward SMTP users to the same server they just used for POP in the
5837 # last 30 minutes
5838 backend pop
5839 mode tcp
5840 balance roundrobin
5841 stick store-request src
5842 stick-table type ip size 200k expire 30m
5843 server s1 192.168.1.1:110
5844 server s2 192.168.1.1:110
5845
5846 backend smtp
5847 mode tcp
5848 balance roundrobin
5849 stick match src table pop
5850 server s1 192.168.1.1:25
5851 server s2 192.168.1.1:25
5852
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005853 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
5854 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005855
5856
5857stick on <pattern> [table <table>] [{if | unless} <condition>]
5858 Define a request pattern to associate a user to a server
5859 May be used in sections : defaults | frontend | listen | backend
5860 no | no | yes | yes
5861
5862 Note : This form is exactly equivalent to "stick match" followed by
5863 "stick store-request", all with the same arguments. Please refer
5864 to both keywords for details. It is only provided as a convenience
5865 for writing more maintainable configurations.
5866
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005867 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5868 unless you know what you do : memory is not shared between the
5869 processes, which can result in random behaviours.
5870
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005871 Examples :
5872 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +01005873 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005874
5875 # ...is strictly equivalent to this one :
5876 stick match src table pop if !localhost
5877 stick store-request src table pop if !localhost
5878
5879
5880 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
5881 # well as HTTP without cookie. Share the same table between both accesses.
5882 backend http
5883 mode http
5884 balance roundrobin
5885 stick on src table https
5886 cookie SRV insert indirect nocache
5887 server s1 192.168.1.1:80 cookie s1
5888 server s2 192.168.1.1:80 cookie s2
5889
5890 backend https
5891 mode tcp
5892 balance roundrobin
5893 stick-table type ip size 200k expire 30m
5894 stick on src
5895 server s1 192.168.1.1:443
5896 server s2 192.168.1.1:443
5897
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005898 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005899
5900
5901stick store-request <pattern> [table <table>] [{if | unless} <condition>]
5902 Define a request pattern used to create an entry in a stickiness table
5903 May be used in sections : defaults | frontend | listen | backend
5904 no | no | yes | yes
5905
5906 Arguments :
5907 <pattern> is a pattern extraction rule as described in section 7.8. It
5908 describes what elements of the incoming request or connection
5909 will be analysed, extracted and stored in the table once a
5910 server is selected.
5911
5912 <table> is an optional stickiness table name. If unspecified, the same
5913 backend's table is used. A stickiness table is declared using
5914 the "stick-table" statement.
5915
5916 <cond> is an optional storage condition. It makes it possible to store
5917 certain criteria only when some conditions are met (or not met).
5918 For instance, it could be used to store the source IP address
5919 except when the request passes through a known proxy, in which
5920 case we'd store a converted form of a header containing that IP
5921 address.
5922
5923 Some protocols or applications require complex stickiness rules and cannot
5924 always simply rely on cookies nor hashing. The "stick store-request" statement
5925 describes a rule to decide what to extract from the request and when to do
5926 it, in order to store it into a stickiness table for further requests to
5927 match it using the "stick match" statement. Obviously the extracted part must
5928 make sense and have a chance to be matched in a further request. Storing a
5929 client's IP address for instance often makes sense. Storing an ID found in a
5930 URL parameter also makes sense. Storing a source port will almost never make
5931 any sense because it will be randomly matched. See section 7 for a complete
5932 list of possible patterns and transformation rules.
5933
5934 The table has to be declared using the "stick-table" statement. It must be of
5935 a type compatible with the pattern. By default it is the one which is present
5936 in the same backend. It is possible to share a table with other backends by
5937 referencing it using the "table" keyword. If another table is referenced,
5938 the server's ID inside the backends are used. By default, all server IDs
5939 start at 1 in each backend, so the server ordering is enough. But in case of
5940 doubt, it is highly recommended to force server IDs using their "id" setting.
5941
5942 It is possible to restrict the conditions where a "stick store-request"
5943 statement will apply, using "if" or "unless" followed by a condition. This
5944 condition will be evaluated while parsing the request, so any criteria can be
5945 used. See section 7 for ACL based conditions.
5946
5947 There is no limit on the number of "stick store-request" statements, but
5948 there is a limit of 8 simultaneous stores per request or response. This
5949 makes it possible to store up to 8 criteria, all extracted from either the
5950 request or the response, regardless of the number of rules. Only the 8 first
5951 ones which match will be kept. Using this, it is possible to feed multiple
5952 tables at once in the hope to increase the chance to recognize a user on
5953 another protocol or access method.
5954
5955 The "store-request" rules are evaluated once the server connection has been
5956 established, so that the table will contain the real server that processed
5957 the request.
5958
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005959 Note : Consider not using this feature in multi-process mode (nbproc > 1)
5960 unless you know what you do : memory is not shared between the
5961 processes, which can result in random behaviours.
5962
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005963 Example :
5964 # forward SMTP users to the same server they just used for POP in the
5965 # last 30 minutes
5966 backend pop
5967 mode tcp
5968 balance roundrobin
5969 stick store-request src
5970 stick-table type ip size 200k expire 30m
5971 server s1 192.168.1.1:110
5972 server s2 192.168.1.1:110
5973
5974 backend smtp
5975 mode tcp
5976 balance roundrobin
5977 stick match src table pop
5978 server s1 192.168.1.1:25
5979 server s2 192.168.1.1:25
5980
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01005981 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
5982 about ACLs and pattern extraction.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005983
5984
Emeric Brun7c6b82e2010-09-24 16:34:28 +02005985stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +02005986 size <size> [expire <expire>] [nopurge] [peers <peersect>]
5987 [store <data_type>]*
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005988 Configure the stickiness table for the current backend
5989 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +02005990 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01005991
5992 Arguments :
5993 ip a table declared with "type ip" will only store IPv4 addresses.
5994 This form is very compact (about 50 bytes per entry) and allows
5995 very fast entry lookup and stores with almost no overhead. This
5996 is mainly used to store client source IP addresses.
5997
David du Colombier9a6d3c92011-03-17 10:40:24 +01005998 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
5999 This form is very compact (about 60 bytes per entry) and allows
6000 very fast entry lookup and stores with almost no overhead. This
6001 is mainly used to store client source IP addresses.
6002
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006003 integer a table declared with "type integer" will store 32bit integers
6004 which can represent a client identifier found in a request for
6005 instance.
6006
6007 string a table declared with "type string" will store substrings of up
6008 to <len> characters. If the string provided by the pattern
6009 extractor is larger than <len>, it will be truncated before
6010 being stored. During matching, at most <len> characters will be
6011 compared between the string in the table and the extracted
6012 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +02006013 to 32 characters.
6014
6015 binary a table declared with "type binary" will store binary blocks
6016 of <len> bytes. If the block provided by the pattern
6017 extractor is larger than <len>, it will be truncated before
6018 being stored. If the block provided by the pattern extractor
6019 is shorter than <len>, it will be padded by 0. When not
6020 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006021
6022 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +02006023 "string" type table (See type "string" above). Or the number
6024 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006025 changing this parameter as memory usage will proportionally
6026 increase.
6027
6028 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +01006029 value directly impacts memory usage. Count approximately
6030 50 bytes per entry, plus the size of a string if any. The size
6031 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006032
6033 [nopurge] indicates that we refuse to purge older entries when the table
6034 is full. When not specified and the table is full when haproxy
6035 wants to store an entry in it, it will flush a few of the oldest
6036 entries in order to release some space for the new ones. This is
6037 most often the desired behaviour. In some specific cases, it
6038 be desirable to refuse new entries instead of purging the older
6039 ones. That may be the case when the amount of data to store is
6040 far above the hardware limits and we prefer not to offer access
6041 to new clients than to reject the ones already connected. When
6042 using this parameter, be sure to properly set the "expire"
6043 parameter (see below).
6044
Emeric Brunf099e792010-09-27 12:05:28 +02006045 <peersect> is the name of the peers section to use for replication. Entries
6046 which associate keys to server IDs are kept synchronized with
6047 the remote peers declared in this section. All entries are also
6048 automatically learned from the local peer (old process) during a
6049 soft restart.
6050
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01006051 NOTE : peers can't be used in multi-process mode.
6052
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006053 <expire> defines the maximum duration of an entry in the table since it
6054 was last created, refreshed or matched. The expiration delay is
6055 defined using the standard time format, similarly as the various
6056 timeouts. The maximum duration is slightly above 24 days. See
6057 section 2.2 for more information. If this delay is not specified,
Cyril Bontédc4d9032012-04-08 21:57:39 +02006058 the session won't automatically expire, but older entries will
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006059 be removed once full. Be sure not to use the "nopurge" parameter
6060 if not expiration delay is specified.
6061
Willy Tarreau08d5f982010-06-06 13:34:54 +02006062 <data_type> is used to store additional information in the stick-table. This
6063 may be used by ACLs in order to control various criteria related
6064 to the activity of the client matching the stick-table. For each
6065 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +02006066 that the additional data can fit. Several data types may be
6067 stored with an entry. Multiple data types may be specified after
6068 the "store" keyword, as a comma-separated list. Alternatively,
6069 it is possible to repeat the "store" keyword followed by one or
6070 several data types. Except for the "server_id" type which is
6071 automatically detected and enabled, all data types must be
6072 explicitly declared to be stored. If an ACL references a data
6073 type which is not stored, the ACL will simply not match. Some
6074 data types require an argument which must be passed just after
6075 the type between parenthesis. See below for the supported data
6076 types and their arguments.
6077
6078 The data types that can be stored with an entry are the following :
6079 - server_id : this is an integer which holds the numeric ID of the server a
6080 request was assigned to. It is used by the "stick match", "stick store",
6081 and "stick on" rules. It is automatically enabled when referenced.
6082
6083 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
6084 integer which may be used for anything. Most of the time it will be used
6085 to put a special tag on some entries, for instance to note that a
6086 specific behaviour was detected and must be known for future matches.
6087
6088 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
6089 the absolute number of connections received from clients which matched
6090 this entry. It does not mean the connections were accepted, just that
6091 they were received.
6092
6093 - conn_cur : Current Connections. It is a positive 32-bit integer which
6094 stores the concurrent connection counts for the entry. It is incremented
6095 once an incoming connection matches the entry, and decremented once the
6096 connection leaves. That way it is possible to know at any time the exact
6097 number of concurrent connections for an entry.
6098
6099 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
6100 integer parameter <period> which indicates in milliseconds the length
6101 of the period over which the average is measured. It reports the average
6102 incoming connection rate over that period, in connections per period. The
6103 result is an integer which can be matched using ACLs.
6104
6105 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
6106 the absolute number of sessions received from clients which matched this
6107 entry. A session is a connection that was accepted by the layer 4 rules.
6108
6109 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
6110 integer parameter <period> which indicates in milliseconds the length
6111 of the period over which the average is measured. It reports the average
6112 incoming session rate over that period, in sessions per period. The
6113 result is an integer which can be matched using ACLs.
6114
6115 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
6116 counts the absolute number of HTTP requests received from clients which
6117 matched this entry. It does not matter whether they are valid requests or
6118 not. Note that this is different from sessions when keep-alive is used on
6119 the client side.
6120
6121 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
6122 integer parameter <period> which indicates in milliseconds the length
6123 of the period over which the average is measured. It reports the average
6124 HTTP request rate over that period, in requests per period. The result is
6125 an integer which can be matched using ACLs. It does not matter whether
6126 they are valid requests or not. Note that this is different from sessions
6127 when keep-alive is used on the client side.
6128
6129 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
6130 counts the absolute number of HTTP requests errors induced by clients
6131 which matched this entry. Errors are counted on invalid and truncated
6132 requests, as well as on denied or tarpitted requests, and on failed
6133 authentications. If the server responds with 4xx, then the request is
6134 also counted as an error since it's an error triggered by the client
6135 (eg: vulnerability scan).
6136
6137 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
6138 integer parameter <period> which indicates in milliseconds the length
6139 of the period over which the average is measured. It reports the average
6140 HTTP request error rate over that period, in requests per period (see
6141 http_err_cnt above for what is accounted as an error). The result is an
6142 integer which can be matched using ACLs.
6143
6144 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
6145 integer which counts the cumulated amount of bytes received from clients
6146 which matched this entry. Headers are included in the count. This may be
6147 used to limit abuse of upload features on photo or video servers.
6148
6149 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
6150 integer parameter <period> which indicates in milliseconds the length
6151 of the period over which the average is measured. It reports the average
6152 incoming bytes rate over that period, in bytes per period. It may be used
6153 to detect users which upload too much and too fast. Warning: with large
6154 uploads, it is possible that the amount of uploaded data will be counted
6155 once upon termination, thus causing spikes in the average transfer speed
6156 instead of having a smooth one. This may partially be smoothed with
6157 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
6158 recommended for better fairness.
6159
6160 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
6161 integer which counts the cumulated amount of bytes sent to clients which
6162 matched this entry. Headers are included in the count. This may be used
6163 to limit abuse of bots sucking the whole site.
6164
6165 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
6166 an integer parameter <period> which indicates in milliseconds the length
6167 of the period over which the average is measured. It reports the average
6168 outgoing bytes rate over that period, in bytes per period. It may be used
6169 to detect users which download too much and too fast. Warning: with large
6170 transfers, it is possible that the amount of transferred data will be
6171 counted once upon termination, thus causing spikes in the average
6172 transfer speed instead of having a smooth one. This may partially be
6173 smoothed with "option contstats" though this is not perfect yet. Use of
6174 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +02006175
Willy Tarreauc00cdc22010-06-06 16:48:26 +02006176 There is only one stick-table per proxy. At the moment of writing this doc,
6177 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006178 to be required, simply create a dummy backend with a stick-table in it and
6179 reference it.
6180
6181 It is important to understand that stickiness based on learning information
6182 has some limitations, including the fact that all learned associations are
6183 lost upon restart. In general it can be good as a complement but not always
6184 as an exclusive stickiness.
6185
Willy Tarreauc9705a12010-07-27 20:05:50 +02006186 Last, memory requirements may be important when storing many data types.
6187 Indeed, storing all indicators above at once in each entry requires 116 bytes
6188 per entry, or 116 MB for a 1-million entries table. This is definitely not
6189 something that can be ignored.
6190
6191 Example:
6192 # Keep track of counters of up to 1 million IP addresses over 5 minutes
6193 # and store a general purpose counter and the average connection rate
6194 # computed over a sliding window of 30 seconds.
6195 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
6196
6197 See also : "stick match", "stick on", "stick store-request", section 2.2
David du Colombiera13d1b92011-03-17 10:40:22 +01006198 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01006199
6200
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006201stick store-response <pattern> [table <table>] [{if | unless} <condition>]
6202 Define a request pattern used to create an entry in a stickiness table
6203 May be used in sections : defaults | frontend | listen | backend
6204 no | no | yes | yes
6205
6206 Arguments :
6207 <pattern> is a pattern extraction rule as described in section 7.8. It
6208 describes what elements of the response or connection will
6209 be analysed, extracted and stored in the table once a
6210 server is selected.
6211
6212 <table> is an optional stickiness table name. If unspecified, the same
6213 backend's table is used. A stickiness table is declared using
6214 the "stick-table" statement.
6215
6216 <cond> is an optional storage condition. It makes it possible to store
6217 certain criteria only when some conditions are met (or not met).
6218 For instance, it could be used to store the SSL session ID only
6219 when the response is a SSL server hello.
6220
6221 Some protocols or applications require complex stickiness rules and cannot
6222 always simply rely on cookies nor hashing. The "stick store-response"
6223 statement describes a rule to decide what to extract from the response and
6224 when to do it, in order to store it into a stickiness table for further
6225 requests to match it using the "stick match" statement. Obviously the
6226 extracted part must make sense and have a chance to be matched in a further
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006227 request. Storing an ID found in a header of a response makes sense.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006228 See section 7 for a complete list of possible patterns and transformation
6229 rules.
6230
6231 The table has to be declared using the "stick-table" statement. It must be of
6232 a type compatible with the pattern. By default it is the one which is present
6233 in the same backend. It is possible to share a table with other backends by
6234 referencing it using the "table" keyword. If another table is referenced,
6235 the server's ID inside the backends are used. By default, all server IDs
6236 start at 1 in each backend, so the server ordering is enough. But in case of
6237 doubt, it is highly recommended to force server IDs using their "id" setting.
6238
6239 It is possible to restrict the conditions where a "stick store-response"
6240 statement will apply, using "if" or "unless" followed by a condition. This
6241 condition will be evaluated while parsing the response, so any criteria can
6242 be used. See section 7 for ACL based conditions.
6243
6244 There is no limit on the number of "stick store-response" statements, but
6245 there is a limit of 8 simultaneous stores per request or response. This
6246 makes it possible to store up to 8 criteria, all extracted from either the
6247 request or the response, regardless of the number of rules. Only the 8 first
6248 ones which match will be kept. Using this, it is possible to feed multiple
6249 tables at once in the hope to increase the chance to recognize a user on
6250 another protocol or access method.
6251
6252 The table will contain the real server that processed the request.
6253
6254 Example :
6255 # Learn SSL session ID from both request and response and create affinity.
6256 backend https
6257 mode tcp
6258 balance roundrobin
Cyril Bontédc4d9032012-04-08 21:57:39 +02006259 # maximum SSL session ID length is 32 bytes.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006260 stick-table type binary len 32 size 30k expire 30m
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006261
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006262 acl clienthello req_ssl_hello_type 1
6263 acl serverhello rep_ssl_hello_type 2
6264
6265 # use tcp content accepts to detects ssl client and server hello.
6266 tcp-request inspect-delay 5s
6267 tcp-request content accept if clienthello
6268
6269 # no timeout on response inspect delay by default.
6270 tcp-response content accept if serverhello
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006271
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006272 # SSL session ID (SSLID) may be present on a client or server hello.
6273 # Its length is coded on 1 byte at offset 43 and its value starts
6274 # at offset 44.
6275
6276 # Match and learn on request if client hello.
6277 stick on payload_lv(43,1) if clienthello
6278
6279 # Learn on response if server hello.
6280 stick store-response payload_lv(43,1) if serverhello
Cyril Bontédc4d9032012-04-08 21:57:39 +02006281
Emeric Brun6a1cefa2010-09-24 18:15:17 +02006282 server s1 192.168.1.1:443
6283 server s2 192.168.1.1:443
6284
6285 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
6286 extraction.
6287
6288
Willy Tarreaue9656522010-08-17 15:40:09 +02006289tcp-request connection <action> [{if | unless} <condition>]
6290 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +02006291 May be used in sections : defaults | frontend | listen | backend
6292 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +02006293 Arguments :
6294 <action> defines the action to perform if the condition applies. Valid
6295 actions include : "accept", "reject", "track-sc1", "track-sc2".
6296 See below for more details.
Willy Tarreau1a687942010-05-23 22:40:30 +02006297
Willy Tarreaue9656522010-08-17 15:40:09 +02006298 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006299
6300 Immediately after acceptance of a new incoming connection, it is possible to
6301 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +02006302 or dropped or have its counters tracked. Those conditions cannot make use of
6303 any data contents because the connection has not been read from yet, and the
6304 buffers are not yet allocated. This is used to selectively and very quickly
6305 accept or drop connections from various sources with a very low overhead. If
6306 some contents need to be inspected in order to take the decision, the
6307 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006308
Willy Tarreaue9656522010-08-17 15:40:09 +02006309 The "tcp-request connection" rules are evaluated in their exact declaration
6310 order. If no rule matches or if there is no rule, the default action is to
6311 accept the incoming connection. There is no specific limit to the number of
6312 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006313
Willy Tarreaue9656522010-08-17 15:40:09 +02006314 Three types of actions are supported :
6315 - accept :
6316 accepts the connection if the condition is true (when used with "if")
6317 or false (when used with "unless"). The first such rule executed ends
6318 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006319
Willy Tarreaue9656522010-08-17 15:40:09 +02006320 - reject :
6321 rejects the connection if the condition is true (when used with "if")
6322 or false (when used with "unless"). The first such rule executed ends
6323 the rules evaluation. Rejected connections do not even become a
6324 session, which is why they are accounted separately for in the stats,
6325 as "denied connections". They are not considered for the session
6326 rate-limit and are not logged either. The reason is that these rules
6327 should only be used to filter extremely high connection rates such as
6328 the ones encountered during a massive DDoS attack. Under these extreme
6329 conditions, the simple action of logging each event would make the
6330 system collapse and would considerably lower the filtering capacity. If
6331 logging is absolutely desired, then "tcp-request content" rules should
6332 be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006333
Willy Tarreaue9656522010-08-17 15:40:09 +02006334 - { track-sc1 | track-sc2 } <key> [table <table>] :
6335 enables tracking of sticky counters from current connection. These
6336 rules do not stop evaluation and do not change default action. Two sets
6337 of counters may be simultaneously tracked by the same connection. The
6338 first "track-sc1" rule executed enables tracking of the counters of the
6339 specified table as the first set. The first "track-sc2" rule executed
6340 enables tracking of the counters of the specified table as the second
6341 set. It is a recommended practice to use the first set of counters for
6342 the per-frontend counters and the second set for the per-backend ones.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006343
Willy Tarreaue9656522010-08-17 15:40:09 +02006344 These actions take one or two arguments :
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01006345 <key> is mandatory, and is a pattern extraction rule as described
6346 in section 7.8. It describes what elements of the incoming
6347 request or connection will be analysed, extracted, combined,
6348 and used to select which table entry to update the counters.
6349 Note that "tcp-request connection" cannot use content-based
6350 fetches.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006351
Willy Tarreaue9656522010-08-17 15:40:09 +02006352 <table> is an optional table to be used instead of the default one,
6353 which is the stick-table declared in the current proxy. All
6354 the counters for the matches and updates for the key will
6355 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006356
Willy Tarreaue9656522010-08-17 15:40:09 +02006357 Once a "track-sc*" rule is executed, the key is looked up in the table
6358 and if it is not found, an entry is allocated for it. Then a pointer to
6359 that entry is kept during all the session's life, and this entry's
6360 counters are updated as often as possible, every time the session's
6361 counters are updated, and also systematically when the session ends.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01006362 Counters are only updated for events that happen after the tracking has
6363 been started. For example, connection counters will not be updated when
6364 tracking layer 7 information, since the connection event happens before
6365 layer7 information is extracted.
6366
Willy Tarreaue9656522010-08-17 15:40:09 +02006367 If the entry tracks concurrent connection counters, one connection is
6368 counted for as long as the entry is tracked, and the entry will not
6369 expire during that time. Tracking counters also provides a performance
6370 advantage over just checking the keys, because only one table lookup is
6371 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006372
Willy Tarreaue9656522010-08-17 15:40:09 +02006373 Note that the "if/unless" condition is optional. If no condition is set on
6374 the action, it is simply performed unconditionally. That can be useful for
6375 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006376
Willy Tarreaue9656522010-08-17 15:40:09 +02006377 Example: accept all connections from white-listed hosts, reject too fast
6378 connection without counting them, and track accepted connections.
6379 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006380
Willy Tarreaue9656522010-08-17 15:40:09 +02006381 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006382 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaue9656522010-08-17 15:40:09 +02006383 tcp-request connection track-sc1 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006384
Willy Tarreaue9656522010-08-17 15:40:09 +02006385 Example: accept all connections from white-listed hosts, count all other
6386 connections and reject too fast ones. This results in abusive ones
6387 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006388
Willy Tarreaue9656522010-08-17 15:40:09 +02006389 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
6390 tcp-request connection track-sc1 src
6391 tcp-request connection reject if { sc1_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006392
6393 See section 7 about ACL usage.
6394
Willy Tarreaue9656522010-08-17 15:40:09 +02006395 See also : "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006396
6397
Willy Tarreaue9656522010-08-17 15:40:09 +02006398tcp-request content <action> [{if | unless} <condition>]
6399 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +02006400 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02006401 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +02006402 Arguments :
6403 <action> defines the action to perform if the condition applies. Valid
6404 actions include : "accept", "reject", "track-sc1", "track-sc2".
6405 See "tcp-request connection" above for their signification.
Willy Tarreau62644772008-07-16 18:36:06 +02006406
Willy Tarreaue9656522010-08-17 15:40:09 +02006407 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +02006408
Willy Tarreaue9656522010-08-17 15:40:09 +02006409 A request's contents can be analysed at an early stage of request processing
6410 called "TCP content inspection". During this stage, ACL-based rules are
6411 evaluated every time the request contents are updated, until either an
6412 "accept" or a "reject" rule matches, or the TCP request inspection delay
6413 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +02006414
Willy Tarreaue9656522010-08-17 15:40:09 +02006415 The first difference between these rules and "tcp-request connection" rules
6416 is that "tcp-request content" rules can make use of contents to take a
6417 decision. Most often, these decisions will consider a protocol recognition or
6418 validity. The second difference is that content-based rules can be used in
6419 both frontends and backends. In frontends, they will be evaluated upon new
6420 connections. In backends, they will be evaluated once a session is assigned
6421 a backend. This means that a single frontend connection may be evaluated
6422 several times by one or multiple backends when a session gets reassigned
6423 (for instance after a client-side HTTP keep-alive request).
Willy Tarreau62644772008-07-16 18:36:06 +02006424
Willy Tarreaue9656522010-08-17 15:40:09 +02006425 Content-based rules are evaluated in their exact declaration order. If no
6426 rule matches or if there is no rule, the default action is to accept the
6427 contents. There is no specific limit to the number of rules which may be
6428 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +02006429
Willy Tarreaue9656522010-08-17 15:40:09 +02006430 Three types of actions are supported :
6431 - accept :
6432 - reject :
6433 - { track-sc1 | track-sc2 } <key> [table <table>]
Willy Tarreau62644772008-07-16 18:36:06 +02006434
Willy Tarreaue9656522010-08-17 15:40:09 +02006435 They have the same meaning as their counter-parts in "tcp-request connection"
6436 so please refer to that section for a complete description.
Willy Tarreau62644772008-07-16 18:36:06 +02006437
Willy Tarreaue9656522010-08-17 15:40:09 +02006438 Also, it is worth noting that if sticky counters are tracked from a rule
6439 defined in a backend, this tracking will automatically end when the session
6440 releases the backend. That allows per-backend counter tracking even in case
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01006441 of HTTP keep-alive requests when the backend changes. This makes a subtle
6442 difference because tracking rules in "frontend" and "listen" section last for
6443 all the session, as opposed to the backend rules. The difference appears when
6444 some layer 7 information is tracked. While there is nothing mandatory about
6445 it, it is recommended to use the track-sc1 pointer to track per-frontend
6446 counters and track-sc2 to track per-backend counters.
Willy Tarreau62644772008-07-16 18:36:06 +02006447
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006448 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +02006449 the action, it is simply performed unconditionally. That can be useful for
6450 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +02006451
Willy Tarreaue9656522010-08-17 15:40:09 +02006452 It is perfectly possible to match layer 7 contents with "tcp-request content"
Willy Tarreauc0239e02012-04-16 14:42:55 +02006453 rules, since HTTP-specific ACL matches are able to preliminarily parse the
6454 contents of a buffer before extracting the required data. If the buffered
6455 contents do not parse as a valid HTTP message, then the ACL does not match.
6456 The parser which is involved there is exactly the same as for all other HTTP
6457 processing, so there is no risk of parsing something differently.
Willy Tarreau62644772008-07-16 18:36:06 +02006458
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01006459 Tracking layer7 information is also possible provided that the information
6460 are present when the rule is processed. The current solution for making the
6461 rule engine wait for such information is to set an inspect delay and to
6462 condition its execution with an ACL relying on such information.
6463
Willy Tarreau62644772008-07-16 18:36:06 +02006464 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +02006465 # Accept HTTP requests containing a Host header saying "example.com"
6466 # and reject everything else.
6467 acl is_host_com hdr(Host) -i example.com
6468 tcp-request inspect-delay 30s
Willy Tarreauc0239e02012-04-16 14:42:55 +02006469 tcp-request content accept if is_host_com
Willy Tarreaue9656522010-08-17 15:40:09 +02006470 tcp-request content reject
6471
6472 Example:
Willy Tarreau62644772008-07-16 18:36:06 +02006473 # reject SMTP connection if client speaks first
6474 tcp-request inspect-delay 30s
6475 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006476 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +02006477
6478 # Forward HTTPS connection only if client speaks
6479 tcp-request inspect-delay 30s
6480 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +02006481 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +02006482 tcp-request content reject
6483
Willy Tarreau5d5b5d82012-12-09 12:00:04 +01006484 Example:
6485 # Track the last IP from X-Forwarded-For
6486 tcp-request inspect-delay 10s
6487 tcp-request content track-sc1 hdr(x-forwarded-for,-1) if HTTP
6488
6489 Example:
6490 # track request counts per "base" (concatenation of Host+URL)
6491 tcp-request inspect-delay 10s
6492 tcp-request content track-sc1 base table req-rate if HTTP
6493
Willy Tarreaue9656522010-08-17 15:40:09 +02006494 Example: track per-frontend and per-backend counters, block abusers at the
6495 frontend when the backend detects abuse.
6496
6497 frontend http
6498 # Use General Purpose Couter 0 in SC1 as a global abuse counter
6499 # protecting all our sites
6500 stick-table type ip size 1m expire 5m store gpc0
6501 tcp-request connection track-sc1 src
6502 tcp-request connection reject if { sc1_get_gpc0 gt 0 }
6503 ...
6504 use_backend http_dynamic if { path_end .php }
6505
6506 backend http_dynamic
6507 # if a source makes too fast requests to this dynamic site (tracked
6508 # by SC2), block it globally in the frontend.
6509 stick-table type ip size 1m expire 5m store http_req_rate(10s)
6510 acl click_too_fast sc2_http_req_rate gt 10
Willy Tarreau869948b2013-01-04 14:14:57 +01006511 acl mark_as_abuser sc1_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +02006512 tcp-request content track-sc2 src
6513 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +02006514
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006515 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +02006516
Willy Tarreaue9656522010-08-17 15:40:09 +02006517 See also : "tcp-request connection", "tcp-request inspect-delay"
Willy Tarreau62644772008-07-16 18:36:06 +02006518
6519
6520tcp-request inspect-delay <timeout>
6521 Set the maximum allowed time to wait for data during content inspection
6522 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +02006523 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +02006524 Arguments :
6525 <timeout> is the timeout value specified in milliseconds by default, but
6526 can be in any other unit if the number is suffixed by the unit,
6527 as explained at the top of this document.
6528
6529 People using haproxy primarily as a TCP relay are often worried about the
6530 risk of passing any type of protocol to a server without any analysis. In
6531 order to be able to analyze the request contents, we must first withhold
6532 the data then analyze them. This statement simply enables withholding of
6533 data for at most the specified amount of time.
6534
Willy Tarreaufb356202010-08-03 14:02:05 +02006535 TCP content inspection applies very early when a connection reaches a
6536 frontend, then very early when the connection is forwarded to a backend. This
6537 means that a connection may experience a first delay in the frontend and a
6538 second delay in the backend if both have tcp-request rules.
6539
Willy Tarreau62644772008-07-16 18:36:06 +02006540 Note that when performing content inspection, haproxy will evaluate the whole
6541 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006542 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +02006543 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +01006544 contents are definitive. If no delay is set, haproxy will not wait at all
6545 and will immediately apply a verdict based on the available information.
6546 Obviously this is unlikely to be very useful and might even be racy, so such
6547 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +02006548
6549 As soon as a rule matches, the request is released and continues as usual. If
6550 the timeout is reached and no rule matches, the default policy will be to let
6551 it pass through unaffected.
6552
6553 For most protocols, it is enough to set it to a few seconds, as most clients
6554 send the full request immediately upon connection. Add 3 or more seconds to
6555 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +01006556 to use large values, for instance to ensure that the client never talks
Willy Tarreau62644772008-07-16 18:36:06 +02006557 before the server (eg: SMTP), or to wait for a client to talk before passing
6558 data to the server (eg: SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +02006559 least the inspection delay, otherwise it will expire first. If the client
6560 closes the connection or if the buffer is full, the delay immediately expires
6561 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +02006562
Willy Tarreau55165fe2009-05-10 12:02:55 +02006563 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +02006564 "timeout client".
6565
6566
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006567tcp-response content <action> [{if | unless} <condition>]
6568 Perform an action on a session response depending on a layer 4-7 condition
6569 May be used in sections : defaults | frontend | listen | backend
6570 no | no | yes | yes
6571 Arguments :
6572 <action> defines the action to perform if the condition applies. Valid
6573 actions include : "accept", "reject".
6574 See "tcp-request connection" above for their signification.
6575
6576 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
6577
6578 Response contents can be analysed at an early stage of response processing
6579 called "TCP content inspection". During this stage, ACL-based rules are
6580 evaluated every time the response contents are updated, until either an
6581 "accept" or a "reject" rule matches, or a TCP response inspection delay is
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006582 set and expires with no matching rule.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006583
6584 Most often, these decisions will consider a protocol recognition or validity.
6585
6586 Content-based rules are evaluated in their exact declaration order. If no
6587 rule matches or if there is no rule, the default action is to accept the
6588 contents. There is no specific limit to the number of rules which may be
6589 inserted.
6590
6591 Two types of actions are supported :
6592 - accept :
6593 accepts the response if the condition is true (when used with "if")
6594 or false (when used with "unless"). The first such rule executed ends
6595 the rules evaluation.
6596
6597 - reject :
6598 rejects the response if the condition is true (when used with "if")
6599 or false (when used with "unless"). The first such rule executed ends
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006600 the rules evaluation. Rejected session are immediately closed.
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006601
6602 Note that the "if/unless" condition is optional. If no condition is set on
6603 the action, it is simply performed unconditionally. That can be useful for
6604 for changing the default action to a reject.
6605
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006606 It is perfectly possible to match layer 7 contents with "tcp-response
6607 content" rules, but then it is important to ensure that a full response has
6608 been buffered, otherwise no contents will match. In order to achieve this,
6609 the best solution involves detecting the HTTP protocol during the inspection
Emeric Brun0a3b67f2010-09-24 15:34:53 +02006610 period.
6611
6612 See section 7 about ACL usage.
6613
6614 See also : "tcp-request content", "tcp-response inspect-delay"
6615
6616
6617tcp-response inspect-delay <timeout>
6618 Set the maximum allowed time to wait for a response during content inspection
6619 May be used in sections : defaults | frontend | listen | backend
6620 no | no | yes | yes
6621 Arguments :
6622 <timeout> is the timeout value specified in milliseconds by default, but
6623 can be in any other unit if the number is suffixed by the unit,
6624 as explained at the top of this document.
6625
6626 See also : "tcp-response content", "tcp-request inspect-delay".
6627
6628
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006629timeout check <timeout>
6630 Set additional check timeout, but only after a connection has been already
6631 established.
6632
6633 May be used in sections: defaults | frontend | listen | backend
6634 yes | no | yes | yes
6635 Arguments:
6636 <timeout> is the timeout value specified in milliseconds by default, but
6637 can be in any other unit if the number is suffixed by the unit,
6638 as explained at the top of this document.
6639
6640 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
6641 for check and "timeout check" as an additional read timeout. The "min" is
6642 used so that people running with *very* long "timeout connect" (eg. those
6643 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +01006644 (Please also note that there is no valid reason to have such long connect
6645 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
6646 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006647
6648 If "timeout check" is not set haproxy uses "inter" for complete check
6649 timeout (connect + read) exactly like all <1.3.15 version.
6650
6651 In most cases check request is much simpler and faster to handle than normal
6652 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +01006653 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006654
6655 This parameter is specific to backends, but can be specified once for all in
6656 "defaults" sections. This is in fact one of the easiest solutions not to
6657 forget about it.
6658
Willy Tarreau41a340d2008-01-22 12:25:31 +01006659 See also: "timeout connect", "timeout queue", "timeout server",
6660 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006661
6662
Willy Tarreau0ba27502007-12-24 16:55:16 +01006663timeout client <timeout>
6664timeout clitimeout <timeout> (deprecated)
6665 Set the maximum inactivity time on the client side.
6666 May be used in sections : defaults | frontend | listen | backend
6667 yes | yes | yes | no
6668 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006669 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01006670 can be in any other unit if the number is suffixed by the unit,
6671 as explained at the top of this document.
6672
6673 The inactivity timeout applies when the client is expected to acknowledge or
6674 send data. In HTTP mode, this timeout is particularly important to consider
6675 during the first phase, when the client sends the request, and during the
6676 response while it is reading data sent by the server. The value is specified
6677 in milliseconds by default, but can be in any other unit if the number is
6678 suffixed by the unit, as specified at the top of this document. In TCP mode
6679 (and to a lesser extent, in HTTP mode), it is highly recommended that the
6680 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006681 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01006682 losses by specifying timeouts that are slightly above multiples of 3 seconds
Willy Tarreauce887fd2012-05-12 12:50:00 +02006683 (eg: 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
6684 sessions (eg: WebSocket and HTTP), it's worth considering "timeout tunnel",
6685 which overrides "timeout client" and "timeout server" for tunnels.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006686
6687 This parameter is specific to frontends, but can be specified once for all in
6688 "defaults" sections. This is in fact one of the easiest solutions not to
6689 forget about it. An unspecified timeout results in an infinite timeout, which
6690 is not recommended. Such a usage is accepted and works but reports a warning
6691 during startup because it may results in accumulation of expired sessions in
6692 the system if the system's timeouts are not configured either.
6693
6694 This parameter replaces the old, deprecated "clitimeout". It is recommended
6695 to use it to write new configurations. The form "timeout clitimeout" is
6696 provided only by backwards compatibility but its use is strongly discouraged.
6697
Willy Tarreauce887fd2012-05-12 12:50:00 +02006698 See also : "clitimeout", "timeout server", "timeout tunnel".
Willy Tarreau0ba27502007-12-24 16:55:16 +01006699
6700
6701timeout connect <timeout>
6702timeout contimeout <timeout> (deprecated)
6703 Set the maximum time to wait for a connection attempt to a server to succeed.
6704 May be used in sections : defaults | frontend | listen | backend
6705 yes | no | yes | yes
6706 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006707 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +01006708 can be in any other unit if the number is suffixed by the unit,
6709 as explained at the top of this document.
6710
6711 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006712 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01006713 cover one or several TCP packet losses by specifying timeouts that are
Willy Tarreau0ba27502007-12-24 16:55:16 +01006714 slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +01006715 connect timeout also presets both queue and tarpit timeouts to the same value
6716 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006717
6718 This parameter is specific to backends, but can be specified once for all in
6719 "defaults" sections. This is in fact one of the easiest solutions not to
6720 forget about it. An unspecified timeout results in an infinite timeout, which
6721 is not recommended. Such a usage is accepted and works but reports a warning
6722 during startup because it may results in accumulation of failed sessions in
6723 the system if the system's timeouts are not configured either.
6724
6725 This parameter replaces the old, deprecated "contimeout". It is recommended
6726 to use it to write new configurations. The form "timeout contimeout" is
6727 provided only by backwards compatibility but its use is strongly discouraged.
6728
Willy Tarreau41a340d2008-01-22 12:25:31 +01006729 See also: "timeout check", "timeout queue", "timeout server", "contimeout",
6730 "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +01006731
6732
Willy Tarreaub16a5742010-01-10 14:46:16 +01006733timeout http-keep-alive <timeout>
6734 Set the maximum allowed time to wait for a new HTTP request to appear
6735 May be used in sections : defaults | frontend | listen | backend
6736 yes | yes | yes | yes
6737 Arguments :
6738 <timeout> is the timeout value specified in milliseconds by default, but
6739 can be in any other unit if the number is suffixed by the unit,
6740 as explained at the top of this document.
6741
6742 By default, the time to wait for a new request in case of keep-alive is set
6743 by "timeout http-request". However this is not always convenient because some
6744 people want very short keep-alive timeouts in order to release connections
6745 faster, and others prefer to have larger ones but still have short timeouts
6746 once the request has started to present itself.
6747
6748 The "http-keep-alive" timeout covers these needs. It will define how long to
6749 wait for a new HTTP request to start coming after a response was sent. Once
6750 the first byte of request has been seen, the "http-request" timeout is used
6751 to wait for the complete request to come. Note that empty lines prior to a
6752 new request do not refresh the timeout and are not counted as a new request.
6753
6754 There is also another difference between the two timeouts : when a connection
6755 expires during timeout http-keep-alive, no error is returned, the connection
6756 just closes. If the connection expires in "http-request" while waiting for a
6757 connection to complete, a HTTP 408 error is returned.
6758
6759 In general it is optimal to set this value to a few tens to hundreds of
6760 milliseconds, to allow users to fetch all objects of a page at once but
6761 without waiting for further clicks. Also, if set to a very small value (eg:
6762 1 millisecond) it will probably only accept pipelined requests but not the
6763 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +02006764 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +01006765
6766 If this parameter is not set, the "http-request" timeout applies, and if both
6767 are not set, "timeout client" still applies at the lower level. It should be
6768 set in the frontend to take effect, unless the frontend is in TCP mode, in
6769 which case the HTTP backend's timeout will be used.
6770
6771 See also : "timeout http-request", "timeout client".
6772
6773
Willy Tarreau036fae02008-01-06 13:24:40 +01006774timeout http-request <timeout>
6775 Set the maximum allowed time to wait for a complete HTTP request
6776 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +02006777 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +01006778 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +01006779 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +01006780 can be in any other unit if the number is suffixed by the unit,
6781 as explained at the top of this document.
6782
6783 In order to offer DoS protection, it may be required to lower the maximum
6784 accepted time to receive a complete HTTP request without affecting the client
6785 timeout. This helps protecting against established connections on which
6786 nothing is sent. The client timeout cannot offer a good protection against
6787 this abuse because it is an inactivity timeout, which means that if the
6788 attacker sends one character every now and then, the timeout will not
6789 trigger. With the HTTP request timeout, no matter what speed the client
6790 types, the request will be aborted if it does not complete in time.
6791
6792 Note that this timeout only applies to the header part of the request, and
6793 not to any data. As soon as the empty line is received, this timeout is not
Willy Tarreaub16a5742010-01-10 14:46:16 +01006794 used anymore. It is used again on keep-alive connections to wait for a second
6795 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +01006796
6797 Generally it is enough to set it to a few seconds, as most clients send the
6798 full request immediately upon connection. Add 3 or more seconds to cover TCP
6799 retransmits but that's all. Setting it to very low values (eg: 50 ms) will
6800 generally work on local networks as long as there are no packet losses. This
6801 will prevent people from sending bare HTTP requests using telnet.
6802
6803 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +02006804 chunk of the incoming request. It should be set in the frontend to take
6805 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
6806 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +01006807
Willy Tarreaub16a5742010-01-10 14:46:16 +01006808 See also : "timeout http-keep-alive", "timeout client".
Willy Tarreau036fae02008-01-06 13:24:40 +01006809
Willy Tarreau844e3c52008-01-11 16:28:18 +01006810
6811timeout queue <timeout>
6812 Set the maximum time to wait in the queue for a connection slot to be free
6813 May be used in sections : defaults | frontend | listen | backend
6814 yes | no | yes | yes
6815 Arguments :
6816 <timeout> is the timeout value specified in milliseconds by default, but
6817 can be in any other unit if the number is suffixed by the unit,
6818 as explained at the top of this document.
6819
6820 When a server's maxconn is reached, connections are left pending in a queue
6821 which may be server-specific or global to the backend. In order not to wait
6822 indefinitely, a timeout is applied to requests pending in the queue. If the
6823 timeout is reached, it is considered that the request will almost never be
6824 served, so it is dropped and a 503 error is returned to the client.
6825
6826 The "timeout queue" statement allows to fix the maximum time for a request to
6827 be left pending in a queue. If unspecified, the same value as the backend's
6828 connection timeout ("timeout connect") is used, for backwards compatibility
6829 with older versions with no "timeout queue" parameter.
6830
6831 See also : "timeout connect", "contimeout".
6832
6833
6834timeout server <timeout>
6835timeout srvtimeout <timeout> (deprecated)
6836 Set the maximum inactivity time on the server side.
6837 May be used in sections : defaults | frontend | listen | backend
6838 yes | no | yes | yes
6839 Arguments :
6840 <timeout> is the timeout value specified in milliseconds by default, but
6841 can be in any other unit if the number is suffixed by the unit,
6842 as explained at the top of this document.
6843
6844 The inactivity timeout applies when the server is expected to acknowledge or
6845 send data. In HTTP mode, this timeout is particularly important to consider
6846 during the first phase of the server's response, when it has to send the
6847 headers, as it directly represents the server's processing time for the
6848 request. To find out what value to put there, it's often good to start with
6849 what would be considered as unacceptable response times, then check the logs
6850 to observe the response time distribution, and adjust the value accordingly.
6851
6852 The value is specified in milliseconds by default, but can be in any other
6853 unit if the number is suffixed by the unit, as specified at the top of this
6854 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
6855 recommended that the client timeout remains equal to the server timeout in
6856 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006857 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01006858 packet losses by specifying timeouts that are slightly above multiples of 3
Willy Tarreauce887fd2012-05-12 12:50:00 +02006859 seconds (eg: 4 or 5 seconds minimum). If some long-lived sessions are mixed
6860 with short-lived sessions (eg: WebSocket and HTTP), it's worth considering
6861 "timeout tunnel", which overrides "timeout client" and "timeout server" for
6862 tunnels.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006863
6864 This parameter is specific to backends, but can be specified once for all in
6865 "defaults" sections. This is in fact one of the easiest solutions not to
6866 forget about it. An unspecified timeout results in an infinite timeout, which
6867 is not recommended. Such a usage is accepted and works but reports a warning
6868 during startup because it may results in accumulation of expired sessions in
6869 the system if the system's timeouts are not configured either.
6870
6871 This parameter replaces the old, deprecated "srvtimeout". It is recommended
6872 to use it to write new configurations. The form "timeout srvtimeout" is
6873 provided only by backwards compatibility but its use is strongly discouraged.
6874
Willy Tarreauce887fd2012-05-12 12:50:00 +02006875 See also : "srvtimeout", "timeout client" and "timeout tunnel".
Willy Tarreau844e3c52008-01-11 16:28:18 +01006876
6877
6878timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +01006879 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +01006880 May be used in sections : defaults | frontend | listen | backend
6881 yes | yes | yes | yes
6882 Arguments :
6883 <timeout> is the tarpit duration specified in milliseconds by default, but
6884 can be in any other unit if the number is suffixed by the unit,
6885 as explained at the top of this document.
6886
6887 When a connection is tarpitted using "reqtarpit", it is maintained open with
6888 no activity for a certain amount of time, then closed. "timeout tarpit"
6889 defines how long it will be maintained open.
6890
6891 The value is specified in milliseconds by default, but can be in any other
6892 unit if the number is suffixed by the unit, as specified at the top of this
6893 document. If unspecified, the same value as the backend's connection timeout
6894 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +01006895 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +01006896
6897 See also : "timeout connect", "contimeout".
6898
6899
Willy Tarreauce887fd2012-05-12 12:50:00 +02006900timeout tunnel <timeout>
6901 Set the maximum inactivity time on the client and server side for tunnels.
6902 May be used in sections : defaults | frontend | listen | backend
6903 yes | no | yes | yes
6904 Arguments :
6905 <timeout> is the timeout value specified in milliseconds by default, but
6906 can be in any other unit if the number is suffixed by the unit,
6907 as explained at the top of this document.
6908
Jamie Gloudonaaa21002012-08-25 00:18:33 -04006909 The tunnel timeout applies when a bidirectional connection is established
Willy Tarreauce887fd2012-05-12 12:50:00 +02006910 between a client and a server, and the connection remains inactive in both
6911 directions. This timeout supersedes both the client and server timeouts once
6912 the connection becomes a tunnel. In TCP, this timeout is used as soon as no
6913 analyser remains attached to either connection (eg: tcp content rules are
6914 accepted). In HTTP, this timeout is used when a connection is upgraded (eg:
6915 when switching to the WebSocket protocol, or forwarding a CONNECT request
6916 to a proxy), or after the first response when no keepalive/close option is
6917 specified.
6918
6919 The value is specified in milliseconds by default, but can be in any other
6920 unit if the number is suffixed by the unit, as specified at the top of this
6921 document. Whatever the expected normal idle time, it is a good practice to
6922 cover at least one or several TCP packet losses by specifying timeouts that
6923 are slightly above multiples of 3 seconds (eg: 4 or 5 seconds minimum).
6924
6925 This parameter is specific to backends, but can be specified once for all in
6926 "defaults" sections. This is in fact one of the easiest solutions not to
6927 forget about it.
6928
6929 Example :
6930 defaults http
6931 option http-server-close
6932 timeout connect 5s
6933 timeout client 30s
6934 timeout client 30s
6935 timeout server 30s
6936 timeout tunnel 1h # timeout to use with WebSocket and CONNECT
6937
6938 See also : "timeout client", "timeout server".
6939
6940
Willy Tarreau844e3c52008-01-11 16:28:18 +01006941transparent (deprecated)
6942 Enable client-side transparent proxying
6943 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01006944 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01006945 Arguments : none
6946
6947 This keyword was introduced in order to provide layer 7 persistence to layer
6948 3 load balancers. The idea is to use the OS's ability to redirect an incoming
6949 connection for a remote address to a local process (here HAProxy), and let
6950 this process know what address was initially requested. When this option is
6951 used, sessions without cookies will be forwarded to the original destination
6952 IP address of the incoming request (which should match that of another
6953 equipment), while requests with cookies will still be forwarded to the
6954 appropriate server.
6955
6956 The "transparent" keyword is deprecated, use "option transparent" instead.
6957
6958 Note that contrary to a common belief, this option does NOT make HAProxy
6959 present the client's IP to the server when establishing the connection.
6960
Willy Tarreau844e3c52008-01-11 16:28:18 +01006961 See also: "option transparent"
6962
William Lallemanda73203e2012-03-12 12:48:57 +01006963unique-id-format <string>
6964 Generate a unique ID for each request.
6965 May be used in sections : defaults | frontend | listen | backend
6966 yes | yes | yes | no
6967 Arguments :
6968 <string> is a log-format string.
6969
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006970 This keyword creates a ID for each request using the custom log format. A
6971 unique ID is useful to trace a request passing through many components of
6972 a complex infrastructure. The newly created ID may also be logged using the
6973 %ID tag the log-format string.
William Lallemanda73203e2012-03-12 12:48:57 +01006974
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006975 The format should be composed from elements that are guaranteed to be
6976 unique when combined together. For instance, if multiple haproxy instances
6977 are involved, it might be important to include the node name. It is often
6978 needed to log the incoming connection's source and destination addresses
6979 and ports. Note that since multiple requests may be performed over the same
6980 connection, including a request counter may help differentiate them.
6981 Similarly, a timestamp may protect against a rollover of the counter.
6982 Logging the process ID will avoid collisions after a service restart.
William Lallemanda73203e2012-03-12 12:48:57 +01006983
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006984 It is recommended to use hexadecimal notation for many fields since it
6985 makes them more compact and saves space in logs.
William Lallemanda73203e2012-03-12 12:48:57 +01006986
Cyril Bonté108cf6e2012-04-21 23:30:29 +02006987 Example:
William Lallemanda73203e2012-03-12 12:48:57 +01006988
6989 unique-id-format %{+X}o\ %Ci:%Cp_%Fi:%Fp_%Ts_%rt:%pid
6990
6991 will generate:
6992
6993 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
6994
6995 See also: "unique-id-header"
6996
6997unique-id-header <name>
6998 Add a unique ID header in the HTTP request.
6999 May be used in sections : defaults | frontend | listen | backend
7000 yes | yes | yes | no
7001 Arguments :
7002 <name> is the name of the header.
7003
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007004 Add a unique-id header in the HTTP request sent to the server, using the
7005 unique-id-format. It can't work if the unique-id-format doesn't exist.
William Lallemanda73203e2012-03-12 12:48:57 +01007006
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007007 Example:
William Lallemanda73203e2012-03-12 12:48:57 +01007008
7009 unique-id-format %{+X}o\ %Ci:%Cp_%Fi:%Fp_%Ts_%rt:%pid
7010 unique-id-header X-Unique-ID
7011
7012 will generate:
7013
7014 X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
7015
7016 See also: "unique-id-format"
Willy Tarreau844e3c52008-01-11 16:28:18 +01007017
7018use_backend <backend> if <condition>
7019use_backend <backend> unless <condition>
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02007020 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007021 May be used in sections : defaults | frontend | listen | backend
7022 no | yes | yes | no
7023 Arguments :
7024 <backend> is the name of a valid backend or "listen" section.
7025
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007026 <condition> is a condition composed of ACLs, as described in section 7.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007027
7028 When doing content-switching, connections arrive on a frontend and are then
7029 dispatched to various backends depending on a number of conditions. The
7030 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02007031 "use_backend" keyword. While it is normally used with HTTP processing, it can
7032 also be used in pure TCP, either without content using stateless ACLs (eg:
7033 source address validation) or combined with a "tcp-request" rule to wait for
7034 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007035
7036 There may be as many "use_backend" rules as desired. All of these rules are
7037 evaluated in their declaration order, and the first one which matches will
7038 assign the backend.
7039
7040 In the first form, the backend will be used if the condition is met. In the
7041 second form, the backend will be used if the condition is not met. If no
7042 condition is valid, the backend defined with "default_backend" will be used.
7043 If no default backend is defined, either the servers in the same section are
7044 used (in case of a "listen" section) or, in case of a frontend, no server is
7045 used and a 503 service unavailable response is returned.
7046
Willy Tarreau51aecc72009-07-12 09:47:04 +02007047 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007048 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +02007049 and backend processing will immediately follow, or the backend will wait for
7050 a complete HTTP request to get in. This feature is useful when a frontend
7051 must decode several protocols on a unique port, one of them being HTTP.
7052
Willy Tarreau1d0dfb12009-07-07 15:10:31 +02007053 See also: "default_backend", "tcp-request", and section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +01007054
Willy Tarreau036fae02008-01-06 13:24:40 +01007055
Willy Tarreau4a5cade2012-04-05 21:09:48 +02007056use-server <server> if <condition>
7057use-server <server> unless <condition>
7058 Only use a specific server if/unless an ACL-based condition is matched.
7059 May be used in sections : defaults | frontend | listen | backend
7060 no | no | yes | yes
7061 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007062 <server> is the name of a valid server in the same backend section.
Willy Tarreau4a5cade2012-04-05 21:09:48 +02007063
7064 <condition> is a condition composed of ACLs, as described in section 7.
7065
7066 By default, connections which arrive to a backend are load-balanced across
7067 the available servers according to the configured algorithm, unless a
7068 persistence mechanism such as a cookie is used and found in the request.
7069
7070 Sometimes it is desirable to forward a particular request to a specific
7071 server without having to declare a dedicated backend for this server. This
7072 can be achieved using the "use-server" rules. These rules are evaluated after
7073 the "redirect" rules and before evaluating cookies, and they have precedence
7074 on them. There may be as many "use-server" rules as desired. All of these
7075 rules are evaluated in their declaration order, and the first one which
7076 matches will assign the server.
7077
7078 If a rule designates a server which is down, and "option persist" is not used
7079 and no force-persist rule was validated, it is ignored and evaluation goes on
7080 with the next rules until one matches.
7081
7082 In the first form, the server will be used if the condition is met. In the
7083 second form, the server will be used if the condition is not met. If no
7084 condition is valid, the processing continues and the server will be assigned
7085 according to other persistence mechanisms.
7086
7087 Note that even if a rule is matched, cookie processing is still performed but
7088 does not assign the server. This allows prefixed cookies to have their prefix
7089 stripped.
7090
7091 The "use-server" statement works both in HTTP and TCP mode. This makes it
7092 suitable for use with content-based inspection. For instance, a server could
7093 be selected in a farm according to the TLS SNI field. And if these servers
7094 have their weight set to zero, they will not be used for other traffic.
7095
7096 Example :
7097 # intercept incoming TLS requests based on the SNI field
7098 use-server www if { req_ssl_sni -i www.example.com }
7099 server www 192.168.0.1:443 weight 0
7100 use-server mail if { req_ssl_sni -i mail.example.com }
7101 server mail 192.168.0.1:587 weight 0
7102 use-server imap if { req_ssl_sni -i imap.example.com }
7103 server mail 192.168.0.1:993 weight 0
7104 # all the rest is forwarded to this server
7105 server default 192.168.0.2:443 check
7106
7107 See also: "use_backend", serction 5 about server and section 7 about ACLs.
7108
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007109
71105. Bind and Server options
7111--------------------------
7112
7113The "bind", "server" and "default-server" keywords support a number of settings
7114depending on some build options and on the system HAProxy was built on. These
7115settings generally each consist in one word sometimes followed by a value,
7116written on the same line as the "bind" or "server" line. All these options are
7117described in this section.
7118
7119
71205.1. Bind options
7121-----------------
7122
7123The "bind" keyword supports a certain number of settings which are all passed
7124as arguments on the same line. The order in which those arguments appear makes
7125no importance, provided that they appear after the bind address. All of these
7126parameters are optional. Some of them consist in a single words (booleans),
7127while other ones expect a value after them. In this case, the value must be
7128provided immediately after the setting name.
7129
7130The currently supported settings are the following ones.
7131
7132accept-proxy
7133 Enforces the use of the PROXY protocol over any connection accepted by any of
7134 the sockets declared on the same line. The PROXY protocol dictates the layer
7135 3/4 addresses of the incoming connection to be used everywhere an address is
7136 used, with the only exception of "tcp-request connection" rules which will
7137 only see the real connection address. Logs will reflect the addresses
7138 indicated in the protocol, unless it is violated, in which case the real
7139 address will still be used. This keyword combined with support from external
7140 components can be used as an efficient and reliable alternative to the
7141 X-Forwarded-For mechanism which is not always reliable and not even always
7142 usable.
7143
7144backlog <backlog>
7145 Sets the socket's backlog to this value. If unspecified, the frontend's
7146 backlog is used instead, which generally defaults to the maxconn value.
7147
Emeric Brun7fb34422012-09-28 15:26:15 +02007148ecdhe <named curve>
7149 This setting is only available when support for OpenSSL was built in. It sets
Emeric Brun6924ef82013-03-06 14:08:53 +01007150 the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default,
7151 used named curve is prime256v1.
Emeric Brun7fb34422012-09-28 15:26:15 +02007152
Emeric Brunfd33a262012-10-11 16:28:27 +02007153ca-file <cafile>
Emeric Brun1a073b42012-09-28 17:07:34 +02007154 This setting is only available when support for OpenSSL was built in. It
7155 designates a PEM file from which to load CA certificates used to verify
7156 client's certificate.
7157
Emeric Brunb6dc9342012-09-28 17:55:37 +02007158ca-ignore-err [all|<errorID>,...]
7159 This setting is only available when support for OpenSSL was built in.
7160 Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
7161 If set to 'all', all errors are ignored. SSL handshake is not aborted if an
7162 error is ignored.
7163
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007164ciphers <ciphers>
7165 This setting is only available when support for OpenSSL was built in. It sets
7166 the string describing the list of cipher algorithms ("cipher suite") that are
7167 negociated during the SSL/TLS handshake. The format of the string is defined
7168 in "man 1 ciphers" from OpenSSL man pages, and can be for instance a string
7169 such as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes).
7170
Emeric Brunfd33a262012-10-11 16:28:27 +02007171crl-file <crlfile>
Emeric Brun1a073b42012-09-28 17:07:34 +02007172 This setting is only available when support for OpenSSL was built in. It
7173 designates a PEM file from which to load certificate revocation list used
7174 to verify client's certificate.
7175
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007176crt <cert>
Alex Davies0fbf0162013-03-02 16:04:50 +00007177 This setting is only available when support for OpenSSL was built in. It
7178 designates a PEM file containing both the required certificates and any
7179 associated private keys. This file can be built by concatenating multiple
7180 PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA
7181 requires an intermediate certificate, this can also be concatenated into this
7182 file.
7183
7184 If the OpenSSL used supports Diffie-Hellman, parameters present in this file
7185 are loaded.
7186
7187 If a directory name is used instead of a PEM file, then all files found in
7188 that directory will be loaded. This directive may be specified multiple times
7189 in order to load certificates from multiple files or directories. The
7190 certificates will be presented to clients who provide a valid TLS Server Name
7191 Indication field matching one of their CN or alt subjects. Wildcards are
7192 supported, where a wildcard character '*' is used instead of the first
7193 hostname component (eg: *.example.org matches www.example.org but not
7194 www.sub.example.org).
7195
7196 If no SNI is provided by the client or if the SSL library does not support
7197 TLS extensions, or if the client provides an SNI hostname which does not
7198 match any certificate, then the first loaded certificate will be presented.
7199 This means that when loading certificates from a directory, it is highly
7200 recommended to load the default one first as a file.
7201
Emeric Brune032bfa2012-09-28 13:01:45 +02007202 Note that the same cert may be loaded multiple times without side effects.
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007203
Alex Davies0fbf0162013-03-02 16:04:50 +00007204 Some CAs (such as Godaddy) offer a drop down list of server types that do not
7205 include HAProxy when obtaining a certificate. If this happens be sure to
7206 choose a webserver that the CA believes requires a intermediate CA (for
7207 Godaddy, selection Apache Tomcat will get the correct bundle, but many
7208 others, e.g. nginx, result in a wrong bundle that will not work for some
7209 clients).
7210
Emeric Brunb6dc9342012-09-28 17:55:37 +02007211crt-ignore-err <errors>
Alex Davies0fbf0162013-03-02 16:04:50 +00007212 This setting is only available when support for OpenSSL was built in. Sets a
7213 comma separated list of errorIDs to ignore during verify at depth == 0. If
7214 set to 'all', all errors are ignored. SSL handshake is not abored if an error
7215 is ignored.
Emeric Brunb6dc9342012-09-28 17:55:37 +02007216
Emmanuel Hocdetfe616562013-01-22 15:31:15 +01007217crt-list <file>
7218 This setting is only available when support for OpenSSL was built in. It
Willy Tarreauad1731d2013-04-02 17:35:58 +02007219 designates a list of PEM file with an optional SNI filter per certificate,
7220 with the following format for each line :
Emmanuel Hocdetfe616562013-01-22 15:31:15 +01007221
Willy Tarreauad1731d2013-04-02 17:35:58 +02007222 <crtfile> [<snifilter>]
Emmanuel Hocdetfe616562013-01-22 15:31:15 +01007223
7224 Wildcards are supported in the SNI filter. The certificates will be presented
7225 to clients who provide a valid TLS Server Name Indication field matching one
7226 of SNI filter. If no SNI filter is specified the CN and alt subjects are
7227 used. This directive may be specified multiple times. See the "crt" option
7228 for more information. The default certificate is still needed to meet OpenSSL
7229 expectations. If it is not used, the strict-sni option may be used.
7230
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007231defer-accept
7232 Is an optional keyword which is supported only on certain Linux kernels. It
7233 states that a connection will only be accepted once some data arrive on it,
7234 or at worst after the first retransmit. This should be used only on protocols
7235 for which the client talks first (eg: HTTP). It can slightly improve
7236 performance by ensuring that most of the request is already available when
7237 the connection is accepted. On the other hand, it will not be able to detect
7238 connections which don't talk. It is important to note that this option is
7239 broken in all kernels up to 2.6.31, as the connection is never accepted until
7240 the client talks. This can cause issues with front firewalls which would see
7241 an established connection while the proxy will only see it in SYN_RECV. This
7242 option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
7243
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007244force-sslv3
7245 This option enforces use of SSLv3 only on SSL connections instanciated from
7246 this listener. SSLv3 is generally less expensive than the TLS counterparts
7247 for high connection rates. See also "force-tls*", "no-sslv3", and "no-tls*".
7248
7249force-tlsv10
7250 This option enforces use of TLSv1.0 only on SSL connections instanciated from
7251 this listener. See also "force-tls*", "no-sslv3", and "no-tls*".
7252
7253force-tlsv11
7254 This option enforces use of TLSv1.1 only on SSL connections instanciated from
7255 this listener. See also "force-tls*", "no-sslv3", and "no-tls*".
7256
7257force-tlsv12
7258 This option enforces use of TLSv1.2 only on SSL connections instanciated from
7259 this listener. See also "force-tls*", "no-sslv3", and "no-tls*".
7260
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007261gid <gid>
7262 Sets the group of the UNIX sockets to the designated system gid. It can also
7263 be set by default in the global section's "unix-bind" statement. Note that
7264 some platforms simply ignore this. This setting is equivalent to the "group"
7265 setting except that the group ID is used instead of its name. This setting is
7266 ignored by non UNIX sockets.
7267
7268group <group>
7269 Sets the group of the UNIX sockets to the designated system group. It can
7270 also be set by default in the global section's "unix-bind" statement. Note
7271 that some platforms simply ignore this. This setting is equivalent to the
7272 "gid" setting except that the group name is used instead of its gid. This
7273 setting is ignored by non UNIX sockets.
7274
7275id <id>
7276 Fixes the socket ID. By default, socket IDs are automatically assigned, but
7277 sometimes it is more convenient to fix them to ease monitoring. This value
7278 must be strictly positive and unique within the listener/frontend. This
7279 option can only be used when defining only a single socket.
7280
7281interface <interface>
Lukas Tribusfce2e962013-02-12 22:13:19 +01007282 Restricts the socket to a specific interface. When specified, only packets
7283 received from that particular interface are processed by the socket. This is
7284 currently only supported on Linux. The interface must be a primary system
7285 interface, not an aliased interface. It is also possible to bind multiple
7286 frontends to the same address if they are bound to different interfaces. Note
7287 that binding to a network interface requires root privileges. This parameter
7288 is only compatible with TCPv4/TCPv6 sockets.
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007289
Willy Tarreauabb175f2012-09-24 12:43:26 +02007290level <level>
7291 This setting is used with the stats sockets only to restrict the nature of
7292 the commands that can be issued on the socket. It is ignored by other
7293 sockets. <level> can be one of :
7294 - "user" is the least privileged level ; only non-sensitive stats can be
7295 read, and no change is allowed. It would make sense on systems where it
7296 is not easy to restrict access to the socket.
7297 - "operator" is the default level and fits most common uses. All data can
7298 be read, and only non-sensitive changes are permitted (eg: clear max
7299 counters).
7300 - "admin" should be used with care, as everything is permitted (eg: clear
7301 all counters).
7302
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007303maxconn <maxconn>
7304 Limits the sockets to this number of concurrent connections. Extraneous
7305 connections will remain in the system's backlog until a connection is
7306 released. If unspecified, the limit will be the same as the frontend's
7307 maxconn. Note that in case of port ranges or multiple addresses, the same
7308 value will be applied to each socket. This setting enables different
7309 limitations on expensive sockets, for instance SSL entries which may easily
7310 eat all memory.
7311
7312mode <mode>
7313 Sets the octal mode used to define access permissions on the UNIX socket. It
7314 can also be set by default in the global section's "unix-bind" statement.
7315 Note that some platforms simply ignore this. This setting is ignored by non
7316 UNIX sockets.
7317
7318mss <maxseg>
7319 Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming
7320 connections. This can be used to force a lower MSS for certain specific
7321 ports, for instance for connections passing through a VPN. Note that this
7322 relies on a kernel feature which is theoretically supported under Linux but
7323 was buggy in all versions prior to 2.6.28. It may or may not work on other
7324 operating systems. It may also not change the advertised value but change the
7325 effective size of outgoing segments. The commonly advertised value for TCPv4
7326 over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is
7327 positive, it will be used as the advertised MSS. If it is negative, it will
7328 indicate by how much to reduce the incoming connection's advertised MSS for
7329 outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.
7330
7331name <name>
7332 Sets an optional name for these sockets, which will be reported on the stats
7333 page.
7334
7335nice <nice>
7336 Sets the 'niceness' of connections initiated from the socket. Value must be
7337 in the range -1024..1024 inclusive, and defaults to zero. Positive values
7338 means that such connections are more friendly to others and easily offer
7339 their place in the scheduler. On the opposite, negative values mean that
7340 connections want to run with a higher priority than others. The difference
7341 only happens under high loads when the system is close to saturation.
7342 Negative values are appropriate for low-latency or administration services,
7343 and high values are generally recommended for CPU intensive tasks such as SSL
7344 processing or bulk transfers which are less sensible to latency. For example,
7345 it may make sense to use a positive value for an SMTP socket and a negative
7346 one for an RDP socket.
7347
Emeric Brun9b3009b2012-10-05 11:55:06 +02007348no-sslv3
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007349 This setting is only available when support for OpenSSL was built in. It
7350 disables support for SSLv3 on any sockets instanciated from the listener when
7351 SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007352 be enabled using any configuration option. See also "force-tls*",
7353 and "force-sslv3".
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007354
Emeric Brun90ad8722012-10-02 14:00:59 +02007355no-tls-tickets
7356 This setting is only available when support for OpenSSL was built in. It
7357 disables the stateless session resumption (RFC 5077 TLS Ticket
7358 extension) and force to use stateful session resumption. Stateless
7359 session resumption is more expensive in CPU usage.
7360
Emeric Brun9b3009b2012-10-05 11:55:06 +02007361no-tlsv10
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007362 This setting is only available when support for OpenSSL was built in. It
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007363 disables support for TLSv1.0 on any sockets instanciated from the listener
7364 when SSL is supported. Note that SSLv2 is forced disabled in the code and
7365 cannot be enabled using any configuration option. See also "force-tls*",
7366 and "force-sslv3".
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007367
Emeric Brun9b3009b2012-10-05 11:55:06 +02007368no-tlsv11
Emeric Brunf5da4932012-09-28 19:42:54 +02007369 This setting is only available when support for OpenSSL was built in. It
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007370 disables support for TLSv1.1 on any sockets instanciated from the listener
7371 when SSL is supported. Note that SSLv2 is forced disabled in the code and
7372 cannot be enabled using any configuration option. See also "force-tls*",
7373 and "force-sslv3".
Emeric Brunf5da4932012-09-28 19:42:54 +02007374
Emeric Brun9b3009b2012-10-05 11:55:06 +02007375no-tlsv12
Emeric Brunf5da4932012-09-28 19:42:54 +02007376 This setting is only available when support for OpenSSL was built in. It
Emeric Brun2cb7ae52012-10-05 14:14:21 +02007377 disables support for TLSv1.2 on any sockets instanciated from the listener
7378 when SSL is supported. Note that SSLv2 is forced disabled in the code and
7379 cannot be enabled using any configuration option. See also "force-tls*",
7380 and "force-sslv3".
Emeric Brunf5da4932012-09-28 19:42:54 +02007381
Willy Tarreau6c9a3d52012-10-18 18:57:14 +02007382npn <protocols>
7383 This enables the NPN TLS extension and advertises the specified protocol list
7384 as supported on top of NPN. The protocol list consists in a comma-delimited
7385 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
7386 This requires that the SSL library is build with support for TLS extensions
7387 enabled (check with haproxy -vv).
7388
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007389ssl
7390 This setting is only available when support for OpenSSL was built in. It
7391 enables SSL deciphering on connections instanciated from this listener. A
7392 certificate is necessary (see "crt" above). All contents in the buffers will
7393 appear in clear text, so that ACLs and HTTP processing will only have access
7394 to deciphered contents.
7395
Emmanuel Hocdet65623372013-01-24 17:17:15 +01007396strict-sni
7397 This setting is only available when support for OpenSSL was built in. The
7398 SSL/TLS negotiation is allow only if the client provided an SNI which match
7399 a certificate. The default certificate is not used.
7400 See the "crt" option for more information.
7401
Willy Tarreau1c862c52012-10-05 16:21:00 +02007402tfo
Lukas Tribus0defb902013-02-13 23:35:39 +01007403 Is an optional keyword which is supported only on Linux kernels >= 3.7. It
Willy Tarreau1c862c52012-10-05 16:21:00 +02007404 enables TCP Fast Open on the listening socket, which means that clients which
7405 support this feature will be able to send a request and receive a response
7406 during the 3-way handshake starting from second connection, thus saving one
7407 round-trip after the first connection. This only makes sense with protocols
7408 that use high connection rates and where each round trip matters. This can
7409 possibly cause issues with many firewalls which do not accept data on SYN
7410 packets, so this option should only be enabled once well tested. This option
Lukas Tribus0999f762013-04-02 16:43:24 +02007411 is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may
7412 need to build HAProxy with USE_TFO=1 if your libc doesn't define
7413 TCP_FASTOPEN.
Willy Tarreau1c862c52012-10-05 16:21:00 +02007414
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007415transparent
7416 Is an optional keyword which is supported only on certain Linux kernels. It
7417 indicates that the addresses will be bound even if they do not belong to the
7418 local machine, and that packets targeting any of these addresses will be
7419 intercepted just as if the addresses were locally configured. This normally
7420 requires that IP forwarding is enabled. Caution! do not use this with the
7421 default address '*', as it would redirect any traffic for the specified port.
7422 This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1.
7423 This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on
7424 kernel version. Some distribution kernels include backports of the feature,
7425 so check for support with your vendor.
7426
Willy Tarreau77e3af92012-11-24 15:07:23 +01007427v4v6
7428 Is an optional keyword which is supported only on most recent systems
7429 including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4
7430 and IPv6 when it uses the default address. Doing so is sometimes necessary
7431 on systems which bind to IPv6 only by default. It has no effect on non-IPv6
7432 sockets, and is overriden by the "v6only" option.
7433
Willy Tarreau9b6700f2012-11-24 11:55:28 +01007434v6only
7435 Is an optional keyword which is supported only on most recent systems
7436 including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only
7437 when it uses the default address. Doing so is sometimes preferred to doing it
Willy Tarreau77e3af92012-11-24 15:07:23 +01007438 system-wide as it is per-listener. It has no effect on non-IPv6 sockets and
7439 has precedence over the "v4v6" option.
Willy Tarreau9b6700f2012-11-24 11:55:28 +01007440
Willy Tarreaub6205fd2012-09-24 12:27:33 +02007441uid <uid>
7442 Sets the owner of the UNIX sockets to the designated system uid. It can also
7443 be set by default in the global section's "unix-bind" statement. Note that
7444 some platforms simply ignore this. This setting is equivalent to the "user"
7445 setting except that the user numeric ID is used instead of its name. This
7446 setting is ignored by non UNIX sockets.
7447
7448user <user>
7449 Sets the owner of the UNIX sockets to the designated system user. It can also
7450 be set by default in the global section's "unix-bind" statement. Note that
7451 some platforms simply ignore this. This setting is equivalent to the "uid"
7452 setting except that the user name is used instead of its uid. This setting is
7453 ignored by non UNIX sockets.
7454
Emeric Brun1a073b42012-09-28 17:07:34 +02007455verify [none|optional|required]
7456 This setting is only available when support for OpenSSL was built in. If set
7457 to 'none', client certificate is not requested. This is the default. In other
7458 cases, a client certificate is requested. If the client does not provide a
7459 certificate after the request and if 'verify' is set to 'required', then the
7460 handshake is aborted, while it would have succeeded if set to 'optional'. The
Emeric Brunfd33a262012-10-11 16:28:27 +02007461 certificate provided by the client is always verified using CAs from
7462 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
7463 is aborted, regardless of the 'verify' option, unless the error code exactly
7464 matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.
Willy Tarreau4a5cade2012-04-05 21:09:48 +02007465
Willy Tarreaub6205fd2012-09-24 12:27:33 +020074665.2. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +01007467------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02007468
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01007469The "server" and "default-server" keywords support a certain number of settings
7470which are all passed as arguments on the server line. The order in which those
7471arguments appear does not count, and they are all optional. Some of those
7472settings are single words (booleans) while others expect one or several values
7473after them. In this case, the values must immediately follow the setting name.
7474Except default-server, all those settings must be specified after the server's
7475address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +02007476
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007477 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01007478 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +02007479
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007480The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +01007481
Willy Tarreauceb4ac92012-04-28 00:41:46 +02007482addr <ipv4|ipv6>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007483 Using the "addr" parameter, it becomes possible to use a different IP address
7484 to send health-checks. On some servers, it may be desirable to dedicate an IP
7485 address to specific component able to perform complex tests which are more
7486 suitable to health-checks than the application. This parameter is ignored if
7487 the "check" parameter is not set. See also the "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007488
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007489 Supported in default-server: No
7490
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007491backup
7492 When "backup" is present on a server line, the server is only used in load
7493 balancing when all other non-backup servers are unavailable. Requests coming
7494 with a persistence cookie referencing the server will always be served
7495 though. By default, only the first operational backup server is used, unless
7496 the "allbackups" option is set in the backend. See also the "allbackups"
7497 option.
Willy Tarreau6a06a402007-07-15 20:15:28 +02007498
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007499 Supported in default-server: No
7500
Emeric Brunef42d922012-10-11 16:11:36 +02007501ca-file <cafile>
7502 This setting is only available when support for OpenSSL was built in. It
7503 designates a PEM file from which to load CA certificates used to verify
7504 server's certificate.
7505
7506 Supported in default-server: No
7507
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007508check
7509 This option enables health checks on the server. By default, a server is
Patrick Mézardb7aeec62012-01-22 16:01:22 +01007510 always considered available. If "check" is set, the server is available when
7511 accepting periodic TCP connections, to ensure that it is really able to serve
7512 requests. The default address and port to send the tests to are those of the
7513 server, and the default source is the same as the one defined in the
7514 backend. It is possible to change the address using the "addr" parameter, the
7515 port using the "port" parameter, the source address using the "source"
7516 address, and the interval and timers using the "inter", "rise" and "fall"
Simon Hormana2b9dad2013-02-12 10:45:54 +09007517 parameters. The request method is define in the backend using the
7518 "httpchk", "lb-agent-chk", "smtpchk", "mysql-check", "pgsql-check" and
7519 "ssl-hello-chk" options. Please refer to those options and parameters for
7520 more information.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007521
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007522 Supported in default-server: No
7523
Willy Tarreau6c16adc2012-10-05 00:04:16 +02007524check-send-proxy
7525 This option forces emission of a PROXY protocol line with outgoing health
7526 checks, regardless of whether the server uses send-proxy or not for the
7527 normal traffic. By default, the PROXY protocol is enabled for health checks
7528 if it is already enabled for normal traffic and if no "port" nor "addr"
7529 directive is present. However, if such a directive is present, the
7530 "check-send-proxy" option needs to be used to force the use of the
7531 protocol. See also the "send-proxy" option for more information.
7532
7533 Supported in default-server: No
7534
Willy Tarreau763a95b2012-10-04 23:15:39 +02007535check-ssl
7536 This option forces encryption of all health checks over SSL, regardless of
7537 whether the server uses SSL or not for the normal traffic. This is generally
7538 used when an explicit "port" or "addr" directive is specified and SSL health
7539 checks are not inherited. It is important to understand that this option
7540 inserts an SSL transport layer below the ckecks, so that a simple TCP connect
7541 check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
7542 common use is to send HTTPS checks by combining "httpchk" with SSL checks.
7543 All SSL settings are common to health checks and traffic (eg: ciphers).
7544 See the "ssl" option for more information.
7545
7546 Supported in default-server: No
7547
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007548ciphers <ciphers>
7549 This option sets the string describing the list of cipher algorithms that is
7550 is negociated during the SSL/TLS handshake with the server. The format of the
7551 string is defined in "man 1 ciphers". When SSL is used to communicate with
7552 servers on the local network, it is common to see a weaker set of algorithms
7553 than what is used over the internet. Doing so reduces CPU usage on both the
7554 server and haproxy while still keeping it compatible with deployed software.
7555 Some algorithms such as RC4-SHA1 are reasonably cheap. If no security at all
7556 is needed and just connectivity, using DES can be appropriate.
7557
Willy Tarreau763a95b2012-10-04 23:15:39 +02007558 Supported in default-server: No
7559
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007560cookie <value>
7561 The "cookie" parameter sets the cookie value assigned to the server to
7562 <value>. This value will be checked in incoming requests, and the first
7563 operational server possessing the same value will be selected. In return, in
7564 cookie insertion or rewrite modes, this value will be assigned to the cookie
7565 sent to the client. There is nothing wrong in having several servers sharing
7566 the same cookie value, and it is in fact somewhat common between normal and
7567 backup servers. See also the "cookie" keyword in backend section.
7568
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007569 Supported in default-server: No
7570
Emeric Brunef42d922012-10-11 16:11:36 +02007571crl-file <crlfile>
7572 This setting is only available when support for OpenSSL was built in. It
7573 designates a PEM file from which to load certificate revocation list used
7574 to verify server's certificate.
7575
7576 Supported in default-server: No
7577
Emeric Bruna7aa3092012-10-26 12:58:00 +02007578crt <cert>
7579 This setting is only available when support for OpenSSL was built in.
7580 It designates a PEM file from which to load both a certificate and the
7581 associated private key. This file can be built by concatenating both PEM
7582 files into one. This certificate will be sent if the server send a client
7583 certificate request.
7584
7585 Supported in default-server: No
7586
Willy Tarreau96839092010-03-29 10:02:24 +02007587disabled
7588 The "disabled" keyword starts the server in the "disabled" state. That means
7589 that it is marked down in maintenance mode, and no connection other than the
7590 ones allowed by persist mode will reach it. It is very well suited to setup
7591 new servers, because normal traffic will never reach them, while it is still
7592 possible to test the service by making use of the force-persist mechanism.
7593
7594 Supported in default-server: No
7595
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007596error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +01007597 If health observing is enabled, the "error-limit" parameter specifies the
7598 number of consecutive errors that triggers event selected by the "on-error"
7599 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007600
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007601 Supported in default-server: Yes
7602
7603 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007604
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007605fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007606 The "fall" parameter states that a server will be considered as dead after
7607 <count> consecutive unsuccessful health checks. This value defaults to 3 if
7608 unspecified. See also the "check", "inter" and "rise" parameters.
7609
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007610 Supported in default-server: Yes
7611
Emeric Brun8694b9a2012-10-05 14:39:07 +02007612force-sslv3
7613 This option enforces use of SSLv3 only when SSL is used to communicate with
7614 the server. SSLv3 is generally less expensive than the TLS counterparts for
7615 high connection rates. See also "no-tlsv*", "no-sslv3".
7616
7617 Supported in default-server: No
7618
7619force-tlsv10
7620 This option enforces use of TLSv1.0 only when SSL is used to communicate with
7621 the server. See also "no-tlsv*", "no-sslv3".
7622
7623 Supported in default-server: No
7624
7625force-tlsv11
7626 This option enforces use of TLSv1.1 only when SSL is used to communicate with
7627 the server. See also "no-tlsv*", "no-sslv3".
7628
7629 Supported in default-server: No
7630
7631force-tlsv12
7632 This option enforces use of TLSv1.2 only when SSL is used to communicate with
7633 the server. See also "no-tlsv*", "no-sslv3".
7634
7635 Supported in default-server: No
7636
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007637id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02007638 Set a persistent ID for the server. This ID must be positive and unique for
7639 the proxy. An unused ID will automatically be assigned if unset. The first
7640 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007641
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007642 Supported in default-server: No
7643
7644inter <delay>
7645fastinter <delay>
7646downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007647 The "inter" parameter sets the interval between two consecutive health checks
7648 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
7649 It is also possible to use "fastinter" and "downinter" to optimize delays
7650 between checks depending on the server state :
7651
7652 Server state | Interval used
7653 ---------------------------------+-----------------------------------------
7654 UP 100% (non-transitional) | "inter"
7655 ---------------------------------+-----------------------------------------
7656 Transitionally UP (going down), |
7657 Transitionally DOWN (going up), | "fastinter" if set, "inter" otherwise.
7658 or yet unchecked. |
7659 ---------------------------------+-----------------------------------------
7660 DOWN 100% (non-transitional) | "downinter" if set, "inter" otherwise.
7661 ---------------------------------+-----------------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +01007662
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007663 Just as with every other time-based parameter, they can be entered in any
7664 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
7665 serves as a timeout for health checks sent to servers if "timeout check" is
7666 not set. In order to reduce "resonance" effects when multiple servers are
7667 hosted on the same hardware, the health-checks of all servers are started
7668 with a small time offset between them. It is also possible to add some random
7669 noise in the health checks interval using the global "spread-checks"
7670 keyword. This makes sense for instance when a lot of backends use the same
7671 servers.
7672
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007673 Supported in default-server: Yes
7674
7675maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007676 The "maxconn" parameter specifies the maximal number of concurrent
7677 connections that will be sent to this server. If the number of incoming
7678 concurrent requests goes higher than this value, they will be queued, waiting
7679 for a connection to be released. This parameter is very important as it can
7680 save fragile servers from going down under extreme loads. If a "minconn"
7681 parameter is specified, the limit becomes dynamic. The default value is "0"
7682 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
7683 the backend's "fullconn" keyword.
7684
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007685 Supported in default-server: Yes
7686
7687maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007688 The "maxqueue" parameter specifies the maximal number of connections which
7689 will wait in the queue for this server. If this limit is reached, next
7690 requests will be redispatched to other servers instead of indefinitely
7691 waiting to be served. This will break persistence but may allow people to
7692 quickly re-log in when the server they try to connect to is dying. The
7693 default value is "0" which means the queue is unlimited. See also the
7694 "maxconn" and "minconn" parameters.
7695
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007696 Supported in default-server: Yes
7697
7698minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007699 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
7700 limit following the backend's load. The server will always accept at least
7701 <minconn> connections, never more than <maxconn>, and the limit will be on
7702 the ramp between both values when the backend has less than <fullconn>
7703 concurrent connections. This makes it possible to limit the load on the
7704 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007705 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007706 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007707
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007708 Supported in default-server: Yes
7709
Emeric Brun9b3009b2012-10-05 11:55:06 +02007710no-sslv3
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007711 This option disables support for SSLv3 when SSL is used to communicate with
7712 the server. Note that SSLv2 is disabled in the code and cannot be enabled
Emeric Brun8694b9a2012-10-05 14:39:07 +02007713 using any configuration option. See also "force-sslv3", "force-tlsv*".
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007714
Willy Tarreau763a95b2012-10-04 23:15:39 +02007715 Supported in default-server: No
7716
Emeric Brunf9c5c472012-10-11 15:28:34 +02007717no-tls-tickets
7718 This setting is only available when support for OpenSSL was built in. It
7719 disables the stateless session resumption (RFC 5077 TLS Ticket
7720 extension) and force to use stateful session resumption. Stateless
7721 session resumption is more expensive in CPU usage for servers.
7722
7723 Supported in default-server: No
7724
Emeric Brun9b3009b2012-10-05 11:55:06 +02007725no-tlsv10
Emeric Brun8694b9a2012-10-05 14:39:07 +02007726 This option disables support for TLSv1.0 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +02007727 the server. Note that SSLv2 is disabled in the code and cannot be enabled
7728 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun8694b9a2012-10-05 14:39:07 +02007729 often makes sense to disable it when communicating with local servers. See
7730 also "force-sslv3", "force-tlsv*".
Emeric Brunf5da4932012-09-28 19:42:54 +02007731
Willy Tarreau763a95b2012-10-04 23:15:39 +02007732 Supported in default-server: No
7733
Emeric Brun9b3009b2012-10-05 11:55:06 +02007734no-tlsv11
Emeric Brun8694b9a2012-10-05 14:39:07 +02007735 This option disables support for TLSv1.1 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +02007736 the server. Note that SSLv2 is disabled in the code and cannot be enabled
7737 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun8694b9a2012-10-05 14:39:07 +02007738 often makes sense to disable it when communicating with local servers. See
7739 also "force-sslv3", "force-tlsv*".
Emeric Brunf5da4932012-09-28 19:42:54 +02007740
Willy Tarreau763a95b2012-10-04 23:15:39 +02007741 Supported in default-server: No
7742
Emeric Brun9b3009b2012-10-05 11:55:06 +02007743no-tlsv12
Emeric Brun8694b9a2012-10-05 14:39:07 +02007744 This option disables support for TLSv1.2 when SSL is used to communicate with
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007745 the server. Note that SSLv2 is disabled in the code and cannot be enabled
7746 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun8694b9a2012-10-05 14:39:07 +02007747 often makes sense to disable it when communicating with local servers. See
7748 also "force-sslv3", "force-tlsv*".
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007749
Willy Tarreau763a95b2012-10-04 23:15:39 +02007750 Supported in default-server: No
7751
Simon Hormanfa461682011-06-25 09:39:49 +09007752non-stick
7753 Never add connections allocated to this sever to a stick-table.
7754 This may be used in conjunction with backup to ensure that
7755 stick-table persistence is disabled for backup servers.
7756
Willy Tarreau763a95b2012-10-04 23:15:39 +02007757 Supported in default-server: No
7758
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007759observe <mode>
7760 This option enables health adjusting based on observing communication with
7761 the server. By default this functionality is disabled and enabling it also
7762 requires to enable health checks. There are two supported modes: "layer4" and
7763 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
7764 significant. In layer7, which is only allowed for http proxies, responses
7765 received from server are verified, like valid/wrong http code, unparsable
Willy Tarreau150d1462012-03-10 08:19:02 +01007766 headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007767
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007768 Supported in default-server: No
7769
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007770 See also the "check", "on-error" and "error-limit".
7771
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007772on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007773 Select what should happen when enough consecutive errors are detected.
7774 Currently, four modes are available:
7775 - fastinter: force fastinter
7776 - fail-check: simulate a failed check, also forces fastinter (default)
7777 - sudden-death: simulate a pre-fatal failed health check, one more failed
7778 check will mark a server down, forces fastinter
7779 - mark-down: mark the server immediately down and force fastinter
7780
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007781 Supported in default-server: Yes
7782
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +01007783 See also the "check", "observe" and "error-limit".
7784
Simon Hormane0d1bfb2011-06-21 14:34:58 +09007785on-marked-down <action>
7786 Modify what occurs when a server is marked down.
7787 Currently one action is available:
Justin Karnegeseb2c24a2012-05-24 15:28:52 -07007788 - shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
7789 all connections to the server are immediately terminated when the server
7790 goes down. It might be used if the health check detects more complex cases
7791 than a simple connection status, and long timeouts would cause the service
7792 to remain unresponsive for too long a time. For instance, a health check
7793 might detect that a database is stuck and that there's no chance to reuse
7794 existing connections anymore. Connections killed this way are logged with
7795 a 'D' termination code (for "Down").
Simon Hormane0d1bfb2011-06-21 14:34:58 +09007796
7797 Actions are disabled by default
7798
7799 Supported in default-server: Yes
7800
Justin Karnegeseb2c24a2012-05-24 15:28:52 -07007801on-marked-up <action>
7802 Modify what occurs when a server is marked up.
7803 Currently one action is available:
7804 - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
7805 done only if the server is not in backup state and if it is not disabled
7806 (it must have an effective weight > 0). This can be used sometimes to force
7807 an active server to take all the traffic back after recovery when dealing
7808 with long sessions (eg: LDAP, SQL, ...). Doing this can cause more trouble
7809 than it tries to solve (eg: incomplete transactions), so use this feature
7810 with extreme care. Sessions killed because a server comes up are logged
7811 with an 'U' termination code (for "Up").
7812
7813 Actions are disabled by default
7814
7815 Supported in default-server: Yes
7816
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007817port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007818 Using the "port" parameter, it becomes possible to use a different port to
7819 send health-checks. On some servers, it may be desirable to dedicate a port
7820 to a specific component able to perform complex tests which are more suitable
7821 to health-checks than the application. It is common to run a simple script in
7822 inetd for instance. This parameter is ignored if the "check" parameter is not
7823 set. See also the "addr" parameter.
7824
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007825 Supported in default-server: Yes
7826
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007827redir <prefix>
7828 The "redir" parameter enables the redirection mode for all GET and HEAD
7829 requests addressing this server. This means that instead of having HAProxy
7830 forward the request to the server, it will send an "HTTP 302" response with
7831 the "Location" header composed of this prefix immediately followed by the
7832 requested URI beginning at the leading '/' of the path component. That means
7833 that no trailing slash should be used after <prefix>. All invalid requests
7834 will be rejected, and all non-GET or HEAD requests will be normally served by
7835 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007836 mangling nor cookie insertion is possible in the response. However, cookies in
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007837 requests are still analysed, making this solution completely usable to direct
7838 users to a remote location in case of local disaster. Main use consists in
7839 increasing bandwidth for static servers by having the clients directly
7840 connect to them. Note: never use a relative location here, it would cause a
7841 loop between the client and HAProxy!
7842
7843 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
7844
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007845 Supported in default-server: No
7846
7847rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007848 The "rise" parameter states that a server will be considered as operational
7849 after <count> consecutive successful health checks. This value defaults to 2
7850 if unspecified. See also the "check", "inter" and "fall" parameters.
7851
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007852 Supported in default-server: Yes
7853
Willy Tarreau5ab04ec2011-03-20 10:32:26 +01007854send-proxy
7855 The "send-proxy" parameter enforces use of the PROXY protocol over any
7856 connection established to this server. The PROXY protocol informs the other
7857 end about the layer 3/4 addresses of the incoming connection, so that it can
7858 know the client's address or the public address it accessed to, whatever the
7859 upper layer protocol. For connections accepted by an "accept-proxy" listener,
7860 the advertised address will be used. Only TCPv4 and TCPv6 address families
7861 are supported. Other families such as Unix sockets, will report an UNKNOWN
7862 family. Servers using this option can fully be chained to another instance of
7863 haproxy listening with an "accept-proxy" setting. This setting must not be
Willy Tarreau6c16adc2012-10-05 00:04:16 +02007864 used if the server isn't aware of the protocol. When health checks are sent
7865 to the server, the PROXY protocol is automatically used when this option is
7866 set, unless there is an explicit "port" or "addr" directive, in which case an
7867 explicit "check-send-proxy" directive would also be needed to use the PROXY
7868 protocol. See also the "accept-proxy" option of the "bind" keyword.
Willy Tarreau5ab04ec2011-03-20 10:32:26 +01007869
7870 Supported in default-server: No
7871
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007872slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007873 The "slowstart" parameter for a server accepts a value in milliseconds which
7874 indicates after how long a server which has just come back up will run at
7875 full speed. Just as with every other time-based parameter, it can be entered
7876 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
7877 linearly from 0 to 100% during this time. The limitation applies to two
7878 parameters :
7879
7880 - maxconn: the number of connections accepted by the server will grow from 1
7881 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
7882
7883 - weight: when the backend uses a dynamic weighted algorithm, the weight
7884 grows linearly from 1 to 100%. In this case, the weight is updated at every
7885 health-check. For this reason, it is important that the "inter" parameter
7886 is smaller than the "slowstart", in order to maximize the number of steps.
7887
7888 The slowstart never applies when haproxy starts, otherwise it would cause
7889 trouble to running servers. It only applies when a server has been previously
7890 seen as failed.
7891
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007892 Supported in default-server: Yes
7893
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02007894source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02007895source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02007896source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007897 The "source" parameter sets the source address which will be used when
7898 connecting to the server. It follows the exact same parameters and principle
7899 as the backend "source" keyword, except that it only applies to the server
7900 referencing it. Please consult the "source" keyword for details.
7901
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02007902 Additionally, the "source" statement on a server line allows one to specify a
7903 source port range by indicating the lower and higher bounds delimited by a
7904 dash ('-'). Some operating systems might require a valid IP address when a
7905 source port range is specified. It is permitted to have the same IP/range for
7906 several servers. Doing so makes it possible to bypass the maximum of 64k
7907 total concurrent connections. The limit will then reach 64k connections per
7908 server.
7909
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007910 Supported in default-server: No
7911
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007912ssl
Willy Tarreau763a95b2012-10-04 23:15:39 +02007913 This option enables SSL ciphering on outgoing connections to the server. At
7914 the moment, server certificates are not checked, so this is prone to man in
7915 the middle attacks. The real intended use is to permit SSL communication
7916 with software which cannot work in other modes over networks that would
7917 otherwise be considered safe enough for clear text communications. When this
7918 option is used, health checks are automatically sent in SSL too unless there
7919 is a "port" or an "addr" directive indicating the check should be sent to a
7920 different location. See the "check-ssl" optino to force SSL health checks.
7921
7922 Supported in default-server: No
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02007923
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007924track [<proxy>/]<server>
7925 This option enables ability to set the current state of the server by
7926 tracking another one. Only a server with checks enabled can be tracked
7927 so it is not possible for example to track a server that tracks another
7928 one. If <proxy> is omitted the current one is used. If disable-on-404 is
7929 used, it has to be enabled on both proxies.
7930
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007931 Supported in default-server: No
7932
Emeric Brunef42d922012-10-11 16:11:36 +02007933verify [none|required]
7934 This setting is only available when support for OpenSSL was built in. If set
7935 to 'none', server certificate is not verified. This is the default. In the
7936 other case, The certificate provided by the server is verified using CAs from
7937 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
7938 is aborted.
7939
7940 Supported in default-server: No
7941
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007942weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007943 The "weight" parameter is used to adjust the server's weight relative to
7944 other servers. All servers will receive a load proportional to their weight
7945 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +02007946 load. The default weight is 1, and the maximal value is 256. A value of 0
7947 means the server will not participate in load-balancing but will still accept
7948 persistent connections. If this parameter is used to distribute the load
7949 according to server's capacity, it is recommended to start with values which
7950 can both grow and shrink, for instance between 10 and 100 to leave enough
7951 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007952
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +01007953 Supported in default-server: Yes
7954
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007955
79566. HTTP header manipulation
7957---------------------------
7958
7959In HTTP mode, it is possible to rewrite, add or delete some of the request and
7960response headers based on regular expressions. It is also possible to block a
7961request or a response if a particular header matches a regular expression,
7962which is enough to stop most elementary protocol attacks, and to protect
7963against information leak from the internal network. But there is a limitation
7964to this : since HAProxy's HTTP engine does not support keep-alive, only headers
7965passed during the first request of a TCP session will be seen. All subsequent
7966headers will be considered data only and not analyzed. Furthermore, HAProxy
7967never touches data contents, it stops analysis at the end of headers.
7968
Willy Tarreau816b9792009-09-15 21:25:21 +02007969There is an exception though. If HAProxy encounters an "Informational Response"
7970(status code 1xx), it is able to process all rsp* rules which can allow, deny,
7971rewrite or delete a header, but it will refuse to add a header to any such
7972messages as this is not HTTP-compliant. The reason for still processing headers
7973in such responses is to stop and/or fix any possible information leak which may
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007974happen, for instance because another downstream equipment would unconditionally
Willy Tarreau816b9792009-09-15 21:25:21 +02007975add a header, or if a server name appears there. When such messages are seen,
7976normal processing still occurs on the next non-informational messages.
7977
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007978This section covers common usage of the following keywords, described in detail
7979in section 4.2 :
7980
7981 - reqadd <string>
7982 - reqallow <search>
7983 - reqiallow <search>
7984 - reqdel <search>
7985 - reqidel <search>
7986 - reqdeny <search>
7987 - reqideny <search>
7988 - reqpass <search>
7989 - reqipass <search>
7990 - reqrep <search> <replace>
7991 - reqirep <search> <replace>
7992 - reqtarpit <search>
7993 - reqitarpit <search>
7994 - rspadd <string>
7995 - rspdel <search>
7996 - rspidel <search>
7997 - rspdeny <search>
7998 - rspideny <search>
7999 - rsprep <search> <replace>
8000 - rspirep <search> <replace>
8001
8002With all these keywords, the same conventions are used. The <search> parameter
8003is a POSIX extended regular expression (regex) which supports grouping through
8004parenthesis (without the backslash). Spaces and other delimiters must be
8005prefixed with a backslash ('\') to avoid confusion with a field delimiter.
8006Other characters may be prefixed with a backslash to change their meaning :
8007
8008 \t for a tab
8009 \r for a carriage return (CR)
8010 \n for a new line (LF)
8011 \ to mark a space and differentiate it from a delimiter
8012 \# to mark a sharp and differentiate it from a comment
8013 \\ to use a backslash in a regex
8014 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
8015 \xXX to write the ASCII hex code XX as in the C language
8016
8017The <replace> parameter contains the string to be used to replace the largest
8018portion of text matching the regex. It can make use of the special characters
8019above, and can reference a substring which is delimited by parenthesis in the
8020regex, by writing a backslash ('\') immediately followed by one digit from 0 to
80219 indicating the group position (0 designating the entire line). This practice
8022is very common to users of the "sed" program.
8023
8024The <string> parameter represents the string which will systematically be added
8025after the last header line. It can also use special character sequences above.
8026
8027Notes related to these keywords :
8028---------------------------------
8029 - these keywords are not always convenient to allow/deny based on header
8030 contents. It is strongly recommended to use ACLs with the "block" keyword
8031 instead, resulting in far more flexible and manageable rules.
8032
8033 - lines are always considered as a whole. It is not possible to reference
8034 a header name only or a value only. This is important because of the way
8035 headers are written (notably the number of spaces after the colon).
8036
8037 - the first line is always considered as a header, which makes it possible to
8038 rewrite or filter HTTP requests URIs or response codes, but in turn makes
8039 it harder to distinguish between headers and request line. The regex prefix
8040 ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix
8041 ^[^ \t:]*: matches any header name followed by a colon.
8042
8043 - for performances reasons, the number of characters added to a request or to
8044 a response is limited at build time to values between 1 and 4 kB. This
8045 should normally be far more than enough for most usages. If it is too short
8046 on occasional usages, it is possible to gain some space by removing some
8047 useless headers before adding new ones.
8048
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008049 - keywords beginning with "reqi" and "rspi" are the same as their counterpart
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008050 without the 'i' letter except that they ignore case when matching patterns.
8051
8052 - when a request passes through a frontend then a backend, all req* rules
8053 from the frontend will be evaluated, then all req* rules from the backend
8054 will be evaluated. The reverse path is applied to responses.
8055
8056 - req* statements are applied after "block" statements, so that "block" is
8057 always the first one, but before "use_backend" in order to permit rewriting
Willy Tarreaud72758d2010-01-12 10:42:19 +01008058 before switching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008059
8060
Willy Tarreaub937b7e2010-01-12 15:27:54 +010080617. Using ACLs and pattern extraction
8062------------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008063
8064The use of Access Control Lists (ACL) provides a flexible solution to perform
8065content switching and generally to take decisions based on content extracted
8066from the request, the response or any environmental status. The principle is
8067simple :
8068
8069 - define test criteria with sets of values
8070 - perform actions only if a set of tests is valid
8071
8072The actions generally consist in blocking the request, or selecting a backend.
8073
8074In order to define a test, the "acl" keyword is used. The syntax is :
8075
8076 acl <aclname> <criterion> [flags] [operator] <value> ...
8077
8078This creates a new ACL <aclname> or completes an existing one with new tests.
8079Those tests apply to the portion of request/response specified in <criterion>
8080and may be adjusted with optional flags [flags]. Some criteria also support
8081an operator which may be specified before the set of values. The values are
8082of the type supported by the criterion, and are separated by spaces.
8083
8084ACL names must be formed from upper and lower case letters, digits, '-' (dash),
8085'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
8086which means that "my_acl" and "My_Acl" are two different ACLs.
8087
8088There is no enforced limit to the number of ACLs. The unused ones do not affect
8089performance, they just consume a small amount of memory.
8090
8091The following ACL flags are currently supported :
8092
Willy Tarreau2b5285d2010-05-09 23:45:24 +02008093 -i : ignore case during matching of all subsequent patterns.
8094 -f : load patterns from a file.
Willy Tarreau6a06a402007-07-15 20:15:28 +02008095 -- : force end of flags. Useful when a string looks like one of the flags.
8096
Willy Tarreau2b5285d2010-05-09 23:45:24 +02008097The "-f" flag is special as it loads all of the lines it finds in the file
8098specified in argument and loads all of them before continuing. It is even
8099possible to pass multiple "-f" arguments if the patterns are to be loaded from
Willy Tarreau58215a02010-05-13 22:07:43 +02008100multiple files. Empty lines as well as lines beginning with a sharp ('#') will
8101be ignored. All leading spaces and tabs will be stripped. If it is absolutely
8102needed to insert a valid pattern beginning with a sharp, just prefix it with a
8103space so that it is not taken for a comment. Depending on the data type and
8104match method, haproxy may load the lines into a binary tree, allowing very fast
8105lookups. This is true for IPv4 and exact string matching. In this case,
8106duplicates will automatically be removed. Also, note that the "-i" flag applies
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008107to subsequent entries and not to entries loaded from files preceding it. For
Willy Tarreau58215a02010-05-13 22:07:43 +02008108instance :
Willy Tarreau2b5285d2010-05-09 23:45:24 +02008109
8110 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
8111
8112In this example, each line of "exact-ua.lst" will be exactly matched against
8113the "user-agent" header of the request. Then each line of "generic-ua" will be
8114case-insensitively matched. Then the word "test" will be insensitively matched
8115too.
8116
8117Note that right now it is difficult for the ACL parsers to report errors, so if
8118a file is unreadable or unparsable, the most you'll get is a parse error in the
8119ACL. Thus, file-based ACLs should only be produced by reliable processes.
8120
Willy Tarreau6a06a402007-07-15 20:15:28 +02008121Supported types of values are :
Willy Tarreau0ba27502007-12-24 16:55:16 +01008122
Willy Tarreau6a06a402007-07-15 20:15:28 +02008123 - integers or integer ranges
8124 - strings
8125 - regular expressions
8126 - IP addresses and networks
8127
8128
Willy Tarreauc57f0e22009-05-10 13:12:33 +020081297.1. Matching integers
8130----------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02008131
8132Matching integers is special in that ranges and operators are permitted. Note
8133that integer matching only applies to positive values. A range is a value
8134expressed with a lower and an upper bound separated with a colon, both of which
8135may be omitted.
8136
8137For instance, "1024:65535" is a valid range to represent a range of
8138unprivileged ports, and "1024:" would also work. "0:1023" is a valid
8139representation of privileged ports, and ":1023" would also work.
8140
Willy Tarreau62644772008-07-16 18:36:06 +02008141As a special case, some ACL functions support decimal numbers which are in fact
8142two integers separated by a dot. This is used with some version checks for
8143instance. All integer properties apply to those decimal numbers, including
8144ranges and operators.
8145
Willy Tarreau6a06a402007-07-15 20:15:28 +02008146For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +01008147operators with ranges does not make much sense and is strongly discouraged.
8148Similarly, it does not make much sense to perform order comparisons with a set
8149of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +02008150
Willy Tarreau0ba27502007-12-24 16:55:16 +01008151Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +02008152
8153 eq : true if the tested value equals at least one value
8154 ge : true if the tested value is greater than or equal to at least one value
8155 gt : true if the tested value is greater than at least one value
8156 le : true if the tested value is less than or equal to at least one value
8157 lt : true if the tested value is less than at least one value
8158
Willy Tarreau0ba27502007-12-24 16:55:16 +01008159For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +02008160
8161 acl negative-length hdr_val(content-length) lt 0
8162
Willy Tarreau62644772008-07-16 18:36:06 +02008163This one matches SSL versions between 3.0 and 3.1 (inclusive) :
8164
8165 acl sslv3 req_ssl_ver 3:3.1
8166
Willy Tarreau6a06a402007-07-15 20:15:28 +02008167
Willy Tarreauc57f0e22009-05-10 13:12:33 +020081687.2. Matching strings
8169---------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02008170
8171String matching applies to verbatim strings as they are passed, with the
8172exception of the backslash ("\") which makes it possible to escape some
8173characters such as the space. If the "-i" flag is passed before the first
8174string, then the matching will be performed ignoring the case. In order
8175to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +01008176before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02008177
8178
Willy Tarreauc57f0e22009-05-10 13:12:33 +020081797.3. Matching regular expressions (regexes)
8180-------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02008181
8182Just like with string matching, regex matching applies to verbatim strings as
8183they are passed, with the exception of the backslash ("\") which makes it
8184possible to escape some characters such as the space. If the "-i" flag is
8185passed before the first regex, then the matching will be performed ignoring
8186the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +01008187the "--" flag before the first string. Same principle applies of course to
8188match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +02008189
8190
Willy Tarreauceb4ac92012-04-28 00:41:46 +020081917.4. Matching IPv4 and IPv6 addresses
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008192----------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02008193
8194IPv4 addresses values can be specified either as plain addresses or with a
8195netmask appended, in which case the IPv4 address matches whenever it is
8196within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01008197host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +01008198difficult to read and debug configurations. If hostnames are used, you should
8199at least ensure that they are present in /etc/hosts so that the configuration
8200does not depend on any random DNS match at the moment the configuration is
8201parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +02008202
Willy Tarreauceb4ac92012-04-28 00:41:46 +02008203IPv6 may be entered in their usual form, with or without a netmask appended.
8204Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of
8205trouble with randomly resolved IP addresses, host names are never allowed in
8206IPv6 patterns.
8207
8208HAProxy is also able to match IPv4 addresses with IPv6 addresses in the
8209following situations :
8210 - tested address is IPv4, pattern address is IPv4, the match applies
8211 in IPv4 using the supplied mask if any.
8212 - tested address is IPv6, pattern address is IPv6, the match applies
8213 in IPv6 using the supplied mask if any.
8214 - tested address is IPv6, pattern address is IPv4, the match applies in IPv4
8215 using the pattern's mask if the IPv6 address matches with 2002:IPV4::,
8216 ::IPV4 or ::ffff:IPV4, otherwise it fails.
8217 - tested address is IPv4, pattern address is IPv6, the IPv4 address is first
8218 converted to IPv6 by prefixing ::ffff: in front of it, then the match is
8219 applied in IPv6 using the supplied IPv6 mask.
8220
Willy Tarreau6a06a402007-07-15 20:15:28 +02008221
Willy Tarreauc57f0e22009-05-10 13:12:33 +020082227.5. Available matching criteria
8223--------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02008224
Willy Tarreauc57f0e22009-05-10 13:12:33 +020082257.5.1. Matching at Layer 4 and below
8226------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01008227
8228A first set of criteria applies to information which does not require any
8229analysis of the request or response contents. Those generally include TCP/IP
Jamie Gloudon801a0a32012-08-25 00:18:33 -04008230addresses and ports, as well as internal values independent on the stream.
Willy Tarreau0ba27502007-12-24 16:55:16 +01008231
Willy Tarreau6a06a402007-07-15 20:15:28 +02008232always_false
8233 This one never matches. All values and flags are ignored. It may be used as
8234 a temporary replacement for another one when adjusting configurations.
8235
8236always_true
8237 This one always matches. All values and flags are ignored. It may be used as
8238 a temporary replacement for another one when adjusting configurations.
8239
Willy Tarreaud63335a2010-02-26 12:56:52 +01008240avg_queue <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008241avg_queue(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008242 Returns the total number of queued connections of the designated backend
8243 divided by the number of active servers. This is very similar to "queue"
8244 except that the size of the farm is considered, in order to give a more
8245 accurate measurement of the time it may take for a new connection to be
8246 processed. The main usage is to return a sorry page to new users when it
8247 becomes certain they will get a degraded service. Note that in the event
8248 there would not be any active server anymore, we would consider twice the
8249 number of queued connections as the measured value. This is a fair estimate,
8250 as we expect one server to get back soon anyway, but we still prefer to send
8251 new traffic to another backend if in better shape. See also the "queue",
8252 "be_conn", and "be_sess_rate" criteria.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +01008253
Willy Tarreaua36af912009-10-10 12:02:45 +02008254be_conn <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008255be_conn(<backend>) <integer>
Willy Tarreaua36af912009-10-10 12:02:45 +02008256 Applies to the number of currently established connections on the backend,
8257 possibly including the connection being evaluated. If no backend name is
8258 specified, the current one is used. But it is also possible to check another
8259 backend. It can be used to use a specific farm when the nominal one is full.
8260 See also the "fe_conn", "queue" and "be_sess_rate" criteria.
Willy Tarreau6a06a402007-07-15 20:15:28 +02008261
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01008262be_id <integer>
8263 Applies to the backend's id. Can be used in frontends to check from which
8264 backend it was called.
8265
Willy Tarreaud63335a2010-02-26 12:56:52 +01008266be_sess_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008267be_sess_rate(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008268 Returns true when the sessions creation rate on the backend matches the
8269 specified values or ranges, in number of new sessions per second. This is
8270 used to switch to an alternate backend when an expensive or fragile one
8271 reaches too high a session rate, or to limit abuse of service (eg. prevent
8272 sucking of an online dictionary).
8273
8274 Example :
8275 # Redirect to an error page if the dictionary is requested too often
8276 backend dynamic
8277 mode http
8278 acl being_scanned be_sess_rate gt 100
8279 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +01008280
Tait Clarridge7896d522012-12-05 21:39:31 -05008281srv_sess_rate(<backend>/<server>) <integer>
8282 Returns true when the sessions creation rate on the server matches the
8283 specified values or ranges, in number of new sessions per second. This is
8284 used to switch to an alternate backend when an expensive or fragile one
8285 reaches too high a session rate, or to limit abuse of service (eg. prevent
8286 latent requests from overloading servers).
8287
8288 Example :
8289 # Redirect to a separate back
8290 acl srv1_full srv_sess_rate(be1/srv1) gt 50
8291 acl srv2_full srv_sess_rate(be1/srv2) gt 50
8292 use_backend be2 if srv1_full or srv2_full
8293
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08008294connslots <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008295connslots(<backend>) <integer>
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08008296 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +02008297 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08008298 usage; see "use_backend" keyword) can be redirected to a different backend.
8299
Willy Tarreau55165fe2009-05-10 12:02:55 +02008300 'connslots' = number of available server connection slots, + number of
8301 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08008302
Willy Tarreaua36af912009-10-10 12:02:45 +02008303 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +02008304 useful when you have a case of traffic going to one single ip, splitting into
8305 multiple backends (perhaps using acls to do name-based load balancing) and
8306 you want to be able to differentiate between different backends, and their
8307 available "connslots". Also, whereas "nbsrv" only measures servers that are
8308 actually *down*, this acl is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +02008309 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08008310
Willy Tarreau55165fe2009-05-10 12:02:55 +02008311 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
8312 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
8313 then this acl clearly does not make sense, in which case the value returned
8314 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +08008315
Willy Tarreaud63335a2010-02-26 12:56:52 +01008316dst <ip_address>
Willy Tarreauceb4ac92012-04-28 00:41:46 +02008317 Applies to the local IPv4 or IPv6 address the client connected to. It can be
8318 used to switch to a different backend for some alternative addresses.
Willy Tarreaua36af912009-10-10 12:02:45 +02008319
Willy Tarreaud63335a2010-02-26 12:56:52 +01008320dst_conn <integer>
8321 Applies to the number of currently established connections on the same socket
8322 including the one being evaluated. It can be used to either return a sorry
8323 page before hard-blocking, or to use a specific backend to drain new requests
8324 when the socket is considered saturated. This offers the ability to assign
8325 different limits to different listening ports or addresses. See also the
8326 "fe_conn" and "be_conn" criteria.
8327
8328dst_port <integer>
8329 Applies to the local port the client connected to. It can be used to switch
8330 to a different backend for some alternative ports.
8331
8332fe_conn <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008333fe_conn(<frontend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008334 Applies to the number of currently established connections on the frontend,
8335 possibly including the connection being evaluated. If no frontend name is
8336 specified, the current one is used. But it is also possible to check another
8337 frontend. It can be used to either return a sorry page before hard-blocking,
8338 or to use a specific backend to drain new requests when the farm is
8339 considered saturated. See also the "dst_conn", "be_conn" and "fe_sess_rate"
8340 criteria.
8341
8342fe_id <integer>
Cyril Bonté78caf842010-03-10 22:41:43 +01008343 Applies to the frontend's id. Can be used in backends to check from which
Willy Tarreaud63335a2010-02-26 12:56:52 +01008344 frontend it was called.
Willy Tarreaua36af912009-10-10 12:02:45 +02008345
Willy Tarreau079ff0a2009-03-05 21:34:28 +01008346fe_sess_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008347fe_sess_rate(<frontend>) <integer>
Willy Tarreau079ff0a2009-03-05 21:34:28 +01008348 Returns true when the session creation rate on the current or the named
8349 frontend matches the specified values or ranges, expressed in new sessions
8350 per second. This is used to limit the connection rate to acceptable ranges in
8351 order to prevent abuse of service at the earliest moment. This can be
8352 combined with layer 4 ACLs in order to force the clients to wait a bit for
8353 the rate to go down below the limit.
8354
8355 Example :
8356 # This frontend limits incoming mails to 10/s with a max of 100
8357 # concurrent connections. We accept any connection below 10/s, and
8358 # force excess clients to wait for 100 ms. Since clients are limited to
8359 # 100 max, there cannot be more than 10 incoming mails per second.
8360 frontend mail
8361 bind :25
8362 mode tcp
8363 maxconn 100
8364 acl too_fast fe_sess_rate ge 10
8365 tcp-request inspect-delay 100ms
8366 tcp-request content accept if ! too_fast
8367 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +01008368
Willy Tarreaud63335a2010-02-26 12:56:52 +01008369nbsrv <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008370nbsrv(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008371 Returns true when the number of usable servers of either the current backend
8372 or the named backend matches the values or ranges specified. This is used to
8373 switch to an alternate backend when the number of servers is too low to
8374 to handle some load. It is useful to report a failure when combined with
8375 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +01008376
Willy Tarreaud63335a2010-02-26 12:56:52 +01008377queue <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008378queue(<backend>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01008379 Returns the total number of queued connections of the designated backend,
8380 including all the connections in server queues. If no backend name is
8381 specified, the current one is used, but it is also possible to check another
8382 one. This can be used to take actions when queuing goes above a known level,
8383 generally indicating a surge of traffic or a massive slowdown on the servers.
8384 One possible action could be to reject new users but still accept old ones.
8385 See also the "avg_queue", "be_conn", and "be_sess_rate" criteria.
8386
Willy Tarreau869948b2013-01-04 14:14:57 +01008387sc1_bytes_in_rate <integer>
8388sc2_bytes_in_rate <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008389 Returns the average client-to-server bytes rate from the currently tracked
8390 counters, measured in amount of bytes over the period configured in the
8391 table. See also src_bytes_in_rate.
8392
Willy Tarreau869948b2013-01-04 14:14:57 +01008393sc1_bytes_out_rate <integer>
8394sc2_bytes_out_rate <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008395 Returns the average server-to-client bytes rate from the currently tracked
8396 counters, measured in amount of bytes over the period configured in the
8397 table. See also src_bytes_out_rate.
8398
Willy Tarreau869948b2013-01-04 14:14:57 +01008399sc1_clr_gpc0 <integer>
8400sc2_clr_gpc0 <integer>
Willy Tarreauf73cd112011-08-13 01:45:16 +02008401 Clears the first General Purpose Counter associated to the currently tracked
8402 counters, and returns its previous value. Before the first invocation, the
Willy Tarreau869948b2013-01-04 14:14:57 +01008403 stored value is zero, so first invocation will always return zero. This is
8404 typically used as a second ACL in an expression in order to mark a connection
8405 when a first ACL was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +02008406
8407 # block if 5 consecutive requests continue to come faster than 10 sess
8408 # per second, and reset the counter as soon as the traffic slows down.
8409 acl abuse sc1_http_req_rate gt 10
8410 acl kill sc1_inc_gpc0 gt 5
Willy Tarreau869948b2013-01-04 14:14:57 +01008411 acl save sc1_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +02008412 tcp-request connection accept if !abuse save
8413 tcp-request connection reject if abuse kill
8414
Willy Tarreau869948b2013-01-04 14:14:57 +01008415sc1_conn_cnt <integer>
8416sc2_conn_cnt <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008417 Returns the cumulated number of incoming connections from currently tracked
8418 counters. See also src_conn_cnt.
8419
Willy Tarreau869948b2013-01-04 14:14:57 +01008420sc1_conn_cur <integer>
8421sc2_conn_cur <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008422 Returns the current amount of concurrent connections tracking the same
8423 tracked counters. This number is automatically incremented when tracking
8424 begins and decremented when tracking stops. See also src_conn_cur.
8425
Willy Tarreau869948b2013-01-04 14:14:57 +01008426sc1_conn_rate <integer>
8427sc2_conn_rate <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008428 Returns the average connection rate from the currently tracked counters,
8429 measured in amount of connections over the period configured in the table.
8430 See also src_conn_rate.
8431
Willy Tarreau869948b2013-01-04 14:14:57 +01008432sc1_get_gpc0 <integer>
8433sc2_get_gpc0 <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008434 Returns the value of the first General Purpose Counter associated to the
8435 currently tracked counters. See also src_get_gpc0 and sc1/sc2_inc_gpc0.
8436
Willy Tarreau869948b2013-01-04 14:14:57 +01008437sc1_http_err_cnt <integer>
8438sc2_http_err_cnt <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008439 Returns the cumulated number of HTTP errors from the currently tracked
8440 counters. This includes the both request errors and 4xx error responses.
8441 See also src_http_err_cnt.
8442
Willy Tarreau869948b2013-01-04 14:14:57 +01008443sc1_http_err_rate <integer>
8444sc2_http_err_rate <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008445 Returns the average rate of HTTP errors from the currently tracked counters,
8446 measured in amount of errors over the period configured in the table. This
8447 includes the both request errors and 4xx error responses. See also
8448 src_http_err_rate.
8449
Willy Tarreau869948b2013-01-04 14:14:57 +01008450sc1_http_req_cnt <integer>
8451sc2_http_req_cnt <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008452 Returns the cumulated number of HTTP requests from the currently tracked
8453 counters. This includes every started request, valid or not. See also
8454 src_http_req_cnt.
8455
Willy Tarreau869948b2013-01-04 14:14:57 +01008456sc1_http_req_rate <integer>
8457sc2_http_req_rate <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008458 Returns the average rate of HTTP requests from the currently tracked
8459 counters, measured in amount of requests over the period configured in
8460 the table. This includes every started request, valid or not. See also
8461 src_http_req_rate.
8462
Willy Tarreau869948b2013-01-04 14:14:57 +01008463sc1_inc_gpc0 <integer>
8464sc2_inc_gpc0 <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008465 Increments the first General Purpose Counter associated to the currently
Willy Tarreau869948b2013-01-04 14:14:57 +01008466 tracked counters, and returns its new value. Before the first invocation,
8467 the stored value is zero, so first invocation will increase it to 1 and will
8468 return 1. This is typically used as a second ACL in an expression in order
8469 to mark a connection when a first ACL was verified :
Willy Tarreaue9656522010-08-17 15:40:09 +02008470
8471 acl abuse sc1_http_req_rate gt 10
Willy Tarreau869948b2013-01-04 14:14:57 +01008472 acl kill sc1_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +02008473 tcp-request connection reject if abuse kill
8474
Willy Tarreau869948b2013-01-04 14:14:57 +01008475sc1_kbytes_in <integer>
8476sc2_kbytes_in <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008477 Returns the amount of client-to-server data from the currently tracked
8478 counters, measured in kilobytes over the period configured in the table. The
8479 test is currently performed on 32-bit integers, which limits values to 4
8480 terabytes. See also src_kbytes_in.
8481
Willy Tarreau869948b2013-01-04 14:14:57 +01008482sc1_kbytes_out <integer>
8483sc2_kbytes_out <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008484 Returns the amount of server-to-client data from the currently tracked
8485 counters, measured in kilobytes over the period configured in the table. The
8486 test is currently performed on 32-bit integers, which limits values to 4
8487 terabytes. See also src_kbytes_out.
8488
Willy Tarreau869948b2013-01-04 14:14:57 +01008489sc1_sess_cnt <integer>
8490sc2_sess_cnt <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008491 Returns the cumulated number of incoming connections that were transformed
8492 into sessions, which means that they were accepted by a "tcp-request
8493 connection" rule, from the currently tracked counters. A backend may count
8494 more sessions than connections because each connection could result in many
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008495 backend sessions if some HTTP keep-alive is performed over the connection
Willy Tarreaue9656522010-08-17 15:40:09 +02008496 with the client. See also src_sess_cnt.
8497
Willy Tarreau869948b2013-01-04 14:14:57 +01008498sc1_sess_rate <integer>
8499sc2_sess_rate <integer>
Willy Tarreaue9656522010-08-17 15:40:09 +02008500 Returns the average session rate from the currently tracked counters,
8501 measured in amount of sessions over the period configured in the table. A
8502 session is a connection that got past the early "tcp-request connection"
8503 rules. A backend may count more sessions than connections because each
8504 connection could result in many backend sessions if some HTTP keep-alive is
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008505 performed over the connection with the client. See also src_sess_rate.
Willy Tarreaue9656522010-08-17 15:40:09 +02008506
Willy Tarreau869948b2013-01-04 14:14:57 +01008507sc1_trackers <integer>
8508sc2_trackers <integer>
Willy Tarreau2406db42012-12-09 12:16:43 +01008509 Returns the current amount of concurrent connections tracking the same
8510 tracked counters. This number is automatically incremented when tracking
8511 begins and decremented when tracking stops. It differs from sc1_conn_cur in
8512 that it does not rely on any stored information but on the table's reference
8513 count (the "use" value which is returned by "show table" on the CLI). This
8514 may sometimes be more suited for layer7 tracking.
8515
Willy Tarreaud63335a2010-02-26 12:56:52 +01008516so_id <integer>
8517 Applies to the socket's id. Useful in frontends with many bind keywords.
8518
8519src <ip_address>
Willy Tarreauceb4ac92012-04-28 00:41:46 +02008520 Applies to the client's IPv4 or IPv6 address. It is usually used to limit
8521 access to certain resources such as statistics. Note that it is the TCP-level
8522 source address which is used, and not the address of a client behind a proxy.
Willy Tarreaud63335a2010-02-26 12:56:52 +01008523
Willy Tarreauc9705a12010-07-27 20:05:50 +02008524src_bytes_in_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008525src_bytes_in_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008526 Returns the average bytes rate from the connection's source IPv4 address in
8527 the current proxy's stick-table or in the designated stick-table, measured in
8528 amount of bytes over the period configured in the table. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02008529 not found, zero is returned. See also sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008530
8531src_bytes_out_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008532src_bytes_out_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008533 Returns the average bytes rate to the connection's source IPv4 address in the
8534 current proxy's stick-table or in the designated stick-table, measured in
8535 amount of bytes over the period configured in the table. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02008536 not found, zero is returned. See also sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008537
Willy Tarreauf73cd112011-08-13 01:45:16 +02008538src_clr_gpc0 <integer>
8539src_clr_gpc0(<table>) <integer>
8540 Clears the first General Purpose Counter associated to the connection's
8541 source IPv4 address in the current proxy's stick-table or in the designated
8542 stick-table, and returns its previous value. If the address is not found, an
Willy Tarreau869948b2013-01-04 14:14:57 +01008543 entry is created and 0 is returned. This is typically used as a second ACL in
8544 an expression in order to mark a connection when a first ACL was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +02008545
8546 # block if 5 consecutive requests continue to come faster than 10 sess
8547 # per second, and reset the counter as soon as the traffic slows down.
8548 acl abuse src_http_req_rate gt 10
8549 acl kill src_inc_gpc0 gt 5
Willy Tarreau869948b2013-01-04 14:14:57 +01008550 acl save src_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +02008551 tcp-request connection accept if !abuse save
8552 tcp-request connection reject if abuse kill
8553
Willy Tarreauc9705a12010-07-27 20:05:50 +02008554src_conn_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008555src_conn_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008556 Returns the cumulated number of connections initiated from the current
8557 connection's source IPv4 address in the current proxy's stick-table or in
8558 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreaue9656522010-08-17 15:40:09 +02008559 See also sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008560
8561src_conn_cur <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008562src_conn_cur(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008563 Returns the current amount of concurrent connections initiated from the
8564 current connection's source IPv4 address in the current proxy's stick-table
8565 or in the designated stick-table. If the address is not found, zero is
Willy Tarreaue9656522010-08-17 15:40:09 +02008566 returned. See also sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008567
8568src_conn_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008569src_conn_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008570 Returns the average connection rate from the connection's source IPv4 address
8571 in the current proxy's stick-table or in the designated stick-table, measured
8572 in amount of connections over the period configured in the table. If the
Willy Tarreaue9656522010-08-17 15:40:09 +02008573 address is not found, zero is returned. See also sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008574
8575src_get_gpc0 <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008576src_get_gpc0(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008577 Returns the value of the first General Purpose Counter associated to the
8578 connection's source IPv4 address in the current proxy's stick-table or in
8579 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreaue9656522010-08-17 15:40:09 +02008580 See also sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008581
8582src_http_err_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008583src_http_err_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008584 Returns the cumulated number of HTTP errors from the current connection's
8585 source IPv4 address in the current proxy's stick-table or in the designated
8586 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreaue9656522010-08-17 15:40:09 +02008587 If the address is not found, zero is returned. See also sc1/sc2_http_err_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008588
8589src_http_err_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008590src_http_err_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008591 Returns the average rate of HTTP errors from the current connection's source
8592 IPv4 address in the current proxy's stick-table or in the designated stick-
8593 table, measured in amount of errors over the period configured in the table.
8594 This includes the both request errors and 4xx error responses. If the address
Willy Tarreaue9656522010-08-17 15:40:09 +02008595 is not found, zero is returned. See also sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008596
8597src_http_req_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008598src_http_req_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008599 Returns the cumulated number of HTTP requests from the current connection's
8600 source IPv4 address in the current proxy's stick-table or in the designated
8601 stick-table. This includes every started request, valid or not. If the
Willy Tarreaue9656522010-08-17 15:40:09 +02008602 address is not found, zero is returned. See also sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008603
8604src_http_req_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008605src_http_req_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008606 Returns the average rate of HTTP requests from the current connection's
8607 source IPv4 address in the current proxy's stick-table or in the designated
8608 stick-table, measured in amount of requests over the period configured in the
8609 table. This includes every started request, valid or not. If the address is
Willy Tarreaue9656522010-08-17 15:40:09 +02008610 not found, zero is returned. See also sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008611
8612src_inc_gpc0 <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008613src_inc_gpc0(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008614 Increments the first General Purpose Counter associated to the connection's
8615 source IPv4 address in the current proxy's stick-table or in the designated
Willy Tarreau869948b2013-01-04 14:14:57 +01008616 stick-table, and returns its new value. If the address is not found, an entry
8617 is created and 1 is returned. This is typically used as a second ACL in an
8618 expression in order to mark a connection when a first ACL was verified :
Willy Tarreauc9705a12010-07-27 20:05:50 +02008619
8620 acl abuse src_http_req_rate gt 10
Willy Tarreau869948b2013-01-04 14:14:57 +01008621 acl kill src_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +02008622 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +02008623
8624src_kbytes_in <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008625src_kbytes_in(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008626 Returns the amount of data received from the connection's source IPv4 address
8627 in the current proxy's stick-table or in the designated stick-table, measured
8628 in kilobytes over the period configured in the table. If the address is not
8629 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreaue9656522010-08-17 15:40:09 +02008630 which limits values to 4 terabytes. See also sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008631
8632src_kbytes_out <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008633src_kbytes_out(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008634 Returns the amount of data sent to the connection's source IPv4 address in
8635 the current proxy's stick-table or in the designated stick-table, measured
8636 in kilobytes over the period configured in the table. If the address is not
8637 found, zero is returned. The test is currently performed on 32-bit integers,
Willy Tarreaue9656522010-08-17 15:40:09 +02008638 which limits values to 4 terabytes. See also sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008639
Willy Tarreaud63335a2010-02-26 12:56:52 +01008640src_port <integer>
8641 Applies to the client's TCP source port. This has a very limited usage.
Willy Tarreau079ff0a2009-03-05 21:34:28 +01008642
Willy Tarreauc9705a12010-07-27 20:05:50 +02008643src_sess_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008644src_sess_cnt(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008645 Returns the cumulated number of connections initiated from the current
8646 connection's source IPv4 address in the current proxy's stick-table or in the
8647 designated stick-table, that were transformed into sessions, which means that
8648 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreaue9656522010-08-17 15:40:09 +02008649 is returned. See also sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008650
8651src_sess_rate <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008652src_sess_rate(<table>) <integer>
Willy Tarreauc9705a12010-07-27 20:05:50 +02008653 Returns the average session rate from the connection's source IPv4 address in
8654 the current proxy's stick-table or in the designated stick-table, measured in
8655 amount of sessions over the period configured in the table. A session is a
8656 connection that got past the early "tcp-request" rules. If the address is not
Willy Tarreaue9656522010-08-17 15:40:09 +02008657 found, zero is returned. See also sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008658
8659src_updt_conn_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008660src_updt_conn_cnt(<table>) <integer>
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008661 Creates or updates the entry associated to the source IPv4 address in the
Willy Tarreauc9705a12010-07-27 20:05:50 +02008662 current proxy's stick-table or in the designated stick-table. This table
8663 must be configured to store the "conn_cnt" data type, otherwise the match
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008664 will be ignored. The current count is incremented by one, and the expiration
8665 timer refreshed. The updated count is returned, so this match can't return
8666 zero. This is used to reject service abusers based on their source address.
Willy Tarreauc9705a12010-07-27 20:05:50 +02008667 Note: it is recommended to use the more complete "track-counters" instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008668
8669 Example :
8670 # This frontend limits incoming SSH connections to 3 per 10 second for
8671 # each source address, and rejects excess connections until a 10 second
8672 # silence is observed. At most 20 addresses are tracked.
8673 listen ssh
8674 bind :22
8675 mode tcp
8676 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +02008677 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreaua975b8f2010-06-05 19:13:27 +02008678 tcp-request content reject if { src_update_count gt 3 }
8679 server local 127.0.0.1:22
8680
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008681srv_conn(<backend>/<server>) <integer>
Hervé COMMOWICKdaa824e2011-08-05 12:09:44 +02008682 Applies to the number of currently established connections on the server,
8683 possibly including the connection being evaluated.
8684 It can be used to use a specific farm when one server is full.
8685 See also the "fe_conn", "be_conn" and "queue" criteria.
8686
Hervé COMMOWICK35ed8012010-12-15 14:04:51 +01008687srv_id <integer>
8688 Applies to the server's id. Can be used in frontends or backends.
8689
Willy Tarreau0b1cd942010-05-16 22:18:27 +02008690srv_is_up(<server>)
8691srv_is_up(<backend>/<server>)
8692 Returns true when the designated server is UP, and false when it is either
8693 DOWN or in maintenance mode. If <backend> is omitted, then the server is
8694 looked up in the current backend. The function takes no arguments since it
8695 is used as a boolean. It is mainly used to take action based on an external
8696 status reported via a health check (eg: a geographical site's availability).
8697 Another possible use which is more of a hack consists in using dummy servers
8698 as boolean variables that can be enabled or disabled from the CLI, so that
8699 rules depending on those ACLs can be tweaked in realtime.
8700
Willy Tarreauc735a072011-03-29 00:57:02 +02008701table_avl <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008702table_avl(<table>) <integer>
Willy Tarreauc735a072011-03-29 00:57:02 +02008703 Returns the total number of available entries in the current proxy's
8704 stick-table or in the designated stick-table. See also table_cnt.
8705
8706table_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008707table_cnt(<table>) <integer>
Willy Tarreauc735a072011-03-29 00:57:02 +02008708 Returns the total number of entries currently in use in the current proxy's
8709 stick-table or in the designated stick-table. See also src_conn_cnt and
8710 table_avl for other entry counting methods.
8711
Willy Tarreau0ba27502007-12-24 16:55:16 +01008712
Willy Tarreaue9656522010-08-17 15:40:09 +020087137.5.2. Matching contents at Layer 4 (also called Layer 6)
8714---------------------------------------------------------
Willy Tarreau62644772008-07-16 18:36:06 +02008715
8716A second set of criteria depends on data found in buffers, but which can change
8717during analysis. This requires that some data has been buffered, for instance
Willy Tarreaue9656522010-08-17 15:40:09 +02008718through TCP request content inspection. Please see the "tcp-request content"
8719keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +02008720
Willy Tarreaub6672b52011-12-12 17:23:41 +01008721rep_ssl_hello_type <integer>
8722 Returns true when data in the response buffer looks like a complete SSL (v3
8723 or superior) hello message and handshake type is equal to <integer>.
8724 This test was designed to be used with TCP response content inspection: a
Willy Tarreau7875d092012-09-10 08:20:03 +02008725 SSL session ID may be fetched. Note that this only applies to raw contents
Willy Tarreaud4c33c82013-01-07 21:59:07 +01008726 found in the response buffer and not to contents deciphered via an SSL data
8727 layer, so this will not work with "server" lines having the "ssl" option.
Willy Tarreaub6672b52011-12-12 17:23:41 +01008728
Willy Tarreau62644772008-07-16 18:36:06 +02008729req_len <integer>
Emeric Brunbede3d02009-06-30 17:54:00 +02008730 Returns true when the length of the data in the request buffer matches the
Willy Tarreau62644772008-07-16 18:36:06 +02008731 specified range. It is important to understand that this test does not
8732 return false as long as the buffer is changing. This means that a check with
8733 equality to zero will almost always immediately match at the beginning of the
8734 session, while a test for more data will wait for that data to come in and
8735 return false only when haproxy is certain that no more data will come in.
8736 This test was designed to be used with TCP request content inspection.
8737
Willy Tarreau2492d5b2009-07-11 00:06:00 +02008738req_proto_http
8739 Returns true when data in the request buffer look like HTTP and correctly
8740 parses as such. It is the same parser as the common HTTP request parser which
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008741 is used so there should be no surprises. This test can be used for instance
Willy Tarreau2492d5b2009-07-11 00:06:00 +02008742 to direct HTTP traffic to a given port and HTTPS traffic to another one
8743 using TCP request content inspection rules.
8744
Emeric Brunbede3d02009-06-30 17:54:00 +02008745req_rdp_cookie <string>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008746req_rdp_cookie(<name>) <string>
Emeric Brunbede3d02009-06-30 17:54:00 +02008747 Returns true when data in the request buffer look like the RDP protocol, and
8748 a cookie is present and equal to <string>. By default, any cookie name is
8749 checked, but a specific cookie name can be specified in parenthesis. The
8750 parser only checks for the first cookie, as illustrated in the RDP protocol
8751 specification. The cookie name is case insensitive. This ACL can be useful
8752 with the "MSTS" cookie, as it can contain the user name of the client
8753 connecting to the server if properly configured on the client. This can be
8754 used to restrict access to certain servers to certain users.
8755
8756req_rdp_cookie_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02008757req_rdp_cookie_cnt(<name>) <integer>
Emeric Brunbede3d02009-06-30 17:54:00 +02008758 Returns true when the data in the request buffer look like the RDP protocol
8759 and the number of RDP cookies matches the specified range (typically zero or
8760 one). Optionally a specific cookie name can be checked. This is a simple way
8761 of detecting the RDP protocol, as clients generally send the MSTS or MSTSHASH
8762 cookies.
8763
Willy Tarreaub6672b52011-12-12 17:23:41 +01008764req_ssl_hello_type <integer>
8765 Returns true when data in the request buffer looks like a complete SSL (v3
8766 or superior) hello message and handshake type is equal to <integer>.
8767 This test was designed to be used with TCP request content inspection: an
Willy Tarreau7875d092012-09-10 08:20:03 +02008768 SSL session ID may be fetched. Note that this only applies to raw contents
8769 found in the request buffer and not to contents deciphered via an SSL data
8770 layer, so this will not work with "bind" lines having the "ssl" option.
Willy Tarreaub6672b52011-12-12 17:23:41 +01008771
8772req_ssl_sni <string>
8773 Returns true when data in the request buffer looks like a complete SSL (v3
8774 or superior) client hello message with a Server Name Indication TLS extension
8775 (SNI) matching <string>. SNI normally contains the name of the host the
8776 client tries to connect to (for recent browsers). SNI is useful for allowing
8777 or denying access to certain hosts when SSL/TLS is used by the client. This
8778 test was designed to be used with TCP request content inspection. If content
8779 switching is needed, it is recommended to first wait for a complete client
Willy Tarreau7875d092012-09-10 08:20:03 +02008780 hello (type 1), like in the example below. Note that this only applies to raw
8781 contents found in the request buffer and not to contents deciphered via an
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008782 SSL transport layer, so this will not work with "bind" lines having the "ssl"
Willy Tarreau7875d092012-09-10 08:20:03 +02008783 option. See also "ssl_sni" below.
Willy Tarreaub6672b52011-12-12 17:23:41 +01008784
8785 Examples :
8786 # Wait for a client hello for at most 5 seconds
8787 tcp-request inspect-delay 5s
8788 tcp-request content accept if { req_ssl_hello_type 1 }
8789 use_backend bk_allow if { req_ssl_sni -f allowed_sites }
8790 default_backend bk_sorry_page
8791
Willy Tarreau62644772008-07-16 18:36:06 +02008792req_ssl_ver <decimal>
8793 Returns true when data in the request buffer look like SSL, with a protocol
8794 version matching the specified range. Both SSLv2 hello messages and SSLv3
8795 messages are supported. The test tries to be strict enough to avoid being
8796 easily fooled. In particular, it waits for as many bytes as announced in the
8797 message header if this header looks valid (bound to the buffer size). Note
8798 that TLSv1 is announced as SSL version 3.1. This test was designed to be used
Willy Tarreau7875d092012-09-10 08:20:03 +02008799 with TCP request content inspection. Note that this only applies to raw
8800 contents found in the request buffer and not to contents deciphered via an
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008801 SSL transport layer, so this will not work with "bind" lines having the "ssl"
Willy Tarreau7875d092012-09-10 08:20:03 +02008802 option.
8803
Emeric Brun2525b6b2012-10-18 15:59:43 +02008804ssl_c_ca_err <integer>
8805 Returns true when the incoming connection was made over an SSL/TLS transport
8806 layer, and the ID of the first error detected during verification of the
8807 client certificate at depth > 0 matches the specified value (check man verify
8808 for possible values). Note that error zero means no error was encountered
8809 during this verification process.
8810
8811ssl_c_ca_err_depth <integer>
8812 Returns true when the incoming connection was made over an SSL/TLS transport
8813 layer, and the depth in the CA chain of the first error detected during the
8814 verification of the client certificate matches the specified value. When no
8815 error is found, depth 0 is returned.
8816
8817ssl_c_err <integer>
8818 Returns true when the incoming connection was made over an SSL/TLS transport
8819 layer, and the ID of the first error detected during verification at depth==0
8820 matches the specified value (check man verify for possible values). Note that
8821 error zero means no error was encountered during this verification process.
8822
Emeric Brun87855892012-10-17 17:39:35 +02008823ssl_c_i_dn <string>
8824ssl_c_i_dn(entry[,occ]) <string>
8825 If no entry specified, returns true when the incoming connection was made
8826 over an SSL/TLS transport layer, and the full distinguished name of the
8827 issuer of the certificate presented by the client matches the specified
8828 string. Otherwise returns true if the value of the first given entry from
8829 the beginning of the DN matches the specified string. If a positive/negative
8830 occurrence number is specified as the optional second argument, it returns
8831 true if the value of the nth given entry value from the beginning/end of the
8832 DN matches the specified string.
8833
Emeric Brun7f56e742012-10-19 18:15:40 +02008834ssl_c_key_alg <string>
8835 Returns true when the incoming connection was made over an SSL/TLS transport
8836 layer, and the name of the algorithm used to generate the key of the
8837 certificate presented by the client matches the string.
8838
Emeric Brunce5ad802012-10-22 14:11:22 +02008839ssl_c_notafter <string>
8840 Returns true when the incoming connection was made over an SSL/TLS transport
8841 layer, and the end date of the certificate presented by the client matches
8842 the string formatted as YYMMDDhhmmss[Z].
8843
8844ssl_c_notbefore <string>
8845 Returns true when the incoming connection was made over an SSL/TLS transport
8846 layer, and the start date of the certificate presented by the client matches
8847 the string formatted as YYMMDDhhmmss[Z].
8848
Emeric Brun87855892012-10-17 17:39:35 +02008849ssl_c_s_dn <string>
8850ssl_c_s_dn(entry[,occ]) <string>
8851 If no entry specified, returns true when the incoming connection was made
8852 over an SSL/TLS transport layer, and the full distinguished name of the
8853 subject of the certificate presented by the client matches the specified
8854 string. Otherwise returns true if the value of the first given entry from
8855 the beginning of the DN matches the specified string. If a positive/negative
8856 occurrence number is specified as the optional second argument, it returns
8857 true if the value of the nth given entry value from the beginning/end of the
8858 DN matches the specified string.
8859
Willy Tarreau8d598402012-10-22 17:58:39 +02008860ssl_c_serial <hexa>
8861 Returns true when the incoming connection was made over an SSL/TLS transport
8862 layer, and the serial of the certificate presented by the client matches
8863 the value written in hexa.
8864
Emeric Brun7f56e742012-10-19 18:15:40 +02008865ssl_c_sig_alg <string>
8866 Returns true when the incoming connection was made over an SSL/TLS transport
8867 layer, and the name of the algorithm used to sign the certificate presented
8868 by the client matches the string.
8869
Emeric Brun9143d372012-12-20 15:44:16 +01008870ssl_c_used
8871 Returns true if current SSL session uses a client certificate even if current
8872 connection uses SSL session resumption. See also "ssl_fc_has_crt".
8873
Emeric Brun2525b6b2012-10-18 15:59:43 +02008874ssl_c_verify <integer>
8875 Returns true when the incoming connection was made over an SSL/TLS transport
8876 layer, and the verify result matches the specified value (check man verify
8877 for possible values). Zero indicates no error was detected.
8878
Emeric Bruna7359fd2012-10-17 15:03:11 +02008879ssl_c_version <integer>
8880 Returns true when the incoming connection was made over an SSL/TLS transport
8881 layer, and the version of the certificate presented by the client matches
8882 the value.
8883
Emeric Brun87855892012-10-17 17:39:35 +02008884ssl_f_i_dn <string>
8885ssl_f_i_dn(entry[,occ]) <string>
8886 If no entry specified, returns true when the incoming connection was made
8887 over an SSL/TLS transport layer, and the full distinguished name of the
8888 issuer of the certificate presented by the frontend matches the specified
8889 string. Otherwise returns true if the value of the first given entry from
8890 the beginning of the DN matches the specified string. If a positive/negative
8891 occurrence number is specified as the optional second argument, it returns
8892 true if the value of the nth given entry value from the beginning/end of the
8893 DN matches the specified string.
8894
Emeric Brun7f56e742012-10-19 18:15:40 +02008895ssl_c_key_alg <string>
8896 Returns true when the incoming connection was made over an SSL/TLS transport
8897 layer, and the name of the algorithm used to generate the key of the
8898 certificate presented by the frontend matches the string.
8899
Emeric Brunce5ad802012-10-22 14:11:22 +02008900ssl_f_notafter <string>
8901 Returns true when the incoming connection was made over an SSL/TLS transport
8902 layer, and the end date of the certificate presented by the frontend matches
8903 the string formatted as YYMMDDhhmmss[Z].
8904
8905ssl_f_notbefore <string>
8906 Returns true when the incoming connection was made over an SSL/TLS transport
8907 layer, and the start date of the certificate presented by the frontend matches
8908 the string formatted as YYMMDDhhmmss[Z].
8909
Emeric Brun87855892012-10-17 17:39:35 +02008910ssl_f_s_dn <string>
8911ssl_f_s_dn(entry[,occ]) <string>
8912 If no entry specified, returns true when the incoming connection was made
8913 over an SSL/TLS transport layer, and the full distinguished name of the
8914 subject of the certificate presented by the frontend matches the specified
8915 string. Otherwise returns true if the value of the first given entry from
8916 the beginning of the DN matches the specified string. If a positive/negative
8917 occurrence number is specified as the optional second argument, it returns
8918 true if the value of the nth given entry value from the beginning/end of the
8919 DN matches the specified string.
8920
Willy Tarreau8d598402012-10-22 17:58:39 +02008921ssl_f_serial <hexa>
8922 Returns true when the incoming connection was made over an SSL/TLS transport
8923 layer, and the serial of the certificate presented by the frontend matches
8924 the value written in hexa.
8925
Emeric Brun7f56e742012-10-19 18:15:40 +02008926ssl_f_sig_alg <string>
8927 Returns true when the incoming connection was made over an SSL/TLS transport
8928 layer, and the name of the algorithm used to sign the certificate presented
8929 by the frontend matches the string.
8930
Emeric Bruna7359fd2012-10-17 15:03:11 +02008931ssl_f_version <integer>
8932 Returns true when the incoming connection was made over an SSL/TLS transport
8933 layer, and the version of the certificate presented by the frontend matches
8934 the value.
8935
Emeric Brun2525b6b2012-10-18 15:59:43 +02008936ssl_fc
8937 Returns true when the front connection was made via an SSL/TLS transport
8938 layer and is locally deciphered. This means it has matched a socket declared
8939 with a "bind" line having the "ssl" option.
8940
Emeric Brun589fcad2012-10-16 14:13:26 +02008941ssl_fc_alg_keysize <integer>
8942 Returns true when the incoming connection was made over an SSL/TLS transport
8943 layer and the symmetric cipher key size supported in bits matches the value.
8944
8945ssl_fc_cipher <string>
8946 returns true when the incoming connection was made over an ssl/tls transport
8947 layer and the name of the used cipher matches the string.
8948
Emeric Brun2525b6b2012-10-18 15:59:43 +02008949ssl_fc_has_crt
8950 Returns true if a client certificate is present in an incoming connection over
8951 SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
Emeric Brun9143d372012-12-20 15:44:16 +01008952 Note: on SSL session resumption with Session ID or TLS ticket, client
8953 certificate is not present in the current connection but may be retrieved
8954 from the cache or the ticket. So prefer "ssl_c_used" if you want to check if
8955 current SSL session uses a client certificate.
Emeric Brun2525b6b2012-10-18 15:59:43 +02008956
8957ssl_fc_has_sni
Willy Tarreau7875d092012-09-10 08:20:03 +02008958 This is used to check for presence of a Server Name Indication TLS extension
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008959 in an incoming connection was made over an SSL/TLS transport layer. Returns
8960 true when the incoming connection presents a TLS SNI field. This requires
8961 that the SSL library is build with support for TLS extensions enabled (check
8962 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02008963
Emeric Brun2525b6b2012-10-18 15:59:43 +02008964ssl_fc_npn <string>
Willy Tarreaua33c6542012-10-15 13:19:06 +02008965 Returns true when the incoming connection was made over an SSL/TLS transport
8966 layer which deciphered it and found a Next Protocol Negociation TLS extension
8967 sent by the client, matching the specified string. This requires that the SSL
8968 library is build with support for TLS extensions enabled (check haproxy -vv).
Willy Tarreau6c9a3d52012-10-18 18:57:14 +02008969 Note that the TLS NPN extension is not advertised unless the "npn" keyword on
8970 the "bind" line specifies a protocol list. Also, nothing forces the client to
8971 pick a protocol from this list, any other one may be requested.
Willy Tarreaua33c6542012-10-15 13:19:06 +02008972
Emeric Brun589fcad2012-10-16 14:13:26 +02008973ssl_fc_protocol <string>
8974 Returns true when the incoming connection was made over an SSL/TLS transport
8975 layer and the name of the used protocol matches the string.
8976
Emeric Brun2525b6b2012-10-18 15:59:43 +02008977ssl_fc_sni <string>
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008978 Returns true when the incoming connection was made over an SSL/TLS transport
8979 layer which deciphered it and found a Server Name Indication TLS extension
8980 sent by the client, matching the specified string. In HTTPS, the SNI field
8981 (when present) is equal to the requested host name. This match is different
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +02008982 from "req_ssl_sni" above in that it applies to the connection being
8983 deciphered by haproxy and not to SSL contents being blindly forwarded.
Emeric Brun2525b6b2012-10-18 15:59:43 +02008984 See also "ssl_fc_sni_end" and "ssl_fc_sni_req" below. This requires that the
8985 SSL library is build with support for TLS extensions enabled (check
8986 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02008987
Emeric Brun2525b6b2012-10-18 15:59:43 +02008988ssl_fc_sni_end <string>
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008989 Returns true when the incoming connection was made over an SSL/TLS transport
8990 layer which deciphered it and found a Server Name Indication TLS extension
8991 sent by the client, ending like the specified string. In HTTPS, the SNI field
8992 (when present) is equal to the requested host name. This match is different
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +02008993 from "req_ssl_sni" above in that it applies to the connection being
8994 deciphered by haproxy and not to SSL contents being blindly forwarded. This
8995 requires that the SSL library is build with support for TLS extensions
8996 enabled (check haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +02008997
Emeric Brun2525b6b2012-10-18 15:59:43 +02008998ssl_fc_sni_reg <regex>
Willy Tarreauf7bc57c2012-10-03 00:19:48 +02008999 Returns true when the incoming connection was made over an SSL/TLS transport
9000 layer which deciphered it and found a Server Name Indication TLS extension
9001 sent by the client, matching the specified regex. In HTTPS, the SNI field
9002 (when present) is equal to the requested host name. This match is different
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +02009003 from "req_ssl_sni" above in that it applies to the connection being
9004 deciphered by haproxy and not to SSL contents being blindly forwarded. This
9005 requires that the SSL library is build with support for TLS extensions
9006 enabled (check haproxy -vv).
Willy Tarreau62644772008-07-16 18:36:06 +02009007
Emeric Brun589fcad2012-10-16 14:13:26 +02009008ssl_fc_use_keysize <integer>
9009 Returns true when the incoming connection was made over an SSL/TLS transport
9010 layer and the symmetric cipher key size used in bits matches the value.
9011
Willy Tarreaub6fb4202008-07-20 11:18:28 +02009012wait_end
9013 Waits for the end of the analysis period to return true. This may be used in
9014 conjunction with content analysis to avoid returning a wrong verdict early.
9015 It may also be used to delay some actions, such as a delayed reject for some
9016 special addresses. Since it either stops the rules evaluation or immediately
9017 returns true, it is recommended to use this acl as the last one in a rule.
9018 Please note that the default ACL "WAIT_END" is always usable without prior
9019 declaration. This test was designed to be used with TCP request content
9020 inspection.
9021
9022 Examples :
9023 # delay every incoming request by 2 seconds
9024 tcp-request inspect-delay 2s
9025 tcp-request content accept if WAIT_END
9026
9027 # don't immediately tell bad guys they are rejected
9028 tcp-request inspect-delay 10s
9029 acl goodguys src 10.0.0.0/24
9030 acl badguys src 10.0.1.0/24
9031 tcp-request content accept if goodguys
9032 tcp-request content reject if badguys WAIT_END
9033 tcp-request content reject
9034
Willy Tarreau62644772008-07-16 18:36:06 +02009035
Willy Tarreauc57f0e22009-05-10 13:12:33 +020090367.5.3. Matching at Layer 7
9037--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01009038
Willy Tarreau62644772008-07-16 18:36:06 +02009039A third set of criteria applies to information which can be found at the
Willy Tarreau0ba27502007-12-24 16:55:16 +01009040application layer (layer 7). Those require that a full HTTP request has been
9041read, and are only evaluated then. They may require slightly more CPU resources
9042than the layer 4 ones, but not much since the request and response are indexed.
9043
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02009044base <string>
9045 Returns true when the concatenation of the first Host header and the path
9046 part of the request, which starts at the first slash and ends before the
9047 question mark, equals one of the strings. It may be used to match known
9048 files in virtual hosting environments, such as "www.example.com/favicon.ico".
9049 See also "path" and "uri".
9050
9051base_beg <string>
9052 Returns true when the base (see above) begins with one of the strings. This
9053 can be used to send certain directory names to alternative backends. See also
9054 "path_beg".
9055
9056base_dir <string>
9057 Returns true when one of the strings is found isolated or delimited with
9058 slashes in the base (see above). Probably of little use, see "url_dir" and
9059 "path_dir" instead.
9060
9061base_dom <string>
9062 Returns true when one of the strings is found isolated or delimited with dots
9063 in the base (see above). Probably of little use, see "path_dom" and "url_dom"
9064 instead.
9065
9066base_end <string>
9067 Returns true when the base (see above) ends with one of the strings. This may
9068 be used to control file name extension, though "path_end" is cheaper.
9069
9070base_len <integer>
9071 Returns true when the base (see above) length matches the values or ranges
9072 specified. This may be used to detect abusive requests for instance.
9073
9074base_reg <regex>
9075 Returns true when the base (see above) matches one of the regular
9076 expressions. It can be used any time, but it is important to remember that
9077 regex matching is slower than other methods. See also "path_reg", "url_reg"
9078 and all "base_" criteria.
9079
9080base_sub <string>
9081 Returns true when the base (see above) contains one of the strings. It can be
9082 used to detect particular patterns in paths, such as "../" for example. See
9083 also "base_dir".
9084
Willy Tarreau04aa6a92012-04-06 18:57:55 +02009085cook(<name>) <string>
9086 All "cook*" matching criteria inspect all "Cookie" headers to find a cookie
9087 with the name between parenthesis. If multiple occurrences of the cookie are
9088 found in the request, they will all be evaluated. Spaces around the name and
9089 the value are ignored as requested by the Cookie specification (RFC6265). The
9090 cookie name is case-sensitive. Use the scook() variant for response cookies
9091 sent by the server.
9092
9093 The "cook" criteria returns true if any of the request cookies <name> match
9094 any of the strings. This can be used to check exact for values. For instance,
9095 checking that the "profile" cookie is set to either "silver" or "gold" :
9096
9097 cook(profile) silver gold
9098
9099cook_beg(<name>) <string>
9100 Returns true if any of the request cookies <name> begins with one of the
9101 strings. See "cook" for more information on cookie matching. Use the
9102 scook_beg() variant for response cookies sent by the server.
9103
9104cook_cnt(<name>) <integer>
9105 Returns true when the number of occurrences of the specified cookie matches
9106 the values or ranges specified. This is used to detect presence, absence or
9107 abuse of a specific cookie. See "cook" for more information on header
9108 matching. Use the scook_cnt() variant for response cookies sent by the
9109 server.
9110
9111cook_dir(<name>) <string>
9112 Returns true if any of the request cookies <name> contains one of the strings
9113 either isolated or delimited by slashes. This is used to perform filename or
9114 directory name matching, though it generally is of limited use with cookies.
9115 See "cook" for more information on cookie matching. Use the scook_dir()
9116 variant for response cookies sent by the server.
9117
9118cook_dom(<name>) <string>
9119 Returns true if any of the request cookies <name> contains one of the strings
9120 either isolated or delimited by dots. This is used to perform domain name
9121 matching. See "cook" for more information on cookie matching. Use the
9122 scook_dom() variant for response cookies sent by the server.
9123
9124cook_end(<name>) <string>
9125 Returns true if any of the request cookies <name> ends with one of the
9126 strings. See "cook" for more information on cookie matching. Use the
9127 scook_end() variant for response cookies sent by the server.
9128
9129cook_len(<name>) <integer>
9130 Returns true if any of the request cookies <name> has a length which matches
9131 the values or ranges specified. This may be used to detect empty or too large
9132 cookie values. Note that an absent cookie does not match a zero-length test.
9133 See "cook" for more information on cookie matching. Use the scook_len()
9134 variant for response cookies sent by the server.
9135
9136cook_reg(<name>) <regex>
9137 Returns true if any of the request cookies <name> matches any of the regular
9138 expressions. It can be used at any time, but it is important to remember that
9139 regex matching is slower than other methods. See also other "cook_" criteria,
9140 as well as "cook" for more information on cookie matching. Use the
9141 scook_reg() variant for response cookies sent by the server.
9142
9143cook_sub(<name>) <string>
9144 Returns true if any of the request cookies <name> contains at least one of
9145 the strings. See "cook" for more information on cookie matching. Use the
9146 scook_sub() variant for response cookies sent by the server.
9147
Willy Tarreau51539362012-05-08 12:46:28 +02009148cook_val(<name>) <integer>
9149 Returns true if any of the request cookies <name> starts with a number which
9150 matches the values or ranges specified. This may be used to select a server
9151 based on application-specific cookies. Note that an absent cookie does not
9152 match any value. See "cook" for more information on cookie matching. Use the
9153 scook_val() variant for response cookies sent by the server.
9154
Willy Tarreaud63335a2010-02-26 12:56:52 +01009155hdr <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02009156hdr(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01009157 Note: all the "hdr*" matching criteria either apply to all headers, or to a
9158 particular header whose name is passed between parenthesis and without any
9159 space. The header name is not case-sensitive. The header matching complies
9160 with RFC2616, and treats as separate headers all values delimited by commas.
Willy Tarreau185b5c42012-04-26 15:11:51 +02009161 If an occurrence number is specified as the optional second argument, only
9162 this occurrence will be considered. Positive values indicate a position from
9163 the first occurrence, 1 being the first one. Negative values indicate
9164 positions relative to the last one, -1 being the last one. Use the shdr()
9165 variant for response headers sent by the server.
Willy Tarreaud63335a2010-02-26 12:56:52 +01009166
9167 The "hdr" criteria returns true if any of the headers matching the criteria
Willy Tarreau25c1ebc2012-04-25 16:21:44 +02009168 match any of the strings. This can be used to check for exact values. For
Willy Tarreaud63335a2010-02-26 12:56:52 +01009169 instance, checking that "connection: close" is set :
9170
9171 hdr(Connection) -i close
9172
9173hdr_beg <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02009174hdr_beg(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01009175 Returns true when one of the headers begins with one of the strings. See
9176 "hdr" for more information on header matching. Use the shdr_beg() variant for
9177 response headers sent by the server.
9178
9179hdr_cnt <integer>
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009180hdr_cnt(<header>) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01009181 Returns true when the number of occurrence of the specified header matches
9182 the values or ranges specified. It is important to remember that one header
9183 line may count as several headers if it has several values. This is used to
9184 detect presence, absence or abuse of a specific header, as well as to block
9185 request smuggling attacks by rejecting requests which contain more than one
9186 of certain headers. See "hdr" for more information on header matching. Use
9187 the shdr_cnt() variant for response headers sent by the server.
9188
9189hdr_dir <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02009190hdr_dir(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01009191 Returns true when one of the headers contains one of the strings either
9192 isolated or delimited by slashes. This is used to perform filename or
9193 directory name matching, and may be used with Referer. See "hdr" for more
9194 information on header matching. Use the shdr_dir() variant for response
9195 headers sent by the server.
9196
9197hdr_dom <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02009198hdr_dom(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01009199 Returns true when one of the headers contains one of the strings either
9200 isolated or delimited by dots. This is used to perform domain name matching,
9201 and may be used with the Host header. See "hdr" for more information on
9202 header matching. Use the shdr_dom() variant for response headers sent by the
9203 server.
9204
9205hdr_end <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02009206hdr_end(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01009207 Returns true when one of the headers ends with one of the strings. See "hdr"
9208 for more information on header matching. Use the shdr_end() variant for
9209 response headers sent by the server.
9210
9211hdr_ip <ip_address>
Willy Tarreauceb4ac92012-04-28 00:41:46 +02009212hdr_ip(<header>[,<occ>]) <address>
9213 Returns true when one of the headers' values contains an IPv4 or IPv6 address
9214 matching <address>. This is mainly used with headers such as X-Forwarded-For
9215 or X-Client-IP. See "hdr" for more information on header matching. Use the
Willy Tarreaud63335a2010-02-26 12:56:52 +01009216 shdr_ip() variant for response headers sent by the server.
9217
Willy Tarreau0e698542011-09-16 08:32:32 +02009218hdr_len <integer>
Willy Tarreau185b5c42012-04-26 15:11:51 +02009219hdr_len(<header>[,<occ>]) <integer>
Willy Tarreau0e698542011-09-16 08:32:32 +02009220 Returns true when at least one of the headers has a length which matches the
9221 values or ranges specified. This may be used to detect empty or too large
9222 headers. See "hdr" for more information on header matching. Use the
9223 shdr_len() variant for response headers sent by the server.
9224
Willy Tarreaud63335a2010-02-26 12:56:52 +01009225hdr_reg <regex>
Willy Tarreau185b5c42012-04-26 15:11:51 +02009226hdr_reg(<header>[,<occ>]) <regex>
Willy Tarreau04aa6a92012-04-06 18:57:55 +02009227 Returns true it one of the headers matches one of the regular expressions. It
Willy Tarreaud63335a2010-02-26 12:56:52 +01009228 can be used at any time, but it is important to remember that regex matching
9229 is slower than other methods. See also other "hdr_" criteria, as well as
9230 "hdr" for more information on header matching. Use the shdr_reg() variant for
9231 response headers sent by the server.
9232
9233hdr_sub <string>
Willy Tarreau185b5c42012-04-26 15:11:51 +02009234hdr_sub(<header>[,<occ>]) <string>
Willy Tarreaud63335a2010-02-26 12:56:52 +01009235 Returns true when one of the headers contains one of the strings. See "hdr"
9236 for more information on header matching. Use the shdr_sub() variant for
9237 response headers sent by the server.
9238
9239hdr_val <integer>
Willy Tarreau185b5c42012-04-26 15:11:51 +02009240hdr_val(<header>[,<occ>]) <integer>
Willy Tarreaud63335a2010-02-26 12:56:52 +01009241 Returns true when one of the headers starts with a number which matches the
9242 values or ranges specified. This may be used to limit content-length to
9243 acceptable values for example. See "hdr" for more information on header
9244 matching. Use the shdr_val() variant for response headers sent by the server.
9245
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009246http_auth(<userlist>)
9247http_auth_group(<userlist>) <group> [<group>]*
Willy Tarreaud63335a2010-02-26 12:56:52 +01009248 Returns true when authentication data received from the client matches
9249 username & password stored on the userlist. It is also possible to
9250 use http_auth_group to check if the user is assigned to at least one
9251 of specified groups.
9252
9253 Currently only http basic auth is supported.
9254
Willy Tarreau85c27da2011-09-16 07:53:52 +02009255http_first_req
Willy Tarreau7f18e522010-10-22 20:04:13 +02009256 Returns true when the request being processed is the first one of the
9257 connection. This can be used to add or remove headers that may be missing
9258 from some requests when a request is not the first one, or even to perform
9259 some specific ACL checks only on the first request.
9260
Willy Tarreau6a06a402007-07-15 20:15:28 +02009261method <string>
9262 Applies to the method in the HTTP request, eg: "GET". Some predefined ACL
9263 already check for most common methods.
9264
Willy Tarreau6a06a402007-07-15 20:15:28 +02009265path <string>
9266 Returns true when the path part of the request, which starts at the first
9267 slash and ends before the question mark, equals one of the strings. It may be
9268 used to match known files, such as /favicon.ico.
9269
9270path_beg <string>
Willy Tarreau0ba27502007-12-24 16:55:16 +01009271 Returns true when the path begins with one of the strings. This can be used
9272 to send certain directory names to alternative backends.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009273
Willy Tarreau6a06a402007-07-15 20:15:28 +02009274path_dir <string>
9275 Returns true when one of the strings is found isolated or delimited with
9276 slashes in the path. This is used to perform filename or directory name
9277 matching without the risk of wrong match due to colliding prefixes. See also
9278 "url_dir" and "path_sub".
9279
9280path_dom <string>
9281 Returns true when one of the strings is found isolated or delimited with dots
9282 in the path. This may be used to perform domain name matching in proxy
9283 requests. See also "path_sub" and "url_dom".
9284
Willy Tarreaud63335a2010-02-26 12:56:52 +01009285path_end <string>
9286 Returns true when the path ends with one of the strings. This may be used to
9287 control file name extension.
9288
Willy Tarreau0e698542011-09-16 08:32:32 +02009289path_len <integer>
9290 Returns true when the path length matches the values or ranges specified.
9291 This may be used to detect abusive requests for instance.
9292
Willy Tarreau6a06a402007-07-15 20:15:28 +02009293path_reg <regex>
9294 Returns true when the path matches one of the regular expressions. It can be
9295 used any time, but it is important to remember that regex matching is slower
9296 than other methods. See also "url_reg" and all "path_" criteria.
9297
Willy Tarreaud63335a2010-02-26 12:56:52 +01009298path_sub <string>
9299 Returns true when the path contains one of the strings. It can be used to
9300 detect particular patterns in paths, such as "../" for example. See also
9301 "path_dir".
9302
Willy Tarreau0ce3aa02012-04-25 18:46:33 +02009303payload(<offset>,<length>) <string>
9304 Returns true if the block of <length> bytes, starting at byte <offset> in the
9305 request or response buffer (depending on the rule) exactly matches one of the
9306 strings.
9307
9308payload_lv(<offset1>,<length>[,<offset2>])
9309 Returns true if the block whose size is specified at <offset1> for <length>
9310 bytes, and which starts at <offset2> if specified or just after the length in
9311 the request or response buffer (depending on the rule) exactly matches one of
9312 the strings. The <offset2> parameter also supports relative offsets if
9313 prepended with a '+' or '-' sign.
9314
Willy Tarreaud63335a2010-02-26 12:56:52 +01009315req_ver <string>
9316 Applies to the version string in the HTTP request, eg: "1.0". Some predefined
9317 ACL already check for versions 1.0 and 1.1.
9318
9319status <integer>
9320 Applies to the HTTP status code in the HTTP response, eg: "302". It can be
9321 used to act on responses depending on status ranges, for instance, remove
9322 any Location header if the response is not a 3xx.
9323
Willy Tarreau6a06a402007-07-15 20:15:28 +02009324url <string>
9325 Applies to the whole URL passed in the request. The only real use is to match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02009326 "*", for which there already is a predefined ACL. See also "base".
Willy Tarreau6a06a402007-07-15 20:15:28 +02009327
9328url_beg <string>
9329 Returns true when the URL begins with one of the strings. This can be used to
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02009330 check whether a URL begins with a slash or with a protocol scheme. See also
9331 "base_beg".
Willy Tarreau6a06a402007-07-15 20:15:28 +02009332
Willy Tarreau6a06a402007-07-15 20:15:28 +02009333url_dir <string>
9334 Returns true when one of the strings is found isolated or delimited with
9335 slashes in the URL. This is used to perform filename or directory name
9336 matching without the risk of wrong match due to colliding prefixes. See also
9337 "path_dir" and "url_sub".
9338
9339url_dom <string>
9340 Returns true when one of the strings is found isolated or delimited with dots
9341 in the URL. This is used to perform domain name matching without the risk of
9342 wrong match due to colliding prefixes. See also "url_sub".
9343
Willy Tarreaud63335a2010-02-26 12:56:52 +01009344url_end <string>
9345 Returns true when the URL ends with one of the strings. It has very limited
9346 use. "path_end" should be used instead for filename matching.
Willy Tarreau6a06a402007-07-15 20:15:28 +02009347
Willy Tarreauceb4ac92012-04-28 00:41:46 +02009348url_ip <address>
9349 Applies to the IPv4 or IPv6 address specified in the absolute URI in an HTTP
9350 request. It can be used to prevent access to certain resources such as local
9351 network. It is useful with option "http_proxy".
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01009352
Willy Tarreau0e698542011-09-16 08:32:32 +02009353url_len <integer>
9354 Returns true when the url length matches the values or ranges specified. This
9355 may be used to detect abusive requests for instance.
9356
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01009357url_port <integer>
Willy Tarreau0ba27502007-12-24 16:55:16 +01009358 Applies to the port specified in the absolute URI in an HTTP request. It can
9359 be used to prevent access to certain resources. It is useful with option
Willy Tarreau198a7442008-01-17 12:05:32 +01009360 "http_proxy". Note that if the port is not specified in the request, port 80
Willy Tarreau0ba27502007-12-24 16:55:16 +01009361 is assumed.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +01009362
Willy Tarreaud63335a2010-02-26 12:56:52 +01009363url_reg <regex>
9364 Returns true when the URL matches one of the regular expressions. It can be
9365 used any time, but it is important to remember that regex matching is slower
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02009366 than other methods. See also "base_reg", "path_reg" and all "url_" criteria.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01009367
Willy Tarreaud63335a2010-02-26 12:56:52 +01009368url_sub <string>
9369 Returns true when the URL contains one of the strings. It can be used to
9370 detect particular patterns in query strings for example. See also "path_sub".
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01009371
Willy Tarreau25c1ebc2012-04-25 16:21:44 +02009372urlp(<name>) <string>
9373 Note: all "urlp*" matching criteria apply to the first occurrence of the
9374 parameter <name> in the query string. The parameter name is case-sensitive.
9375
9376 The "urlp" matching criteria returns true if the designated URL parameter
9377 matches any of the strings. This can be used to check for exact values.
9378
9379urlp_beg(<name>) <string>
9380 Returns true when the URL parameter "<name>" begins with one of the strings.
9381 This can be used to check whether a URL begins with a slash or with a
9382 protocol scheme.
9383
9384urlp_dir(<name>) <string>
9385 Returns true when the URL parameter "<name>" contains one of the strings
9386 either isolated or delimited with slashes. This is used to perform filename
9387 or directory name matching in a specific URL parameter without the risk of
9388 wrong match due to colliding prefixes. See also "path_dir" and "urlp_sub".
9389
9390urlp_dom(<name>) <string>
9391 Returns true when one of the strings is found isolated or delimited with dots
9392 in the URL parameter "<name>". This is used to perform domain name matching
9393 in a specific URL parameter without the risk of wrong match due to colliding
9394 prefixes. See also "urlp_sub".
9395
9396urlp_end(<name>) <string>
9397 Returns true when the URL parameter "<name>" ends with one of the strings.
9398
9399urlp_ip(<name>) <ip_address>
Willy Tarreauceb4ac92012-04-28 00:41:46 +02009400 Returns true when the URL parameter "<name>" contains an IPv4 or IPv6 address
9401 which matches one of the specified addresses.
Willy Tarreau25c1ebc2012-04-25 16:21:44 +02009402
9403urlp_len(<name>) <integer>
9404 Returns true when the URL parameter "<name>" has a length matching the values
9405 or ranges specified. This is used to detect abusive requests for instance.
9406
9407urlp_reg(<name>) <regex>
9408 Returns true when the URL parameter "<name>" matches one of the regular
9409 expressions. It can be used any time, but it is important to remember that
9410 regex matching is slower than other methods. See also "path_reg" and all
9411 "urlp_" criteria.
9412
9413urlp_sub(<name>) <string>
9414 Returns true when the URL parameter "<name>" contains one of the strings. It
9415 can be used to detect particular patterns in query strings for example. See
9416 also "path_sub" and other "urlp_" criteria.
9417
Willy Tarreaua9fddca2012-07-31 07:51:48 +02009418urlp_val(<name>) <integer>
9419 Returns true when the URL parameter "<name>" starts with a number matching
9420 the values or ranges specified. Note that the absence of the parameter does
9421 not match anything. Integers are unsigned so it is not possible to match
9422 negative data.
9423
Willy Tarreau198a7442008-01-17 12:05:32 +01009424
Willy Tarreauc57f0e22009-05-10 13:12:33 +020094257.6. Pre-defined ACLs
9426---------------------
Willy Tarreauced27012008-01-17 20:35:34 +01009427
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009428Some predefined ACLs are hard-coded so that they do not have to be declared in
9429every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +02009430order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +01009431
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009432ACL name Equivalent to Usage
9433---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009434FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +02009435HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009436HTTP_1.0 req_ver 1.0 match HTTP version 1.0
9437HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +01009438HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
9439HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
9440HTTP_URL_SLASH url_beg / match URL beginning with "/"
9441HTTP_URL_STAR url * match URL equal to "*"
9442LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009443METH_CONNECT method CONNECT match HTTP CONNECT method
9444METH_GET method GET HEAD match HTTP GET or HEAD method
9445METH_HEAD method HEAD match HTTP HEAD method
9446METH_OPTIONS method OPTIONS match HTTP OPTIONS method
9447METH_POST method POST match HTTP POST method
9448METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +02009449RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009450REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +01009451TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009452WAIT_END wait_end wait for end of content analysis
9453---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01009454
Willy Tarreauced27012008-01-17 20:35:34 +01009455
Willy Tarreauc57f0e22009-05-10 13:12:33 +020094567.7. Using ACLs to form conditions
9457----------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +01009458
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009459Some actions are only performed upon a valid condition. A condition is a
9460combination of ACLs with operators. 3 operators are supported :
Willy Tarreauced27012008-01-17 20:35:34 +01009461
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009462 - AND (implicit)
9463 - OR (explicit with the "or" keyword or the "||" operator)
9464 - Negation with the exclamation mark ("!")
Willy Tarreauced27012008-01-17 20:35:34 +01009465
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009466A condition is formed as a disjunctive form:
Willy Tarreauced27012008-01-17 20:35:34 +01009467
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009468 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreauced27012008-01-17 20:35:34 +01009469
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009470Such conditions are generally used after an "if" or "unless" statement,
9471indicating when the condition will trigger the action.
Willy Tarreauced27012008-01-17 20:35:34 +01009472
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009473For instance, to block HTTP requests to the "*" URL with methods other than
9474"OPTIONS", as well as POST requests without content-length, and GET or HEAD
9475requests with a content-length greater than 0, and finally every request which
9476is not either GET/HEAD/POST/OPTIONS !
Willy Tarreauced27012008-01-17 20:35:34 +01009477
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009478 acl missing_cl hdr_cnt(Content-length) eq 0
9479 block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
9480 block if METH_GET HTTP_CONTENT
9481 block unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreauced27012008-01-17 20:35:34 +01009482
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009483To select a different backend for requests to static contents on the "www" site
9484and to every request on the "img", "video", "download" and "ftp" hosts :
Willy Tarreauced27012008-01-17 20:35:34 +01009485
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009486 acl url_static path_beg /static /images /img /css
9487 acl url_static path_end .gif .png .jpg .css .js
9488 acl host_www hdr_beg(host) -i www
9489 acl host_static hdr_beg(host) -i img. video. download. ftp.
Willy Tarreauced27012008-01-17 20:35:34 +01009490
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009491 # now use backend "static" for all static-only hosts, and for static urls
9492 # of host "www". Use backend "www" for the rest.
9493 use_backend static if host_static or host_www url_static
9494 use_backend www if host_www
Willy Tarreauced27012008-01-17 20:35:34 +01009495
Willy Tarreau95fa4692010-02-01 13:05:50 +01009496It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
9497expressions that are built on the fly without needing to be declared. They must
9498be enclosed between braces, with a space before and after each brace (because
Jamie Gloudon801a0a32012-08-25 00:18:33 -04009499the braces must be seen as independent words). Example :
Willy Tarreau95fa4692010-02-01 13:05:50 +01009500
9501 The following rule :
9502
9503 acl missing_cl hdr_cnt(Content-length) eq 0
9504 block if METH_POST missing_cl
9505
9506 Can also be written that way :
9507
9508 block if METH_POST { hdr_cnt(Content-length) eq 0 }
9509
9510It is generally not recommended to use this construct because it's a lot easier
9511to leave errors in the configuration when written that way. However, for very
9512simple rules matching only one source IP address for instance, it can make more
9513sense to use them than to declare ACLs with random names. Another example of
9514good use is the following :
9515
9516 With named ACLs :
9517
9518 acl site_dead nbsrv(dynamic) lt 2
9519 acl site_dead nbsrv(static) lt 2
9520 monitor fail if site_dead
9521
9522 With anonymous ACLs :
9523
9524 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
9525
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009526See section 4.2 for detailed help on the "block" and "use_backend" keywords.
Willy Tarreauced27012008-01-17 20:35:34 +01009527
Willy Tarreau5764b382007-11-30 17:46:49 +01009528
Willy Tarreaub937b7e2010-01-12 15:27:54 +010095297.8. Pattern extraction
9530-----------------------
9531
9532The stickiness features relies on pattern extraction in the request and
9533response. Sometimes the data needs to be converted first before being stored,
9534for instance converted from ASCII to IP or upper case to lower case.
9535
9536All these operations of data extraction and conversion are defined as
9537"pattern extraction rules". A pattern rule always has the same format. It
9538begins with a single pattern fetch word, potentially followed by a list of
9539arguments within parenthesis then an optional list of transformations. As
9540much as possible, the pattern fetch functions use the same name as their
9541equivalent used in ACLs.
9542
9543The list of currently supported pattern fetch functions is the following :
9544
Willy Tarreaud4c33c82013-01-07 21:59:07 +01009545 always_false
9546 Always returns the boolean "false" value.
9547
9548 always_true
9549 Always returns the boolean "true" value.
9550
Willy Tarreau1a7eca12013-01-07 22:38:03 +01009551 avg_queue([<backend>])
9552 Returns the total number of queued connections of the designated
9553 backend divided by the number of active servers. The current
9554 backend is used if no backend is specified. This is very similar
9555 to "queue" except that the size of the farm is considered, in
9556 order to give a more accurate measurement of the time it may
9557 take for a new connection to be processed. The main usage is
9558 with ACL to return a sorry page to new users when it becomes
9559 certain they will get a degraded service, or to pass to the
9560 backend servers in a header so that they decide to work in
9561 degraded mode or to disable some functions to speed up the
9562 processing a bit. Note that in the event there would not be
9563 any active server anymore, we would consider twice the number
9564 of queued connections as the measured value. This is a fair
9565 estimate, as we expect one server to get back soon anyway, but
9566 we still prefer to send new traffic to another backend if in
9567 better shape. See also the "queue", "be_conn", and
9568 "be_sess_rate" sample fetches.
9569
Willy Tarreaua7ad50c2012-04-29 15:39:40 +02009570 base This returns the concatenation of the first Host header and the
9571 path part of the request, which starts at the first slash and
9572 ends before the question mark. It can be useful in virtual
9573 hosted environments to detect URL abuses as well as to improve
9574 shared caches efficiency. Using this with a limited size stick
9575 table also allows one to collect statistics about most commonly
9576 requested objects by host/path.
9577
Willy Tarreauab1f7b72012-12-09 13:38:54 +01009578 base32 This returns a 32-bit hash of the value returned by the "base"
9579 fetch method above. This is useful to track per-URL activity on
9580 high traffic sites without having to store all URLs. Instead a
9581 shorter hash is stored, saving a lot of memory. The output type
9582 is an unsigned integer.
9583
Willy Tarreau4a550602012-12-09 14:53:32 +01009584 base32+src This returns the concatenation of the base32 fetch above and the
9585 src fetch below. The resulting type is of type binary, with a
9586 size of 8 or 20 bytes depending on the source address family.
9587 This can be used to track per-IP, per-URL counters.
9588
Willy Tarreau1a7eca12013-01-07 22:38:03 +01009589 be_conn([<backend>])
9590 Returns the number of currently established connections on the
9591 the backend, possibly including the connection being evaluated.
9592 If no backend name is specified, the current one is used. But it
9593 is also possible to check another backend. It can be used to use
9594 a specific farm when the nominal one is full. See also the
9595 "fe_conn", "queue" and "be_sess_rate" criteria.
9596
9597 be_id Returns an integer containing the current backend's id.
9598
9599 be_sess_rate([<backend>])
9600 Returns an integer value corresponding to the sessions creation
9601 rate on the backend, in number of new sessions per second. This
9602 is used with ACLs to switch to an alternate backend when an
9603 expensive or fragile one reaches too high a session rate, or to
9604 limit abuse of service (eg. prevent sucking of an online
9605 dictionary). It can also be useful to add this element to logs
9606 using a log-format directive.
9607
9608 connslots([<backend>])
9609 Returns an integer value corresponding to the number of
9610 connection slots still available in the backend, by totalizing
9611 the maximum amount of connections on all servers and the maximum
9612 queue size. This is only used with ACLs. See the ACL "connslots"
9613 keyword description for more information on possible caveats.
9614
Willy Tarreau409bcde2013-01-08 00:31:00 +01009615 cook([<name>])
9616 This extracts the last occurrence of the cookie name <name> on a
9617 "Cookie" header line from the request, and returns its value as
9618 string. If no name is specified, the first cookie value is
9619 returned.
9620
9621 cookie([<name>])
Willy Tarreaud4c33c82013-01-07 21:59:07 +01009622 This extracts the last occurrence of the cookie name <name> on a
9623 "Cookie" header line from the request, or a "Set-Cookie" header
Willy Tarreau409bcde2013-01-08 00:31:00 +01009624 from the response, and returns its value as a string. A typical
9625 use is to get multiple clients sharing a same profile use the
9626 same server. This can be similar to what "appsession" does with
9627 the "request-learn" statement, but with support for multi-peer
9628 synchronization and state keeping across restarts. If no name is
9629 specified, the first cookie value is returned.
Willy Tarreaud4c33c82013-01-07 21:59:07 +01009630
9631 See also : "appsession"
David du Colombier9a6d3c92011-03-17 10:40:24 +01009632
Willy Tarreau409bcde2013-01-08 00:31:00 +01009633 cook_cnt([<name>])
9634 Returns an integer value representing the number of occurrences of
9635 the cookie <name> in the request, or all cookies if <name> is not
9636 specified.
9637
9638 cook_val([<name>])
9639 This extracts the last occurrence of the cookie name <name> on a
9640 "Cookie" header line from the request, and converts its value to
9641 an integer which is returned. If no name is specified, the first
9642 cookie value is returned.
9643
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009644 dst This is the destination IPv4 address of the session on the
9645 client side, which is the address the client connected to.
9646 It can be useful when running in transparent mode. It is of
David du Colombier9a6d3c92011-03-17 10:40:24 +01009647 type IPv4 and works on both IPv4 and IPv6 tables.
9648 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent,
9649 according to RFC 4291.
9650
Willy Tarreau0ccb7442013-01-07 22:54:17 +01009651 dst_conn
9652 Returns an integer value corresponding to the number of
9653 currently established connections on the same socket including
9654 the one being evaluated. It is normally used with ACLs but can
9655 as well be used to pass the information to servers in an HTTP
9656 header or in logs. See also "fe_conn" and "dst_conn".
9657
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009658 dst_port This is the destination TCP port of the session on the client
9659 side, which is the port the client connected to. This might be
9660 used when running in transparent mode or when assigning dynamic
9661 ports to some clients for a whole application session. It is of
9662 type integer and only works with such tables.
9663
Willy Tarreaud6896bc2013-01-07 22:48:29 +01009664 fe_conn([<frontend>])
9665 Returns the number of currently established connections on the
9666 the frontend, possibly including the connection being evaluated.
9667 If no frontend name is specified, the current one is used. But
9668 it is also possible to check another frontend. It can be used to
9669 return a sorry page before hard-blocking, or to use a specific
9670 backend to drain new requests when the farm is considered full.
9671 This is mostly used with ACLs but can also be used to pass some
9672 statistics to servers in HTTP headers. See also the "dst_conn",
9673 "be_conn", "fe_sess_rate" criteria.
9674
9675 fe_id Returns an integer containing the current frontend's id.
9676
9677 fe_sess_rate([<frontend>])
9678 Returns an integer value corresponding to the sessions creation
9679 rate on the frontend, in number of new sessions per second. This
9680 is used with ACLs to limit the incoming session rate to an
9681 acceptable range in order to prevent abuse of service at the
9682 earliest moment. It can also be useful to add this element to
9683 logs using a log-format directive.
9684
Willy Tarreau185b5c42012-04-26 15:11:51 +02009685 hdr(<name>[,<occ>])
9686 This extracts the last occurrence of header <name> in an HTTP
9687 request. Optionally, a specific occurrence might be specified as
9688 a position number. Positive values indicate a position from the
9689 first occurrence, with 1 being the first one. Negative values
9690 indicate positions relative to the last one, with -1 being the
9691 last one. A typical use is with the X-Forwarded-For header once
Willy Tarreaue428fb72011-12-16 21:50:30 +01009692 converted to IP, associated with an IP stick-table.
Willy Tarreau4a568972010-05-12 08:08:50 +02009693
Willy Tarreau409bcde2013-01-08 00:31:00 +01009694 hdr_cnt([<name>])
9695 Returns an integer value representing the number of occurrences
9696 of request header field name <name>, or the total number of
9697 header fields if <name> is not specified.
9698
9699 hdr_ip([<name>[,<occ>]])
9700 This extracts the last occurrence of header <name> in an HTTP
9701 request, converts it to an IPv4 or IPv6 address and returns this
9702 address. Optionally, a specific occurrence might be specified as
9703 a position number. Positive values indicate a position from the
9704 first occurrence, with 1 being the first one. Negative values
9705 indicate positions relative to the last one, with -1 being the
9706 last one. A typical use is with the X-Forwarded-For header.
9707
9708 hdr_val([<name>[,<occ>]])
9709 This extracts the last occurrence of header <name> in an HTTP
9710 request, and converts it to an integer value. Optionally, a
9711 specific occurrence might be specified as a position number.
9712 Positive values indicate a position from the first occurrence,
9713 with 1 being the first one. Negative values indicate positions
9714 relative to the last one, with -1 being the last one. A typical
9715 use is with the X-Forwarded-For header.
9716
9717 http_auth(<userlist>)
9718 http_auth_group(<userlist>)
9719 Returns a boolean indicating whether the authentication data
9720 received from the client match a username & password stored in
9721 the specified userlist. These fetch functions are not really
9722 useful outside of ACLs.
9723
9724 http_first_req
9725 Returns true when the request being processed is the first one
9726 of the connection. This can be used to add or remove headers
9727 that may be missing from some requests when a request is not the
9728 first one, or to help grouping requests in the logs.
9729
9730 method
9731 Returns an integer value corresponding to the to the method in
9732 the HTTP request. For example, "GET" equals 1 (check sources to
9733 establish the matching). Value 9 means "other method" and may be
9734 converted to a string extracted from the stream. This should not
9735 be used directly, this is only meant to be used from ACLs.
9736
Willy Tarreau1a7eca12013-01-07 22:38:03 +01009737 nbsrv([<backend>])
9738 Returns an integer value corresponding to the number of usable
9739 servers of either the current backend or the named backend. This
9740 is mostly used with ACLs but can also be useful when added to
9741 logs.
9742
Willy Tarreau6812bcf2012-04-29 09:28:50 +02009743 path This extracts the request's URL path (without the host part). A
9744 typical use is with prefetch-capable caches, and with portals
9745 which need to aggregate multiple information from databases and
9746 keep them in caches. Note that with outgoing caches, it would be
9747 wiser to use "url" instead.
9748
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009749 payload(<offset>,<length>)
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009750 This extracts a binary block of <length> bytes, and starting
9751 at bytes <offset> in the buffer of request or response (request
9752 on "stick on" or "stick match" or response in on "stick store
9753 response").
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009754
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009755 payload_lv(<offset1>,<length>[,<offset2>])
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009756 This extracts a binary block. In a first step the size of the
9757 block is read from response or request buffer at <offset>
9758 bytes and considered coded on <length> bytes. In a second step
9759 data of the block are read from buffer at <offset2> bytes
9760 (by default <lengthoffset> + <lengthsize>).
9761 If <offset2> is prefixed by '+' or '-', it is relative to
9762 <lengthoffset> + <lengthsize> else it is absolute.
9763 Ex: see SSL session id example in "stick table" chapter.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009764
Willy Tarreau1a7eca12013-01-07 22:38:03 +01009765 queue([<backend>])
9766 Returns the total number of queued connections of the designated
9767 backend, including all the connections in server queues. If no
9768 backend name is specified, the current one is used, but it is
9769 also possible to check another one. This is useful with ACLs
9770 or to pass statistics to backend servers.
9771
Willy Tarreaud4c33c82013-01-07 21:59:07 +01009772 rdp_cookie(<name>)
9773 This extracts the value of the rdp cookie <name> as a string
9774 and uses this value to match. This enables implementation of
9775 persistence based on the mstshash cookie. This is typically
9776 done if there is no msts cookie present.
9777
9778 This differs from "balance rdp-cookie" in that any balancing
9779 algorithm may be used and thus the distribution of clients
9780 to backend servers is not linked to a hash of the RDP
9781 cookie. It is envisaged that using a balancing algorithm
9782 such as "balance roundrobin" or "balance leastconnect" will
9783 lead to a more even distribution of clients to backend
9784 servers than the hash used by "balance rdp-cookie".
9785
9786 Example :
9787 listen tse-farm
9788 bind 0.0.0.0:3389
9789 # wait up to 5s for an RDP cookie in the request
9790 tcp-request inspect-delay 5s
9791 tcp-request content accept if RDP_COOKIE
9792 # apply RDP cookie persistence
9793 persist rdp-cookie
9794 # Persist based on the mstshash cookie
9795 # This is only useful makes sense if
9796 # balance rdp-cookie is not used
9797 stick-table type string size 204800
9798 stick on rdp_cookie(mstshash)
9799 server srv1 1.1.1.1:3389
9800 server srv1 1.1.1.2:3389
9801
9802 See also : "balance rdp-cookie", "persist rdp-cookie",
9803 "tcp-request" and the "req_rdp_cookie" ACL.
9804
9805 rdp_cookie_cnt([name])
9806 Tries to parse the request buffer as RDP protocol, then returns
9807 an integer corresponding to the number of RDP cookies found. If
9808 an optional cookie name is passed, only cookies matching this
9809 name are considered. This is mostly used in ACL.
9810
9811 rep_ssl_hello_type
9812 Returns an integer value containing the type of the SSL hello
9813 message found in the response buffer. Note that this only
9814 applies to raw contents found in the response buffer and not to
9815 contents deciphered via an SSL data layer, so this will not work
9816 with "server" lines having the "ssl" option. This is mostly used
9817 in ACL.
9818
9819 req_len Returns an integer value corresponding to the number of bytes
9820 present in the request buffer. This is mostly used in ACL.
9821
Willy Tarreau409bcde2013-01-08 00:31:00 +01009822 req_proto_http
9823 Returns true when data in the request buffer look like HTTP and
9824 correctly parses as such. It is the same parser as the common
9825 HTTP request parser which is used so there should be no
9826 surprises. This test may be used to report the protocol in TCP
9827 logs.
9828
Willy Tarreaud4c33c82013-01-07 21:59:07 +01009829 req_ssl_hello_type
9830 Returns an integer value containing the type of the SSL hello
9831 message found in the request buffer. Note that this only applies
9832 to raw contents found in the request buffer and not to contents
9833 deciphered via an SSL data layer, so this will not work with
9834 "bind" lines having the "ssl" option. This is mostly used in
9835 ACL.
9836
9837 req_ssl_sni Returns a string containing the value of the Server Name TLS
9838 extension sent by a client in a TLS stream passing through the
9839 request buffer. Note that this only applies to raw contents
9840 found in the request buffer and not to contents deciphered via
9841 an SSL data layer, so this will not work with "bind" lines
9842 having the "ssl" option. This is mostly used in ACL.
9843
9844 req_ssl_ver Returns an integer value containing the version of the SSL/TLS
9845 protocol of a stream present in the request buffer. The value is
9846 composed of the major version multiplied by 65536, added to the
9847 minor version. Note that this only applies to raw contents found
9848 in the request buffer and not to contents deciphered via an SSL
9849 data layer, so this will not work with "bind" lines having the
9850 "ssl" option. This is mostly used in ACL.
9851
Willy Tarreau409bcde2013-01-08 00:31:00 +01009852 req_ver Returns the version string from the HTTP request, for example
9853 "1.1". This can be useful for logs, but is mostly there for ACL.
9854
9855 resp_ver Returns the version string from the HTTP response, for example
9856 "1.1". This can be useful for logs, but is mostly there for ACL.
9857
Willy Tarreau281c7992013-01-08 01:23:27 +01009858 sc1_bytes_in_rate
9859 sc2_bytes_in_rate
9860 Returns the average client-to-server bytes rate from the
9861 currently tracked counters, measured in amount of bytes over the
9862 period configured in the table. See also src_bytes_in_rate.
9863
9864 sc1_bytes_out_rate
9865 sc2_bytes_out_rate
9866 Returns the average server-to-client bytes rate from the
9867 currently tracked counters, measured in amount of bytes over the
9868 period configured in the table. See also src_bytes_out_rate.
9869
9870 sc1_clr_gpc0
9871 sc2_clr_gpc0
9872 Clears the first General Purpose Counter associated to the
9873 currently tracked counters, and returns its previous value.
9874 This is only useful when used by ACLs.
9875
9876 sc1_conn_cnt
9877 sc2_conn_cnt
9878 Returns the cumulated number of incoming connections from
9879 currently tracked counters. See also src_conn_cnt.
9880
9881 sc1_conn_cur
9882 sc2_conn_cur
9883 Returns the current amount of concurrent connections tracking
9884 the same tracked counters. This number is automatically
9885 incremented when tracking begins and decremented when tracking
9886 stops. See also src_conn_cur.
9887
9888 sc1_conn_rate
9889 sc2_conn_rate
9890 Returns the average connection rate from the currently tracked
9891 counters, measured in amount of connections over the period
9892 configured in the table. See also src_conn_rate.
9893
9894 sc1_get_gpc0
9895 sc2_get_gpc0
9896 Returns the value of the first General Purpose Counter
9897 associated to the currently tracked counters. See also
9898 src_get_gpc0 and sc1/sc2_inc_gpc0.
9899
9900 sc1_http_err_cnt
9901 sc2_http_err_cnt
9902 Returns the cumulated number of HTTP errors from the currently
9903 tracked counters. This includes the both request errors and 4xx
9904 error responses. See also src_http_err_cnt.
9905
9906 sc1_http_err_rate
9907 sc2_http_err_rate
9908 Returns the average rate of HTTP errors from the currently
9909 tracked counters, measured in amount of errors over the period
9910 configured in the table. This includes the both request errors
9911 and 4xx error responses. See also src_http_err_rate.
9912
9913 sc1_http_req_cnt
9914 sc2_http_req_cnt
9915 Returns the cumulated number of HTTP requests from the currently
9916 tracked counters. This includes every started request, valid or
9917 not. See also src_http_req_cnt.
9918
9919 sc1_http_req_rate
9920 sc2_http_req_rate
9921 Returns the average rate of HTTP requests from the currently
9922 tracked counters, measured in amount of requests over the period
9923 configured in the table. This includes every started request,
9924 valid or not. See also src_http_req_rate.
9925
9926 sc1_inc_gpc0
9927 sc2_inc_gpc0
9928 Increments the first General Purpose Counter associated to the
9929 currently tracked counters, and returns its new value. This is
9930 only useful when used by ACLs.
9931
9932 sc1_kbytes_in
9933 sc2_kbytes_in
9934 Returns the amount of client-to-server data from the currently
9935 tracked counters, measured in kilobytes over the period
9936 configured in the table. The value being stored as a 32-bit
9937 integer, it wraps at 4 terabytes. See also src_kbytes_in.
9938
9939 sc1_kbytes_out
9940 sc2_kbytes_out
9941 Returns the amount of server-to-client data from the currently
9942 tracked counters, measured in kilobytes over the period
9943 configured in the table. The value being stored as a 32-bit
9944 integer, it wraps at 4 terabytes. See also src_kbytes_out.
9945
9946 sc1_sess_cnt
9947 sc2_sess_cnt
9948 Returns the cumulated number of incoming connections that were
9949 transformed into sessions, which means that they were accepted
9950 by a "tcp-request connection" rule, from the currently tracked
9951 counters. A backend may count more sessions than connections
9952 because each connection could result in many backend sessions if
9953 some HTTP keep-alive is performed over the connection with the
9954 client. See also src_sess_cnt.
9955
9956 sc1_sess_rate
9957 sc2_sess_rate
9958 Returns the average session rate from the currently tracked
9959 counters, measured in amount of sessions over the period
9960 configured in the table. A session is a connection that got past
9961 the early "tcp-request connection" rules. A backend may count
9962 more sessions than connections because each connection could
9963 result in many backend sessions if some HTTP keep-alive is
9964 performed over the connection with the client. See also
9965 src_sess_rate.
9966
9967 sc1_trackers
9968 sc2_trackers
9969 Returns the current amount of concurrent connections tracking
9970 the same tracked counters. This number is automatically
9971 incremented when tracking begins and decremented when tracking
9972 stops. It differs from sc1_conn_cur in that it does not rely on
9973 any stored information but on the table's reference count (the
9974 "use" value which is returned by "show table" on the CLI). This
9975 may sometimes be more suited for layer7 tracking. It can be used
9976 to tell a server how many concurrent connections there are from
9977 a given address for example.
9978
Willy Tarreau409bcde2013-01-08 00:31:00 +01009979 scook([<name>])
9980 This extracts the last occurrence of the cookie name <name> on a
9981 "Set-Cookie" header line from the response, and returns its
9982 value as string. If no name is specified, the first cookie value
9983 is returned.
9984
9985 scook_cnt([<name>])
9986 Returns an integer value representing the number of occurrences of
9987 the cookie <name> in the response, or all cookies if <name> is not
9988 specified.
9989
9990 scook_val([<name>])
9991 This extracts the last occurrence of the cookie name <name> on a
9992 "Set-Cookie" header line from the response, and converts its
9993 value to an integer which is returned. If no name is specified,
9994 the first cookie value is returned.
9995
Willy Tarreaud4c33c82013-01-07 21:59:07 +01009996 set-cookie(<name>)
9997 This fetch function is deprecated and has been superseded by the
9998 "cookie" fetch which is capable of handling both requests and
9999 responses. This keyword will disappear soon.
10000
10001 This extracts the last occurrence of the cookie name <name> on a
10002 "Set-Cookie" header line from the response and uses the
10003 corresponding value to match. This can be comparable to what
10004 "appsession" does with default options, but with support for
10005 multi-peer synchronization and state keeping across restarts.
10006
10007 See also : "appsession"
10008
Willy Tarreau409bcde2013-01-08 00:31:00 +010010009 shdr(<name>[,<occ>])
10010 This extracts the last occurrence of header <name> in an HTTP
10011 response. Optionally, a specific occurrence might be specified
10012 as a position number. Positive values indicate a position from
10013 the first occurrence, with 1 being the first one. Negative
10014 values indicate positions relative to the last one, with -1
10015 being the last one. This can be useful to learn some data into
10016 a stick-table.
10017
10018 shdr_cnt([<name>])
10019 Returns an integer value representing the number of occurrences
10020 of response header field name <name>, or the total number of
10021 header fields if <name> is not specified.
10022
10023 shdr_ip([<name>[,<occ>]])
10024 This extracts the last occurrence of header <name> in an HTTP
10025 response, convert it to an IPv4 or IPv6 address and returns this
10026 address. Optionally, a specific occurrence might be specified as
10027 a position number. Positive values indicate a position from the
10028 first occurrence, with 1 being the first one. Negative values
10029 indicate positions relative to the last one, with -1 being the
10030 last one. This can be useful to learn some data into a stick
10031 table.
10032
10033 shdr_val([<name>[,<occ>]])
10034 This extracts the last occurrence of header <name> in an HTTP
10035 response, and converts it to an integer value. Optionally, a
10036 specific occurrence might be specified as a position number.
10037 Positive values indicate a position from the first occurrence,
10038 with 1 being the first one. Negative values indicate positions
10039 relative to the last one, with -1 being the last one. This can
10040 be useful to learn some data into a stick table.
10041
Willy Tarreau0ccb7442013-01-07 22:54:17 +010010042 so_id Returns an integer containing the listening socket's id.
10043
Willy Tarreaud4c33c82013-01-07 21:59:07 +010010044 src This is the source IPv4 address of the client of the session.
10045 It is of type IPv4 and works on both IPv4 and IPv6 tables.
10046 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent,
10047 according to RFC 4291.
10048
Willy Tarreau281c7992013-01-08 01:23:27 +010010049 src_bytes_in_rate([<table>])
10050 Returns the average bytes rate from the connection's source IPv4
10051 address in the current proxy's stick-table or in the designated
10052 stick-table, measured in amount of bytes over the period
10053 configured in the table. If the address is not found, zero is
10054 returned. See also sc1/sc2_bytes_in_rate.
10055
10056 src_bytes_out_rate([<table>])
10057 Returns the average bytes rate to the connection's source IPv4
10058 address in the current proxy's stick-table or in the designated
10059 stick-table, measured in amount of bytes over the period
10060 configured in the table. If the address is not found, zero is
10061 returned. See also sc1/sc2_bytes_out_rate.
10062
10063 src_clr_gpc0([<table>])
10064 Clears the first General Purpose Counter associated to the
10065 connection's source IPv4 address in the current proxy's
10066 stick-table or in the designated stick-table, and returns its
10067 previous value. This is only useful when used by ACLs.
10068
10069 src_conn_cnt([<table>])
10070 Returns the cumulated number of connections initiated from the
10071 current connection's source IPv4 address in the current proxy's
10072 stick-table or in the designated stick-table. If the address is
10073 not found, zero is returned. See also sc1/sc2_conn_cnt.
10074
10075 src_conn_cur([<table>])
10076 Returns the current amount of concurrent connections initiated
10077 from the current connection's source IPv4 address in the current
10078 proxy's stick-table or in the designated stick-table. If the
10079 address is not found, zero is returned. See also
10080 sc1/sc2_conn_cur.
10081
10082 src_conn_rate([<table>])
10083 Returns the average connection rate from the connection's source
10084 IPv4 address in the current proxy's stick-table or in the
10085 designated stick-table, measured in amount of connections over
10086 the period configured in the table. If the address is not found,
10087 zero is returned. See also sc1/sc2_conn_rate.
10088
10089 src_get_gpc0([<table>])
10090 Returns the value of the first General Purpose Counter
10091 associated to the connection's source IPv4 address in the
10092 current proxy's stick-table or in the designated stick-table. If
10093 the address is not found, zero is returned. See also
10094 sc1/sc2_get_gpc0 and src_inc_gpc0.
10095
10096 src_http_err_cnt([<table>])
10097 Returns the cumulated number of HTTP errors from the current
10098 connection's source IPv4 address in the current proxy's
10099 stick-table or in the designated stick-table. This includes the
10100 both request errors and 4xx error responses. If the address is
10101 not found, zero is returned. See also sc1/sc2_http_err_cnt.
10102
10103 src_http_err_rate([<table>])
10104 Returns the average rate of HTTP errors from the current
10105 connection's source IPv4 address in the current proxy's
10106 stick-table or in the designated stick- table, measured in
10107 amount of errors over the period configured in the table. This
10108 includes the both request errors and 4xx error responses. If the
10109 address is not found, zero is returned. See also
10110 sc1/sc2_http_err_rate.
10111
10112 src_http_req_cnt([<table>])
10113 Returns the cumulated number of HTTP requests from the current
10114 connection's source IPv4 address in the current proxy's
10115 stick-table or in the designated stick-table. This includes
10116 every started request, valid or not. If the address is not
10117 found, zero is returned. See also sc1/sc2_http_req_cnt.
10118
10119 src_http_req_rate([<table>])
10120 Returns the average rate of HTTP requests from the current
10121 connection's source IPv4 address in the current proxy's
10122 stick-table or in the designated stick-table, measured in amount
10123 of requests over the period configured in the table. This
10124 includes every started request, valid or not. If the address is
10125 not found, zero is returned. See also sc1/sc2_http_req_rate.
10126
10127 src_inc_gpc0([<table>])
10128 Increments the first General Purpose Counter associated to the
10129 connection's source IPv4 address in the current proxy's
10130 stick-table or in the designated stick-table, and returns its
10131 new value. This is only useful when used by ACLs.
10132
10133 src_kbytes_in([<table>])
10134 Returns the amount of data received from the connection's source
10135 IPv4 address in the current proxy's stick-table or in the
10136 designated stick-table, measured in kilobytes over the period
10137 configured in the table. If the address is not found, zero is
10138 returned. The value being stored as a 32-bit integer, it wraps
10139 at 4 terabytes. See also sc1/sc2_kbytes_in.
10140
10141 src_kbytes_out([<table>])
10142 Returns the amount of data sent to the connection's source IPv4
10143 address in the current proxy's stick-table or in the designated
10144 stick-table, measured in kilobytes over the period configured in
10145 the table. If the address is not found, zero is returned. The
10146 value being stored as a 32-bit integer, it wraps at 4 terabytes.
10147 See also sc1/sc2_kbytes_out.
10148
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020010149 src_port This is the source TCP port of the session on the client side,
10150 which is the port the client connected from. It is very unlikely
10151 that this function will be useful but it's available at no cost.
10152 It is of type integer and only works with such tables.
10153
Willy Tarreau281c7992013-01-08 01:23:27 +010010154 src_sess_cnt([<table>])
10155 Returns the cumulated number of connections initiated from the
10156 current connection's source IPv4 address in the current proxy's
10157 stick-table or in the designated stick-table, that were
10158 transformed into sessions, which means that they were accepted
10159 by "tcp-request" rules. If the address is not found, zero is
10160 returned. See also sc1/sc2_sess_cnt.
10161
10162 src_sess_rate([<table>])
10163 Returns the average session rate from the connection's source
10164 IPv4 address in the current proxy's stick-table or in the
10165 designated stick-table, measured in amount of sessions over the
10166 period configured in the table. A session is a connection that
10167 got past the early "tcp-request" rules. If the address is not
10168 found, zero is returned. See also sc1/sc2_sess_rate.
10169
10170 src_updt_conn_cnt([<table>])
10171 Creates or updates the entry associated to the source IPv4
10172 address in the current proxy's stick-table or in the designated
10173 stick-table. This is only useful when used by ACLs.
10174
Willy Tarreau1a7eca12013-01-07 22:38:03 +010010175 srv_conn(<backend>/<server>)
10176 Returns an integer value corresponding to the number of
10177 currently established connections on this server, possibly
10178 including the connection being evaluated. It is only used with
10179 ACLs.
10180
10181 srv_id Returns an integer containing the server's id when processing
10182 the response. While it's almost only used with ACLs, it may be
10183 used for logging or debugging.
10184
10185 srv_is_up([<backend>/]<server>)
10186 Returns a the boolean TRUE value when the designated server is
10187 UP, and false when it is either DOWN or in maintenance mode. If
10188 <backend> is omitted, then the server is looked up in the
10189 current backend. It is almost only used with ACLs.
10190
10191 srv_sess_rate(<backend>/<server>)
10192 Returns an integer corresponding to the sessions creation rate
10193 on the server, in number of new sessions per second. This is
10194 used with ACLs but may make sense with logs too.
10195
Emeric Brun2525b6b2012-10-18 15:59:43 +020010196 ssl_c_ca_err Returns the ID of the first error detected during verify of the
10197 client certificate at depth > 0, or 0 if no error was detected.
10198
10199 ssl_c_ca_err_depth
10200 Returns the depth of the first error detected during verify. If
10201 no error is encountered in the CA chain, zero is returned.
10202
10203 ssl_c_err Returns the ID of the first error detected during verify of the
10204 client certificate at depth == 0, or 0 if no errors.
10205
Emeric Brun87855892012-10-17 17:39:35 +020010206 ssl_c_i_dn[(entry[,occ])]
10207 If no entry specified, returns the full distinguished name of
10208 the issuer of the certificate presented by the client when
10209 the incoming connection was made over an SSL/TLS transport
Baptiste Assmannea3e73b2013-02-02 23:47:49 +010010210 layer. Otherwise returns the value of the first given entry
10211 found from the beginning of the DN. If a positive/negative
Emeric Brun87855892012-10-17 17:39:35 +020010212 occurrence number is specified as the optional second argument,
10213 it returns the value of the nth given entry found from the
10214 beginning/end of the DN. For instance to retrieve the common
10215 name ssl_c_i_dn(CN) and the second organization unit
10216 ssl_c_i_dn(OU,2).
10217
Emeric Brun7f56e742012-10-19 18:15:40 +020010218 ssl_c_key_alg
10219 Returns the name of the algorithm used to generate the key of
10220 the certificate presented by the client when the incoming
10221 connection was made over an SSL/TLS transport layer.
10222
Emeric Brunce5ad802012-10-22 14:11:22 +020010223 ssl_c_notafter
10224 Returns the end date presented by the client as a formatted
10225 string YYMMDDhhmmss[Z] when the incoming connection was made
10226 over an SSL/TLS transport layer.
10227
10228 ssl_c_notbefore
10229 Returns the start date presented by the client as a formatted
10230 string YYMMDDhhmmss[Z] when the incoming connection was made
10231 over an SSL/TLS transport layer.
10232
Emeric Brun87855892012-10-17 17:39:35 +020010233 ssl_c_s_dn[(entry[,occ])]
10234 If no entry specified, returns the full distinguished name of
10235 the subject of the certificate presented by the client when
10236 the incoming connection was made over an SSL/TLS transport
Baptiste Assmannea3e73b2013-02-02 23:47:49 +010010237 layer. Otherwise returns the value of the first given entry
10238 found from the beginning of the DN. If a positive/negative
Emeric Brun87855892012-10-17 17:39:35 +020010239 occurrence number is specified as the optional second argument,
10240 it returns the value of the nth given entry found from the
10241 beginning/end of the DN. For instance to retrieve the common
10242 name ssl_c_s_dn(CN) and the second organization unit
10243 ssl_c_s_dn(OU,2).
10244
Willy Tarreau8d598402012-10-22 17:58:39 +020010245 ssl_c_serial Returns the serial of the certificate presented by the client
10246 when the incoming connection was made over an SSL/TLS transport
10247 layer.
10248
Emeric Brun7f56e742012-10-19 18:15:40 +020010249 ssl_c_sig_alg
10250 Returns the name of the algorithm used to sign the certificate
10251 presented by the client when the incoming connection was made
10252 over an SSL/TLS transport layer.
10253
Emeric Brun9143d372012-12-20 15:44:16 +010010254 ssl_c_used
10255 Returns 1 if current SSL session use a client certificate,
10256 otherwise 0. See also "ssl_fc_has_crt".
10257
Emeric Brun2525b6b2012-10-18 15:59:43 +020010258 ssl_c_verify Returns the verify result errorID when the incoming connection
10259 was made over an SSL/TLS transport layer, otherwise zero if no
10260 error is encountered.
10261
Emeric Bruna7359fd2012-10-17 15:03:11 +020010262 ssl_c_version
10263 Returns the version of the certificate presented by the client
10264 when the incoming connection was made over an SSL/TLS transport
10265 layer.
10266
Emeric Brun87855892012-10-17 17:39:35 +020010267 ssl_f_i_dn[(entry[,occ])]
10268 If no entry specified, returns the full distinguished name of
10269 the issuer of the certificate presented by the frontend when
10270 the incoming connection was made over an SSL/TLS transport
Baptiste Assmannea3e73b2013-02-02 23:47:49 +010010271 layer. Otherwise returns the value of the first given entry
10272 found from the beginning of the DN. If a positive/negative
Emeric Brun87855892012-10-17 17:39:35 +020010273 occurrence number is specified as the optional second argument,
10274 it returns the value of the nth given entry found from the
10275 beginning/end of the DN. For instance to retrieve the common
10276 name ssl_f_i_dn(CN) and the second organization unit
10277 ssl_f_i_dn(OU,2).
10278
Emeric Brun7f56e742012-10-19 18:15:40 +020010279 ssl_f_key_alg
10280 Returns the name of the algorithm used to generate the key of
10281 the certificate presented by the frontend when the incoming
10282 connection was made over an SSL/TLS transport layer.
10283
Emeric Brunce5ad802012-10-22 14:11:22 +020010284 ssl_f_notafter
10285 Returns the end date presented by the frontend as a formatted
10286 string YYMMDDhhmmss[Z] when the incoming connection was made
10287 over an SSL/TLS transport layer.
10288
10289 ssl_f_notbefore
10290 Returns the start date presented by the frontend as a formatted
10291 string YYMMDDhhmmss[Z] when the incoming connection was made
10292 over an SSL/TLS transport layer.
10293
Emeric Brun87855892012-10-17 17:39:35 +020010294 ssl_f_s_dn[(entry[,occ])]
10295 If no entry specified, returns the full distinguished name of
10296 the subject of the certificate presented by the frontend when
10297 the incoming connection was made over an SSL/TLS transport
Baptiste Assmannea3e73b2013-02-02 23:47:49 +010010298 layer. Otherwise returns the value of the first given entry
10299 found from the beginning of the DN. If a positive/negative
Emeric Brun87855892012-10-17 17:39:35 +020010300 occurrence number is specified as the optional second argument,
10301 it returns the value of the nth given entry found from the
10302 beginning/end of the DN. For instance to retrieve the common
10303 name ssl_f_s_dn(CN) and the second organization unit
10304 ssl_f_s_dn(OU,2).
10305
Willy Tarreau8d598402012-10-22 17:58:39 +020010306 ssl_f_serial Returns the serial of the certificate presented by the frontend
10307 when the incoming connection was made over an SSL/TLS transport
10308 layer.
10309
Emeric Brun7f56e742012-10-19 18:15:40 +020010310 ssl_f_sig_alg
10311 Returns the name of the algorithm used to sign the certificate
10312 presented by the frontend when the incoming connection was made
10313 over an SSL/TLS transport layer.
10314
Emeric Bruna7359fd2012-10-17 15:03:11 +020010315 ssl_f_version
10316 Returns the version of the certificate presented by the frontend
10317 when the incoming connection was made over an SSL/TLS transport
10318 layer.
10319
Emeric Brun2525b6b2012-10-18 15:59:43 +020010320 ssl_fc This checks the transport layer used on the front connection,
10321 and returns 1 if it was made via an SSL/TLS transport layer,
10322 otherwise zero.
10323
Emeric Brun589fcad2012-10-16 14:13:26 +020010324 ssl_fc_alg_keysize
10325 Returns the symmetric cipher key size support d in bits when the
10326 incoming connection was made over an SSL/TLS transport layer.
10327
10328 ssl_fc_cipher
10329 Returns the name of the used cipher when the incoming connection
10330 was made over an SSL/TLS transport layer.
10331
Emeric Brun2525b6b2012-10-18 15:59:43 +020010332 ssl_fc_has_crt
10333 Returns 1 if a client certificate is present in the front
10334 connection over SSL/TLS transport layer, otherwise 0.
Emeric Brun9143d372012-12-20 15:44:16 +010010335 Note: on SSL session resumption with Session ID or TLS ticket,
10336 client certificate is not present in the current connection but
10337 may be retrieved from the cache or the ticket. So prefer
10338 "ssl_c_used" if you want to check if current SSL session uses
10339 a client certificate.
Emeric Brun2525b6b2012-10-18 15:59:43 +020010340
10341 ssl_fc_has_sni
10342 This checks the transport layer used by the front connection, and
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020010343 returns 1 if the connection was made via an SSL/TLS transport
10344 layer and the client sent a Server Name Indication TLS extension,
Willy Tarreau7875d092012-09-10 08:20:03 +020010345 otherwise zero. This requires that the SSL library is build with
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020010346 support for TLS extensions enabled (check haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +020010347
Emeric Brun2525b6b2012-10-18 15:59:43 +020010348 ssl_fc_npn This extracts the Next Protocol Negociation field from an
Willy Tarreaua33c6542012-10-15 13:19:06 +020010349 incoming connection made via an SSL/TLS transport layer and
10350 locally deciphered by haproxy. The result is a string containing
10351 the protocol name advertised by the client. The SSL library must
10352 have been built with support for TLS extensions enabled (check
Emeric Brun2525b6b2012-10-18 15:59:43 +020010353 haproxy -vv). See also the "npn" bind keyword.
Willy Tarreaua33c6542012-10-15 13:19:06 +020010354
Emeric Brun589fcad2012-10-16 14:13:26 +020010355 ssl_fc_protocol
Cyril Bonté316a8cf2012-11-11 13:38:27 +010010356 Returns the name of the used protocol when the incoming
10357 connection was made over an SSL/TLS transport layer.
Emeric Brun589fcad2012-10-16 14:13:26 +020010358
Emeric Brunfe68f682012-10-16 14:59:28 +020010359 ssl_fc_session_id
10360 Returns the SSL ID of the front connection when the incoming
10361 connection was made over an SSL/TLS transport layer. Useful to
10362 stick on a given client.
10363
Emeric Brun2525b6b2012-10-18 15:59:43 +020010364 ssl_fc_sni This extracts the Server Name Indication field from an incoming
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020010365 connection made via an SSL/TLS transport layer and locally
10366 deciphered by haproxy. The result typically is a string matching
10367 the HTTPS host name (253 chars or less). The SSL library must
10368 have been built with support for TLS extensions enabled (check
10369 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +020010370
Emeric Brun589fcad2012-10-16 14:13:26 +020010371 ssl_fc_use_keysize
10372 Returns the symmetric cipher key size used in bits when the
10373 incoming connection was made over an SSL/TLS transport layer.
10374
Willy Tarreau409bcde2013-01-08 00:31:00 +010010375 status Returns an integer containing the HTTP status code in the HTTP
10376 response, for example, 302. It is mostly used within ACLs.
10377
Willy Tarreau281c7992013-01-08 01:23:27 +010010378 table_avl([<table>])
10379 Returns the total number of available entries in the current
10380 proxy's stick-table or in the designated stick-table. See also
10381 table_cnt.
10382
10383 table_cnt([<table>])
10384 Returns the total number of entries currently in use in the
10385 current proxy's stick-table or in the designated stick-table.
10386 See also src_conn_cnt and table_avl for other entry counting
10387 methods.
10388
Willy Tarreau6812bcf2012-04-29 09:28:50 +020010389 url This extracts the request's URL as presented in the request. A
10390 typical use is with prefetch-capable caches, and with portals
10391 which need to aggregate multiple information from databases and
10392 keep them in caches. See also "path".
10393
Willy Tarreau409bcde2013-01-08 00:31:00 +010010394 urlp(<name>[,<delim>])
10395 Note: all "urlp*" sample fetch methods apply only to the first
10396 occurrence of the parameter <name> in the query string, which
10397 is delimited by character <delim> if specified, otherwise '&'.
10398 The parameter name is case-sensitive. This one extracts a string
10399 corresponding to the value of the parameter <name>. This can be
10400 used for session stickiness.
10401
10402 urlp_val(<name>[,<delim>])
10403 See "urlp" above. This one extracts the URL parameter <name> in
10404 the request and converts it ao an integer value. This can be
10405 used for session stickiness.
10406
Willy Tarreau6812bcf2012-04-29 09:28:50 +020010407 url_ip This extracts the IP address from the request's URL when the
10408 host part is presented as an IP address. Its use is very
10409 limited. For instance, a monitoring system might use this field
10410 as an alternative for the source IP in order to test what path a
10411 given source address would follow, or to force an entry in a
10412 table for a given source address.
10413
10414 url_port This extracts the port part from the request's URL. It probably
10415 is totally useless but it was available at no cost.
10416
bedis4c75cca2012-10-05 08:38:24 +020010417 url_param(<name>[,<delim>])
Cyril Bontédc4d9032012-04-08 21:57:39 +020010418 This extracts the first occurrence of the parameter <name> in
bedis4c75cca2012-10-05 08:38:24 +020010419 the parameter string of the request and uses the corresponding
10420 value to match. Optionally, a delimiter can be provided. If not
10421 then the question mark '?' is used by default.
10422 A typical use is to get sticky session through url for cases
10423 where cookies cannot be used.
10424
10425 Example :
10426 # match http://example.com/foo?PHPSESSIONID=some_id
10427 stick on url_param(PHPSESSIONID)
10428 # match http://example.com/foo;JSESSIONID=some_id
10429 stick on url_param(JSESSIONID,;)
David Cournapeau16023ee2010-12-23 20:55:41 +090010430
Willy Tarreaud4c33c82013-01-07 21:59:07 +010010431 wait_end Always returns true or does not fetch. This is only used for ACL
10432 compatibility.
Willy Tarreaub3eb2212011-07-01 16:16:17 +020010433
Simon Hormanab814e02011-06-24 14:50:20 +090010434
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010435The currently available list of transformations include :
10436
10437 lower Convert a string pattern to lower case. This can only be placed
10438 after a string pattern fetch function or after a conversion
10439 function returning a string type. The result is of type string.
10440
10441 upper Convert a string pattern to upper case. This can only be placed
10442 after a string pattern fetch function or after a conversion
10443 function returning a string type. The result is of type string.
10444
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +020010445 ipmask(<mask>) Apply a mask to an IPv4 address, and use the result for lookups
Willy Tarreaud31d6eb2010-01-26 18:01:41 +010010446 and storage. This can be used to make all hosts within a
10447 certain mask to share the same table entries and as such use
10448 the same server. The mask can be passed in dotted form (eg:
10449 255.255.255.0) or in CIDR form (eg: 24).
10450
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010451
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200104528. Logging
10453----------
Willy Tarreau844e3c52008-01-11 16:28:18 +010010454
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010455One of HAProxy's strong points certainly lies is its precise logs. It probably
10456provides the finest level of information available for such a product, which is
10457very important for troubleshooting complex environments. Standard information
10458provided in logs include client ports, TCP/HTTP state timers, precise session
10459state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010460to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010461headers.
10462
10463In order to improve administrators reactivity, it offers a great transparency
10464about encountered problems, both internal and external, and it is possible to
10465send logs to different sources at the same time with different level filters :
10466
10467 - global process-level logs (system errors, start/stop, etc..)
10468 - per-instance system and internal errors (lack of resource, bugs, ...)
10469 - per-instance external troubles (servers up/down, max connections)
10470 - per-instance activity (client connections), either at the establishment or
10471 at the termination.
10472
10473The ability to distribute different levels of logs to different log servers
10474allow several production teams to interact and to fix their problems as soon
10475as possible. For example, the system team might monitor system-wide errors,
10476while the application team might be monitoring the up/down for their servers in
10477real time, and the security team might analyze the activity logs with one hour
10478delay.
10479
10480
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200104818.1. Log levels
10482---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010483
Simon Hormandf791f52011-05-29 15:01:10 +090010484TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010485source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +090010486HTTP request, HTTP return code, number of bytes transmitted, conditions
10487in which the session ended, and even exchanged cookies values. For example
10488track a particular user's problems. All messages may be sent to up to two
10489syslog servers. Check the "log" keyword in section 4.2 for more information
10490about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010491
10492
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200104938.2. Log formats
10494----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010495
William Lallemand48940402012-01-30 16:47:22 +010010496HAProxy supports 5 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +090010497and will be detailed in the following sections. A few of them may vary
10498slightly with the configuration, due to indicators specific to certain
10499options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010500
10501 - the default format, which is very basic and very rarely used. It only
10502 provides very basic information about the incoming connection at the moment
10503 it is accepted : source IP:port, destination IP:port, and frontend-name.
10504 This mode will eventually disappear so it will not be described to great
10505 extents.
10506
10507 - the TCP format, which is more advanced. This format is enabled when "option
10508 tcplog" is set on the frontend. HAProxy will then usually wait for the
10509 connection to terminate before logging. This format provides much richer
10510 information, such as timers, connection counts, queue size, etc... This
10511 format is recommended for pure TCP proxies.
10512
10513 - the HTTP format, which is the most advanced for HTTP proxying. This format
10514 is enabled when "option httplog" is set on the frontend. It provides the
10515 same information as the TCP format with some HTTP-specific fields such as
10516 the request, the status code, and captures of headers and cookies. This
10517 format is recommended for HTTP proxies.
10518
Emeric Brun3a058f32009-06-30 18:26:00 +020010519 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
10520 fields arranged in the same order as the CLF format. In this mode, all
10521 timers, captures, flags, etc... appear one per field after the end of the
10522 common fields, in the same order they appear in the standard HTTP format.
10523
William Lallemand48940402012-01-30 16:47:22 +010010524 - the custom log format, allows you to make your own log line.
10525
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010526Next sections will go deeper into details for each of these formats. Format
10527specification will be performed on a "field" basis. Unless stated otherwise, a
10528field is a portion of text delimited by any number of spaces. Since syslog
10529servers are susceptible of inserting fields at the beginning of a line, it is
10530always assumed that the first field is the one containing the process name and
10531identifier.
10532
10533Note : Since log lines may be quite long, the log examples in sections below
10534 might be broken into multiple lines. The example log lines will be
10535 prefixed with 3 closing angle brackets ('>>>') and each time a log is
10536 broken into multiple lines, each non-final line will end with a
10537 backslash ('\') and the next line will start indented by two characters.
10538
10539
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200105408.2.1. Default log format
10541-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010542
10543This format is used when no specific option is set. The log is emitted as soon
10544as the connection is accepted. One should note that this currently is the only
10545format which logs the request's destination IP and ports.
10546
10547 Example :
10548 listen www
10549 mode http
10550 log global
10551 server srv1 127.0.0.1:8000
10552
10553 >>> Feb 6 12:12:09 localhost \
10554 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
10555 (www/HTTP)
10556
10557 Field Format Extract from the example above
10558 1 process_name '[' pid ']:' haproxy[14385]:
10559 2 'Connect from' Connect from
10560 3 source_ip ':' source_port 10.0.1.2:33312
10561 4 'to' to
10562 5 destination_ip ':' destination_port 10.0.3.31:8012
10563 6 '(' frontend_name '/' mode ')' (www/HTTP)
10564
10565Detailed fields description :
10566 - "source_ip" is the IP address of the client which initiated the connection.
10567 - "source_port" is the TCP port of the client which initiated the connection.
10568 - "destination_ip" is the IP address the client connected to.
10569 - "destination_port" is the TCP port the client connected to.
10570 - "frontend_name" is the name of the frontend (or listener) which received
10571 and processed the connection.
10572 - "mode is the mode the frontend is operating (TCP or HTTP).
10573
Willy Tarreauceb24bc2010-11-09 12:46:41 +010010574In case of a UNIX socket, the source and destination addresses are marked as
10575"unix:" and the ports reflect the internal ID of the socket which accepted the
10576connection (the same ID as reported in the stats).
10577
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010578It is advised not to use this deprecated format for newer installations as it
10579will eventually disappear.
10580
10581
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200105828.2.2. TCP log format
10583---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010584
10585The TCP format is used when "option tcplog" is specified in the frontend, and
10586is the recommended format for pure TCP proxies. It provides a lot of precious
10587information for troubleshooting. Since this format includes timers and byte
10588counts, the log is normally emitted at the end of the session. It can be
10589emitted earlier if "option logasap" is specified, which makes sense in most
10590environments with long sessions such as remote terminals. Sessions which match
10591the "monitor" rules are never logged. It is also possible not to emit logs for
10592sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020010593specifying "option dontlognull" in the frontend. Successful connections will
10594not be logged if "option dontlog-normal" is specified in the frontend. A few
10595fields may slightly vary depending on some configuration options, those are
10596marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010597
10598 Example :
10599 frontend fnt
10600 mode tcp
10601 option tcplog
10602 log global
10603 default_backend bck
10604
10605 backend bck
10606 server srv1 127.0.0.1:8000
10607
10608 >>> Feb 6 12:12:56 localhost \
10609 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
10610 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
10611
10612 Field Format Extract from the example above
10613 1 process_name '[' pid ']:' haproxy[14387]:
10614 2 client_ip ':' client_port 10.0.1.2:33313
10615 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
10616 4 frontend_name fnt
10617 5 backend_name '/' server_name bck/srv1
10618 6 Tw '/' Tc '/' Tt* 0/0/5007
10619 7 bytes_read* 212
10620 8 termination_state --
10621 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
10622 10 srv_queue '/' backend_queue 0/0
10623
10624Detailed fields description :
10625 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010010626 connection to haproxy. If the connection was accepted on a UNIX socket
10627 instead, the IP address would be replaced with the word "unix". Note that
10628 when the connection is accepted on a socket configured with "accept-proxy"
10629 and the PROXY protocol is correctly used, then the logs will reflect the
10630 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010631
10632 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010010633 If the connection was accepted on a UNIX socket instead, the port would be
10634 replaced with the ID of the accepting socket, which is also reported in the
10635 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010636
10637 - "accept_date" is the exact date when the connection was received by haproxy
10638 (which might be very slightly different from the date observed on the
10639 network if there was some queuing in the system's backlog). This is usually
10640 the same date which may appear in any upstream firewall's log.
10641
10642 - "frontend_name" is the name of the frontend (or listener) which received
10643 and processed the connection.
10644
10645 - "backend_name" is the name of the backend (or listener) which was selected
10646 to manage the connection to the server. This will be the same as the
10647 frontend if no switching rule has been applied, which is common for TCP
10648 applications.
10649
10650 - "server_name" is the name of the last server to which the connection was
10651 sent, which might differ from the first one if there were connection errors
10652 and a redispatch occurred. Note that this server belongs to the backend
10653 which processed the request. If the connection was aborted before reaching
10654 a server, "<NOSRV>" is indicated instead of a server name.
10655
10656 - "Tw" is the total time in milliseconds spent waiting in the various queues.
10657 It can be "-1" if the connection was aborted before reaching the queue.
10658 See "Timers" below for more details.
10659
10660 - "Tc" is the total time in milliseconds spent waiting for the connection to
10661 establish to the final server, including retries. It can be "-1" if the
10662 connection was aborted before a connection could be established. See
10663 "Timers" below for more details.
10664
10665 - "Tt" is the total time in milliseconds elapsed between the accept and the
10666 last close. It covers all possible processings. There is one exception, if
10667 "option logasap" was specified, then the time counting stops at the moment
10668 the log is emitted. In this case, a '+' sign is prepended before the value,
10669 indicating that the final one will be larger. See "Timers" below for more
10670 details.
10671
10672 - "bytes_read" is the total number of bytes transmitted from the server to
10673 the client when the log is emitted. If "option logasap" is specified, the
10674 this value will be prefixed with a '+' sign indicating that the final one
10675 may be larger. Please note that this value is a 64-bit counter, so log
10676 analysis tools must be able to handle it without overflowing.
10677
10678 - "termination_state" is the condition the session was in when the session
10679 ended. This indicates the session state, which side caused the end of
10680 session to happen, and for what reason (timeout, error, ...). The normal
10681 flags should be "--", indicating the session was closed by either end with
10682 no data remaining in buffers. See below "Session state at disconnection"
10683 for more details.
10684
10685 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010686 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010687 limits have been reached. For instance, if actconn is close to 512 when
10688 multiple connection errors occur, chances are high that the system limits
10689 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010690 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010691
10692 - "feconn" is the total number of concurrent connections on the frontend when
10693 the session was logged. It is useful to estimate the amount of resource
10694 required to sustain high loads, and to detect when the frontend's "maxconn"
10695 has been reached. Most often when this value increases by huge jumps, it is
10696 because there is congestion on the backend servers, but sometimes it can be
10697 caused by a denial of service attack.
10698
10699 - "beconn" is the total number of concurrent connections handled by the
10700 backend when the session was logged. It includes the total number of
10701 concurrent connections active on servers as well as the number of
10702 connections pending in queues. It is useful to estimate the amount of
10703 additional servers needed to support high loads for a given application.
10704 Most often when this value increases by huge jumps, it is because there is
10705 congestion on the backend servers, but sometimes it can be caused by a
10706 denial of service attack.
10707
10708 - "srv_conn" is the total number of concurrent connections still active on
10709 the server when the session was logged. It can never exceed the server's
10710 configured "maxconn" parameter. If this value is very often close or equal
10711 to the server's "maxconn", it means that traffic regulation is involved a
10712 lot, meaning that either the server's maxconn value is too low, or that
10713 there aren't enough servers to process the load with an optimal response
10714 time. When only one of the server's "srv_conn" is high, it usually means
10715 that this server has some trouble causing the connections to take longer to
10716 be processed than on other servers.
10717
10718 - "retries" is the number of connection retries experienced by this session
10719 when trying to connect to the server. It must normally be zero, unless a
10720 server is being stopped at the same moment the connection was attempted.
10721 Frequent retries generally indicate either a network problem between
10722 haproxy and the server, or a misconfigured system backlog on the server
10723 preventing new connections from being queued. This field may optionally be
10724 prefixed with a '+' sign, indicating that the session has experienced a
10725 redispatch after the maximal retry count has been reached on the initial
10726 server. In this case, the server name appearing in the log is the one the
10727 connection was redispatched to, and not the first one, though both may
10728 sometimes be the same in case of hashing for instance. So as a general rule
10729 of thumb, when a '+' is present in front of the retry count, this count
10730 should not be attributed to the logged server.
10731
10732 - "srv_queue" is the total number of requests which were processed before
10733 this one in the server queue. It is zero when the request has not gone
10734 through the server queue. It makes it possible to estimate the approximate
10735 server's response time by dividing the time spent in queue by the number of
10736 requests in the queue. It is worth noting that if a session experiences a
10737 redispatch and passes through two server queues, their positions will be
10738 cumulated. A request should not pass through both the server queue and the
10739 backend queue unless a redispatch occurs.
10740
10741 - "backend_queue" is the total number of requests which were processed before
10742 this one in the backend's global queue. It is zero when the request has not
10743 gone through the global queue. It makes it possible to estimate the average
10744 queue length, which easily translates into a number of missing servers when
10745 divided by a server's "maxconn" parameter. It is worth noting that if a
10746 session experiences a redispatch, it may pass twice in the backend's queue,
10747 and then both positions will be cumulated. A request should not pass
10748 through both the server queue and the backend queue unless a redispatch
10749 occurs.
10750
10751
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200107528.2.3. HTTP log format
10753----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010754
10755The HTTP format is the most complete and the best suited for HTTP proxies. It
10756is enabled by when "option httplog" is specified in the frontend. It provides
10757the same level of information as the TCP format with additional features which
10758are specific to the HTTP protocol. Just like the TCP format, the log is usually
10759emitted at the end of the session, unless "option logasap" is specified, which
10760generally only makes sense for download sites. A session which matches the
10761"monitor" rules will never logged. It is also possible not to log sessions for
10762which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020010763frontend. Successful connections will not be logged if "option dontlog-normal"
10764is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010765
10766Most fields are shared with the TCP log, some being different. A few fields may
10767slightly vary depending on some configuration options. Those ones are marked
10768with a star ('*') after the field name below.
10769
10770 Example :
10771 frontend http-in
10772 mode http
10773 option httplog
10774 log global
10775 default_backend bck
10776
10777 backend static
10778 server srv1 127.0.0.1:8000
10779
10780 >>> Feb 6 12:14:14 localhost \
10781 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
10782 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 +010010783 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010784
10785 Field Format Extract from the example above
10786 1 process_name '[' pid ']:' haproxy[14389]:
10787 2 client_ip ':' client_port 10.0.1.2:33317
10788 3 '[' accept_date ']' [06/Feb/2009:12:14:14.655]
10789 4 frontend_name http-in
10790 5 backend_name '/' server_name static/srv1
10791 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt* 10/0/30/69/109
10792 7 status_code 200
10793 8 bytes_read* 2750
10794 9 captured_request_cookie -
10795 10 captured_response_cookie -
10796 11 termination_state ----
10797 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
10798 13 srv_queue '/' backend_queue 0/0
10799 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
10800 15 '{' captured_response_headers* '}' {}
10801 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +010010802
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010803
10804Detailed fields description :
10805 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010010806 connection to haproxy. If the connection was accepted on a UNIX socket
10807 instead, the IP address would be replaced with the word "unix". Note that
10808 when the connection is accepted on a socket configured with "accept-proxy"
10809 and the PROXY protocol is correctly used, then the logs will reflect the
10810 forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010811
10812 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010010813 If the connection was accepted on a UNIX socket instead, the port would be
10814 replaced with the ID of the accepting socket, which is also reported in the
10815 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010816
10817 - "accept_date" is the exact date when the TCP connection was received by
10818 haproxy (which might be very slightly different from the date observed on
10819 the network if there was some queuing in the system's backlog). This is
10820 usually the same date which may appear in any upstream firewall's log. This
10821 does not depend on the fact that the client has sent the request or not.
10822
10823 - "frontend_name" is the name of the frontend (or listener) which received
10824 and processed the connection.
10825
10826 - "backend_name" is the name of the backend (or listener) which was selected
10827 to manage the connection to the server. This will be the same as the
10828 frontend if no switching rule has been applied.
10829
10830 - "server_name" is the name of the last server to which the connection was
10831 sent, which might differ from the first one if there were connection errors
10832 and a redispatch occurred. Note that this server belongs to the backend
10833 which processed the request. If the request was aborted before reaching a
10834 server, "<NOSRV>" is indicated instead of a server name. If the request was
10835 intercepted by the stats subsystem, "<STATS>" is indicated instead.
10836
10837 - "Tq" is the total time in milliseconds spent waiting for the client to send
10838 a full HTTP request, not counting data. It can be "-1" if the connection
10839 was aborted before a complete request could be received. It should always
10840 be very small because a request generally fits in one single packet. Large
10841 times here generally indicate network trouble between the client and
10842 haproxy. See "Timers" below for more details.
10843
10844 - "Tw" is the total time in milliseconds spent waiting in the various queues.
10845 It can be "-1" if the connection was aborted before reaching the queue.
10846 See "Timers" below for more details.
10847
10848 - "Tc" is the total time in milliseconds spent waiting for the connection to
10849 establish to the final server, including retries. It can be "-1" if the
10850 request was aborted before a connection could be established. See "Timers"
10851 below for more details.
10852
10853 - "Tr" is the total time in milliseconds spent waiting for the server to send
10854 a full HTTP response, not counting data. It can be "-1" if the request was
10855 aborted before a complete response could be received. It generally matches
10856 the server's processing time for the request, though it may be altered by
10857 the amount of data sent by the client to the server. Large times here on
10858 "GET" requests generally indicate an overloaded server. See "Timers" below
10859 for more details.
10860
10861 - "Tt" is the total time in milliseconds elapsed between the accept and the
10862 last close. It covers all possible processings. There is one exception, if
10863 "option logasap" was specified, then the time counting stops at the moment
10864 the log is emitted. In this case, a '+' sign is prepended before the value,
10865 indicating that the final one will be larger. See "Timers" below for more
10866 details.
10867
10868 - "status_code" is the HTTP status code returned to the client. This status
10869 is generally set by the server, but it might also be set by haproxy when
10870 the server cannot be reached or when its response is blocked by haproxy.
10871
10872 - "bytes_read" is the total number of bytes transmitted to the client when
10873 the log is emitted. This does include HTTP headers. If "option logasap" is
10874 specified, the this value will be prefixed with a '+' sign indicating that
10875 the final one may be larger. Please note that this value is a 64-bit
10876 counter, so log analysis tools must be able to handle it without
10877 overflowing.
10878
10879 - "captured_request_cookie" is an optional "name=value" entry indicating that
10880 the client had this cookie in the request. The cookie name and its maximum
10881 length are defined by the "capture cookie" statement in the frontend
10882 configuration. The field is a single dash ('-') when the option is not
10883 set. Only one cookie may be captured, it is generally used to track session
10884 ID exchanges between a client and a server to detect session crossing
10885 between clients due to application bugs. For more details, please consult
10886 the section "Capturing HTTP headers and cookies" below.
10887
10888 - "captured_response_cookie" is an optional "name=value" entry indicating
10889 that the server has returned a cookie with its response. The cookie name
10890 and its maximum length are defined by the "capture cookie" statement in the
10891 frontend configuration. The field is a single dash ('-') when the option is
10892 not set. Only one cookie may be captured, it is generally used to track
10893 session ID exchanges between a client and a server to detect session
10894 crossing between clients due to application bugs. For more details, please
10895 consult the section "Capturing HTTP headers and cookies" below.
10896
10897 - "termination_state" is the condition the session was in when the session
10898 ended. This indicates the session state, which side caused the end of
10899 session to happen, for what reason (timeout, error, ...), just like in TCP
10900 logs, and information about persistence operations on cookies in the last
10901 two characters. The normal flags should begin with "--", indicating the
10902 session was closed by either end with no data remaining in buffers. See
10903 below "Session state at disconnection" for more details.
10904
10905 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010906 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010907 limits have been reached. For instance, if actconn is close to 512 or 1024
10908 when multiple connection errors occur, chances are high that the system
10909 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010910 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010010911 system.
10912
10913 - "feconn" is the total number of concurrent connections on the frontend when
10914 the session was logged. It is useful to estimate the amount of resource
10915 required to sustain high loads, and to detect when the frontend's "maxconn"
10916 has been reached. Most often when this value increases by huge jumps, it is
10917 because there is congestion on the backend servers, but sometimes it can be
10918 caused by a denial of service attack.
10919
10920 - "beconn" is the total number of concurrent connections handled by the
10921 backend when the session was logged. It includes the total number of
10922 concurrent connections active on servers as well as the number of
10923 connections pending in queues. It is useful to estimate the amount of
10924 additional servers needed to support high loads for a given application.
10925 Most often when this value increases by huge jumps, it is because there is
10926 congestion on the backend servers, but sometimes it can be caused by a
10927 denial of service attack.
10928
10929 - "srv_conn" is the total number of concurrent connections still active on
10930 the server when the session was logged. It can never exceed the server's
10931 configured "maxconn" parameter. If this value is very often close or equal
10932 to the server's "maxconn", it means that traffic regulation is involved a
10933 lot, meaning that either the server's maxconn value is too low, or that
10934 there aren't enough servers to process the load with an optimal response
10935 time. When only one of the server's "srv_conn" is high, it usually means
10936 that this server has some trouble causing the requests to take longer to be
10937 processed than on other servers.
10938
10939 - "retries" is the number of connection retries experienced by this session
10940 when trying to connect to the server. It must normally be zero, unless a
10941 server is being stopped at the same moment the connection was attempted.
10942 Frequent retries generally indicate either a network problem between
10943 haproxy and the server, or a misconfigured system backlog on the server
10944 preventing new connections from being queued. This field may optionally be
10945 prefixed with a '+' sign, indicating that the session has experienced a
10946 redispatch after the maximal retry count has been reached on the initial
10947 server. In this case, the server name appearing in the log is the one the
10948 connection was redispatched to, and not the first one, though both may
10949 sometimes be the same in case of hashing for instance. So as a general rule
10950 of thumb, when a '+' is present in front of the retry count, this count
10951 should not be attributed to the logged server.
10952
10953 - "srv_queue" is the total number of requests which were processed before
10954 this one in the server queue. It is zero when the request has not gone
10955 through the server queue. It makes it possible to estimate the approximate
10956 server's response time by dividing the time spent in queue by the number of
10957 requests in the queue. It is worth noting that if a session experiences a
10958 redispatch and passes through two server queues, their positions will be
10959 cumulated. A request should not pass through both the server queue and the
10960 backend queue unless a redispatch occurs.
10961
10962 - "backend_queue" is the total number of requests which were processed before
10963 this one in the backend's global queue. It is zero when the request has not
10964 gone through the global queue. It makes it possible to estimate the average
10965 queue length, which easily translates into a number of missing servers when
10966 divided by a server's "maxconn" parameter. It is worth noting that if a
10967 session experiences a redispatch, it may pass twice in the backend's queue,
10968 and then both positions will be cumulated. A request should not pass
10969 through both the server queue and the backend queue unless a redispatch
10970 occurs.
10971
10972 - "captured_request_headers" is a list of headers captured in the request due
10973 to the presence of the "capture request header" statement in the frontend.
10974 Multiple headers can be captured, they will be delimited by a vertical bar
10975 ('|'). When no capture is enabled, the braces do not appear, causing a
10976 shift of remaining fields. It is important to note that this field may
10977 contain spaces, and that using it requires a smarter log parser than when
10978 it's not used. Please consult the section "Capturing HTTP headers and
10979 cookies" below for more details.
10980
10981 - "captured_response_headers" is a list of headers captured in the response
10982 due to the presence of the "capture response header" statement in the
10983 frontend. Multiple headers can be captured, they will be delimited by a
10984 vertical bar ('|'). When no capture is enabled, the braces do not appear,
10985 causing a shift of remaining fields. It is important to note that this
10986 field may contain spaces, and that using it requires a smarter log parser
10987 than when it's not used. Please consult the section "Capturing HTTP headers
10988 and cookies" below for more details.
10989
10990 - "http_request" is the complete HTTP request line, including the method,
10991 request and HTTP version string. Non-printable characters are encoded (see
10992 below the section "Non-printable characters"). This is always the last
10993 field, and it is always delimited by quotes and is the only one which can
10994 contain quotes. If new fields are added to the log format, they will be
10995 added before this field. This field might be truncated if the request is
10996 huge and does not fit in the standard syslog buffer (1024 characters). This
10997 is the reason why this field must always remain the last one.
10998
10999
Cyril Bontédc4d9032012-04-08 21:57:39 +0200110008.2.4. Custom log format
11001------------------------
William Lallemand48940402012-01-30 16:47:22 +010011002
Willy Tarreau2beef582012-12-20 17:22:52 +010011003The directive log-format allows you to customize the logs in http mode and tcp
William Lallemandbddd4fd2012-02-27 11:23:10 +010011004mode. It takes a string as argument.
William Lallemand48940402012-01-30 16:47:22 +010011005
11006HAproxy understands some log format variables. % precedes log format variables.
11007Variables can take arguments using braces ('{}'), and multiple arguments are
11008separated by commas within the braces. Flags may be added or removed by
11009prefixing them with a '+' or '-' sign.
11010
11011Special variable "%o" may be used to propagate its flags to all other
11012variables on the same format string. This is particularly handy with quoted
11013string formats ("Q").
11014
Willy Tarreauc8368452012-12-21 00:09:23 +010011015If a variable is named between square brackets ('[' .. ']') then it is used
11016as a pattern extraction rule (see section 7.8). This it useful to add some
11017less common information such as the client's SSL certificate's DN, or to log
11018the key that would be used to store an entry into a stick table.
11019
William Lallemand48940402012-01-30 16:47:22 +010011020Note: spaces must be escaped. A space character is considered as a separator.
11021HAproxy will automatically merge consecutive separators.
11022
11023Flags are :
11024 * Q: quote a string
Jamie Gloudonaaa21002012-08-25 00:18:33 -040011025 * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid)
William Lallemand48940402012-01-30 16:47:22 +010011026
11027 Example:
11028
11029 log-format %T\ %t\ Some\ Text
11030 log-format %{+Q}o\ %t\ %s\ %{-Q}r
11031
11032At the moment, the default HTTP format is defined this way :
11033
Willy Tarreau2beef582012-12-20 17:22:52 +010011034 log-format %ci:%cp\ [%t]\ %ft\ %b/%s\ %Tq/%Tw/%Tc/%Tr/%Tt\ %ST\ %B\ %CC\ \
11035 %CS\ %tsc\ %ac/%fc/%bc/%sc/%rc\ %sq/%bq\ %hr\ %hs\ %{+Q}r
William Lallemand48940402012-01-30 16:47:22 +010011036
William Lallemandbddd4fd2012-02-27 11:23:10 +010011037the default CLF format is defined this way :
William Lallemand48940402012-01-30 16:47:22 +010011038
Willy Tarreau2beef582012-12-20 17:22:52 +010011039 log-format %{+Q}o\ %{-Q}ci\ -\ -\ [%T]\ %r\ %ST\ %B\ \"\"\ \"\"\ %cp\ \
Willy Tarreau773d65f2012-10-12 14:56:11 +020011040 %ms\ %ft\ %b\ %s\ \%Tq\ %Tw\ %Tc\ %Tr\ %Tt\ %tsc\ %ac\ %fc\ \
Willy Tarreau2beef582012-12-20 17:22:52 +010011041 %bc\ %sc\ %rc\ %sq\ %bq\ %CC\ %CS\ \%hrl\ %hsl
William Lallemand48940402012-01-30 16:47:22 +010011042
William Lallemandbddd4fd2012-02-27 11:23:10 +010011043and the default TCP format is defined this way :
11044
Willy Tarreau2beef582012-12-20 17:22:52 +010011045 log-format %ci:%cp\ [%t]\ %ft\ %b/%s\ %Tw/%Tc/%Tt\ %B\ %ts\ \
William Lallemandbddd4fd2012-02-27 11:23:10 +010011046 %ac/%fc/%bc/%sc/%rc\ %sq/%bq
11047
William Lallemand48940402012-01-30 16:47:22 +010011048Please refer to the table below for currently defined variables :
11049
William Lallemandbddd4fd2012-02-27 11:23:10 +010011050 +---+------+-----------------------------------------------+-------------+
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011051 | R | var | field name (8.2.2 and 8.2.3 for description) | type |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011052 +---+------+-----------------------------------------------+-------------+
11053 | | %o | special variable, apply flags on all next var | |
11054 +---+------+-----------------------------------------------+-------------+
Willy Tarreau2beef582012-12-20 17:22:52 +010011055 | | %B | bytes_read (from server to client) | numeric |
11056 | H | %CC | captured_request_cookie | string |
11057 | H | %CS | captured_response_cookie | string |
William Lallemand5f232402012-04-05 18:02:55 +020011058 | | %H | hostname | string |
William Lallemanda73203e2012-03-12 12:48:57 +010011059 | | %ID | unique-id | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010011060 | H | %ST | status_code | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020011061 | | %T | gmt_date_time | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011062 | | %Tc | Tc | numeric |
Yuxans Yao4e25b012012-10-19 10:36:09 +080011063 | | %Tl | local_date_time | date |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011064 | H | %Tq | Tq | numeric |
11065 | H | %Tr | Tr | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020011066 | | %Ts | timestamp | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011067 | | %Tt | Tt | numeric |
11068 | | %Tw | Tw | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010011069 | | %U | bytes_uploaded (from client to server) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011070 | | %ac | actconn | numeric |
11071 | | %b | backend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010011072 | | %bc | beconn (backend concurrent connections) | numeric |
11073 | | %bi | backend_source_ip (connecting address) | IP |
11074 | | %bp | backend_source_port (connecting address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011075 | | %bq | backend_queue | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010011076 | | %ci | client_ip (accepted address) | IP |
11077 | | %cp | client_port (accepted address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011078 | | %f | frontend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010011079 | | %fc | feconn (frontend concurrent connections) | numeric |
11080 | | %fi | frontend_ip (accepting address) | IP |
11081 | | %fp | frontend_port (accepting address) | numeric |
Willy Tarreau773d65f2012-10-12 14:56:11 +020011082 | | %ft | frontend_name_transport ('~' suffix for SSL) | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011083 | H | %hr | captured_request_headers default style | string |
11084 | H | %hrl | captured_request_headers CLF style | string list |
11085 | H | %hs | captured_response_headers default style | string |
11086 | H | %hsl | captured_response_headers CLF style | string list |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011087 | | %ms | accept date milliseconds | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020011088 | | %pid | PID | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011089 | H | %r | http_request | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011090 | | %rc | retries | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010011091 | H | %rt | http_request_counter | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011092 | | %s | server_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010011093 | | %sc | srv_conn (server concurrent connections) | numeric |
11094 | | %si | server_IP (target address) | IP |
11095 | | %sp | server_port (target address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011096 | | %sq | srv_queue | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011097 | S | %sslc| ssl_ciphers (ex: AES-SHA) | string |
11098 | S | %sslv| ssl_version (ex: TLSv1) | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010011099 | | %t | date_time (with millisecond resolution) | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011100 | | %ts | termination_state | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011101 | H | %tsc | termination_state with cookie status | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010011102 +---+------+-----------------------------------------------+-------------+
William Lallemand48940402012-01-30 16:47:22 +010011103
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020011104 R = Restrictions : H = mode http only ; S = SSL only
William Lallemand48940402012-01-30 16:47:22 +010011105
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010011106
111078.2.5. Error log format
11108-----------------------
11109
11110When an incoming connection fails due to an SSL handshake or an invalid PROXY
11111protocol header, haproxy will log the event using a shorter, fixed line format.
11112By default, logs are emitted at the LOG_INFO level, unless the option
11113"log-separate-errors" is set in the backend, in which case the LOG_ERR level
11114will be used. Connections on which no data are exchanged (eg: probes) are not
11115logged if the "dontlognull" option is set.
11116
11117The format looks like this :
11118
11119 >>> Dec 3 18:27:14 localhost \
11120 haproxy[6103]: 127.0.0.1:56059 [03/Dec/2012:17:35:10.380] frt/f1: \
11121 Connection error during SSL handshake
11122
11123 Field Format Extract from the example above
11124 1 process_name '[' pid ']:' haproxy[6103]:
11125 2 client_ip ':' client_port 127.0.0.1:56059
11126 3 '[' accept_date ']' [03/Dec/2012:17:35:10.380]
11127 4 frontend_name "/" bind_name ":" frt/f1:
11128 5 message Connection error during SSL handshake
11129
11130These fields just provide minimal information to help debugging connection
11131failures.
11132
11133
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200111348.3. Advanced logging options
11135-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011136
11137Some advanced logging options are often looked for but are not easy to find out
11138just by looking at the various options. Here is an entry point for the few
11139options which can enable better logging. Please refer to the keywords reference
11140for more information about their usage.
11141
11142
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200111438.3.1. Disabling logging of external tests
11144------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011145
11146It is quite common to have some monitoring tools perform health checks on
11147haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
11148commercial load-balancer, and sometimes it will simply be a more complete
11149monitoring system such as Nagios. When the tests are very frequent, users often
11150ask how to disable logging for those checks. There are three possibilities :
11151
11152 - if connections come from everywhere and are just TCP probes, it is often
11153 desired to simply disable logging of connections without data exchange, by
11154 setting "option dontlognull" in the frontend. It also disables logging of
11155 port scans, which may or may not be desired.
11156
11157 - if the connection come from a known source network, use "monitor-net" to
11158 declare this network as monitoring only. Any host in this network will then
11159 only be able to perform health checks, and their requests will not be
11160 logged. This is generally appropriate to designate a list of equipments
11161 such as other load-balancers.
11162
11163 - if the tests are performed on a known URI, use "monitor-uri" to declare
11164 this URI as dedicated to monitoring. Any host sending this request will
11165 only get the result of a health-check, and the request will not be logged.
11166
11167
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200111688.3.2. Logging before waiting for the session to terminate
11169----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011170
11171The problem with logging at end of connection is that you have no clue about
11172what is happening during very long sessions, such as remote terminal sessions
11173or large file downloads. This problem can be worked around by specifying
11174"option logasap" in the frontend. Haproxy will then log as soon as possible,
11175just before data transfer begins. This means that in case of TCP, it will still
11176log the connection status to the server, and in case of HTTP, it will log just
11177after processing the server headers. In this case, the number of bytes reported
11178is the number of header bytes sent to the client. In order to avoid confusion
11179with normal logs, the total time field and the number of bytes are prefixed
11180with a '+' sign which means that real numbers are certainly larger.
11181
11182
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200111838.3.3. Raising log level upon errors
11184------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020011185
11186Sometimes it is more convenient to separate normal traffic from errors logs,
11187for instance in order to ease error monitoring from log files. When the option
11188"log-separate-errors" is used, connections which experience errors, timeouts,
11189retries, redispatches or HTTP status codes 5xx will see their syslog level
11190raised from "info" to "err". This will help a syslog daemon store the log in
11191a separate file. It is very important to keep the errors in the normal traffic
11192file too, so that log ordering is not altered. You should also be careful if
11193you already have configured your syslog daemon to store all logs higher than
11194"notice" in an "admin" file, because the "err" level is higher than "notice".
11195
11196
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200111978.3.4. Disabling logging of successful connections
11198--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020011199
11200Although this may sound strange at first, some large sites have to deal with
11201multiple thousands of logs per second and are experiencing difficulties keeping
11202them intact for a long time or detecting errors within them. If the option
11203"dontlog-normal" is set on the frontend, all normal connections will not be
11204logged. In this regard, a normal connection is defined as one without any
11205error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
11206and a response with a status 5xx is not considered normal and will be logged
11207too. Of course, doing is is really discouraged as it will remove most of the
11208useful information from the logs. Do this only if you have no other
11209alternative.
11210
11211
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200112128.4. Timing events
11213------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011214
11215Timers provide a great help in troubleshooting network problems. All values are
11216reported in milliseconds (ms). These timers should be used in conjunction with
11217the session termination flags. In TCP mode with "option tcplog" set on the
11218frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
11219mode, 5 control points are reported under the form "Tq/Tw/Tc/Tr/Tt" :
11220
11221 - Tq: total time to get the client request (HTTP mode only). It's the time
11222 elapsed between the moment the client connection was accepted and the
11223 moment the proxy received the last HTTP header. The value "-1" indicates
11224 that the end of headers (empty line) has never been seen. This happens when
11225 the client closes prematurely or times out.
11226
11227 - Tw: total time spent in the queues waiting for a connection slot. It
11228 accounts for backend queue as well as the server queues, and depends on the
11229 queue size, and the time needed for the server to complete previous
11230 requests. The value "-1" means that the request was killed before reaching
11231 the queue, which is generally what happens with invalid or denied requests.
11232
11233 - Tc: total time to establish the TCP connection to the server. It's the time
11234 elapsed between the moment the proxy sent the connection request, and the
11235 moment it was acknowledged by the server, or between the TCP SYN packet and
11236 the matching SYN/ACK packet in return. The value "-1" means that the
11237 connection never established.
11238
11239 - Tr: server response time (HTTP mode only). It's the time elapsed between
11240 the moment the TCP connection was established to the server and the moment
11241 the server sent its complete response headers. It purely shows its request
11242 processing time, without the network overhead due to the data transmission.
11243 It is worth noting that when the client has data to send to the server, for
11244 instance during a POST request, the time already runs, and this can distort
11245 apparent response time. For this reason, it's generally wise not to trust
11246 too much this field for POST requests initiated from clients behind an
11247 untrusted network. A value of "-1" here means that the last the response
11248 header (empty line) was never seen, most likely because the server timeout
11249 stroke before the server managed to process the request.
11250
11251 - Tt: total session duration time, between the moment the proxy accepted it
11252 and the moment both ends were closed. The exception is when the "logasap"
11253 option is specified. In this case, it only equals (Tq+Tw+Tc+Tr), and is
11254 prefixed with a '+' sign. From this field, we can deduce "Td", the data
11255 transmission time, by substracting other timers when valid :
11256
11257 Td = Tt - (Tq + Tw + Tc + Tr)
11258
11259 Timers with "-1" values have to be excluded from this equation. In TCP
11260 mode, "Tq" and "Tr" have to be excluded too. Note that "Tt" can never be
11261 negative.
11262
11263These timers provide precious indications on trouble causes. Since the TCP
11264protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
11265that timers close to multiples of 3s are nearly always related to lost packets
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011266due to network problems (wires, negotiation, congestion). Moreover, if "Tt" is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011267close to a timeout value specified in the configuration, it often means that a
11268session has been aborted on timeout.
11269
11270Most common cases :
11271
11272 - If "Tq" is close to 3000, a packet has probably been lost between the
11273 client and the proxy. This is very rare on local networks but might happen
11274 when clients are on far remote networks and send large requests. It may
11275 happen that values larger than usual appear here without any network cause.
11276 Sometimes, during an attack or just after a resource starvation has ended,
11277 haproxy may accept thousands of connections in a few milliseconds. The time
11278 spent accepting these connections will inevitably slightly delay processing
11279 of other connections, and it can happen that request times in the order of
11280 a few tens of milliseconds are measured after a few thousands of new
Patrick Mezard105faca2010-06-12 17:02:46 +020011281 connections have been accepted at once. Setting "option http-server-close"
11282 may display larger request times since "Tq" also measures the time spent
11283 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011284
11285 - If "Tc" is close to 3000, a packet has probably been lost between the
11286 server and the proxy during the server connection phase. This value should
11287 always be very low, such as 1 ms on local networks and less than a few tens
11288 of ms on remote networks.
11289
Willy Tarreau55165fe2009-05-10 12:02:55 +020011290 - If "Tr" is nearly always lower than 3000 except some rare values which seem
11291 to be the average majored by 3000, there are probably some packets lost
11292 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011293
11294 - If "Tt" is large even for small byte counts, it generally is because
11295 neither the client nor the server decides to close the connection, for
11296 instance because both have agreed on a keep-alive connection mode. In order
11297 to solve this issue, it will be needed to specify "option httpclose" on
11298 either the frontend or the backend. If the problem persists, it means that
11299 the server ignores the "close" connection mode and expects the client to
11300 close. Then it will be required to use "option forceclose". Having the
11301 smallest possible 'Tt' is important when connection regulation is used with
11302 the "maxconn" option on the servers, since no new connection will be sent
11303 to the server until another one is released.
11304
11305Other noticeable HTTP log cases ('xx' means any value to be ignored) :
11306
11307 Tq/Tw/Tc/Tr/+Tt The "option logasap" is present on the frontend and the log
11308 was emitted before the data phase. All the timers are valid
11309 except "Tt" which is shorter than reality.
11310
11311 -1/xx/xx/xx/Tt The client was not able to send a complete request in time
11312 or it aborted too early. Check the session termination flags
11313 then "timeout http-request" and "timeout client" settings.
11314
11315 Tq/-1/xx/xx/Tt It was not possible to process the request, maybe because
11316 servers were out of order, because the request was invalid
11317 or forbidden by ACL rules. Check the session termination
11318 flags.
11319
11320 Tq/Tw/-1/xx/Tt The connection could not establish on the server. Either it
11321 actively refused it or it timed out after Tt-(Tq+Tw) ms.
11322 Check the session termination flags, then check the
11323 "timeout connect" setting. Note that the tarpit action might
11324 return similar-looking patterns, with "Tw" equal to the time
11325 the client connection was maintained open.
11326
11327 Tq/Tw/Tc/-1/Tt The server has accepted the connection but did not return
11328 a complete response in time, or it closed its connexion
11329 unexpectedly after Tt-(Tq+Tw+Tc) ms. Check the session
11330 termination flags, then check the "timeout server" setting.
11331
11332
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200113338.5. Session state at disconnection
11334-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011335
11336TCP and HTTP logs provide a session termination indicator in the
11337"termination_state" field, just before the number of active connections. It is
113382-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
11339each of which has a special meaning :
11340
11341 - On the first character, a code reporting the first event which caused the
11342 session to terminate :
11343
11344 C : the TCP session was unexpectedly aborted by the client.
11345
11346 S : the TCP session was unexpectedly aborted by the server, or the
11347 server explicitly refused it.
11348
11349 P : the session was prematurely aborted by the proxy, because of a
11350 connection limit enforcement, because a DENY filter was matched,
11351 because of a security check which detected and blocked a dangerous
11352 error in server response which might have caused information leak
11353 (eg: cacheable cookie), or because the response was processed by
11354 the proxy (redirect, stats, etc...).
11355
11356 R : a resource on the proxy has been exhausted (memory, sockets, source
11357 ports, ...). Usually, this appears during the connection phase, and
11358 system logs should contain a copy of the precise error. If this
11359 happens, it must be considered as a very serious anomaly which
11360 should be fixed as soon as possible by any means.
11361
11362 I : an internal error was identified by the proxy during a self-check.
11363 This should NEVER happen, and you are encouraged to report any log
11364 containing this, because this would almost certainly be a bug. It
11365 would be wise to preventively restart the process after such an
11366 event too, in case it would be caused by memory corruption.
11367
Simon Horman752dc4a2011-06-21 14:34:59 +090011368 D : the session was killed by haproxy because the server was detected
11369 as down and was configured to kill all connections when going down.
11370
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070011371 U : the session was killed by haproxy on this backup server because an
11372 active server was detected as up and was configured to kill all
11373 backup connections when going up.
11374
Willy Tarreaua2a64e92011-09-07 23:01:56 +020011375 K : the session was actively killed by an admin operating on haproxy.
11376
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011377 c : the client-side timeout expired while waiting for the client to
11378 send or receive data.
11379
11380 s : the server-side timeout expired while waiting for the server to
11381 send or receive data.
11382
11383 - : normal session completion, both the client and the server closed
11384 with nothing left in the buffers.
11385
11386 - on the second character, the TCP or HTTP session state when it was closed :
11387
Willy Tarreauf7b30a92010-12-06 22:59:17 +010011388 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011389 (HTTP mode only). Nothing was sent to any server.
11390
11391 Q : the proxy was waiting in the QUEUE for a connection slot. This can
11392 only happen when servers have a 'maxconn' parameter set. It can
11393 also happen in the global queue after a redispatch consecutive to
11394 a failed attempt to connect to a dying server. If no redispatch is
11395 reported, then no connection attempt was made to any server.
11396
11397 C : the proxy was waiting for the CONNECTION to establish on the
11398 server. The server might at most have noticed a connection attempt.
11399
11400 H : the proxy was waiting for complete, valid response HEADERS from the
11401 server (HTTP only).
11402
11403 D : the session was in the DATA phase.
11404
11405 L : the proxy was still transmitting LAST data to the client while the
11406 server had already finished. This one is very rare as it can only
11407 happen when the client dies while receiving the last packets.
11408
11409 T : the request was tarpitted. It has been held open with the client
11410 during the whole "timeout tarpit" duration or until the client
11411 closed, both of which will be reported in the "Tw" timer.
11412
11413 - : normal session completion after end of data transfer.
11414
11415 - the third character tells whether the persistence cookie was provided by
11416 the client (only in HTTP mode) :
11417
11418 N : the client provided NO cookie. This is usually the case for new
11419 visitors, so counting the number of occurrences of this flag in the
11420 logs generally indicate a valid trend for the site frequentation.
11421
11422 I : the client provided an INVALID cookie matching no known server.
11423 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +020011424 cookies between HTTP/HTTPS sites, persistence conditionally
11425 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011426
11427 D : the client provided a cookie designating a server which was DOWN,
11428 so either "option persist" was used and the client was sent to
11429 this server, or it was not set and the client was redispatched to
11430 another server.
11431
Willy Tarreau996a92c2010-10-13 19:30:47 +020011432 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011433 server.
11434
Willy Tarreau996a92c2010-10-13 19:30:47 +020011435 E : the client provided a valid cookie, but with a last date which was
11436 older than what is allowed by the "maxidle" cookie parameter, so
11437 the cookie is consider EXPIRED and is ignored. The request will be
11438 redispatched just as if there was no cookie.
11439
11440 O : the client provided a valid cookie, but with a first date which was
11441 older than what is allowed by the "maxlife" cookie parameter, so
11442 the cookie is consider too OLD and is ignored. The request will be
11443 redispatched just as if there was no cookie.
11444
Willy Tarreauc89ccb62012-04-05 21:18:22 +020011445 U : a cookie was present but was not used to select the server because
11446 some other server selection mechanism was used instead (typically a
11447 "use-server" rule).
11448
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011449 - : does not apply (no cookie set in configuration).
11450
11451 - the last character reports what operations were performed on the persistence
11452 cookie returned by the server (only in HTTP mode) :
11453
11454 N : NO cookie was provided by the server, and none was inserted either.
11455
11456 I : no cookie was provided by the server, and the proxy INSERTED one.
11457 Note that in "cookie insert" mode, if the server provides a cookie,
11458 it will still be overwritten and reported as "I" here.
11459
Willy Tarreau996a92c2010-10-13 19:30:47 +020011460 U : the proxy UPDATED the last date in the cookie that was presented by
11461 the client. This can only happen in insert mode with "maxidle". It
11462 happens everytime there is activity at a different date than the
11463 date indicated in the cookie. If any other change happens, such as
11464 a redispatch, then the cookie will be marked as inserted instead.
11465
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011466 P : a cookie was PROVIDED by the server and transmitted as-is.
11467
11468 R : the cookie provided by the server was REWRITTEN by the proxy, which
11469 happens in "cookie rewrite" or "cookie prefix" modes.
11470
11471 D : the cookie provided by the server was DELETED by the proxy.
11472
11473 - : does not apply (no cookie set in configuration).
11474
Willy Tarreau996a92c2010-10-13 19:30:47 +020011475The combination of the two first flags gives a lot of information about what
11476was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011477helpful to detect server saturation, network troubles, local system resource
11478starvation, attacks, etc...
11479
11480The most common termination flags combinations are indicated below. They are
11481alphabetically sorted, with the lowercase set just after the upper case for
11482easier finding and understanding.
11483
11484 Flags Reason
11485
11486 -- Normal termination.
11487
11488 CC The client aborted before the connection could be established to the
11489 server. This can happen when haproxy tries to connect to a recently
11490 dead (or unchecked) server, and the client aborts while haproxy is
11491 waiting for the server to respond or for "timeout connect" to expire.
11492
11493 CD The client unexpectedly aborted during data transfer. This can be
11494 caused by a browser crash, by an intermediate equipment between the
11495 client and haproxy which decided to actively break the connection,
11496 by network routing issues between the client and haproxy, or by a
11497 keep-alive session between the server and the client terminated first
11498 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +010011499
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011500 cD The client did not send nor acknowledge any data for as long as the
11501 "timeout client" delay. This is often caused by network failures on
Cyril Bontédc4d9032012-04-08 21:57:39 +020011502 the client side, or the client simply leaving the net uncleanly.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011503
11504 CH The client aborted while waiting for the server to start responding.
11505 It might be the server taking too long to respond or the client
11506 clicking the 'Stop' button too fast.
11507
11508 cH The "timeout client" stroke while waiting for client data during a
11509 POST request. This is sometimes caused by too large TCP MSS values
11510 for PPPoE networks which cannot transport full-sized packets. It can
11511 also happen when client timeout is smaller than server timeout and
11512 the server takes too long to respond.
11513
11514 CQ The client aborted while its session was queued, waiting for a server
11515 with enough empty slots to accept it. It might be that either all the
11516 servers were saturated or that the assigned server was taking too
11517 long a time to respond.
11518
11519 CR The client aborted before sending a full HTTP request. Most likely
11520 the request was typed by hand using a telnet client, and aborted
11521 too early. The HTTP status code is likely a 400 here. Sometimes this
11522 might also be caused by an IDS killing the connection between haproxy
11523 and the client.
11524
11525 cR The "timeout http-request" stroke before the client sent a full HTTP
11526 request. This is sometimes caused by too large TCP MSS values on the
11527 client side for PPPoE networks which cannot transport full-sized
11528 packets, or by clients sending requests by hand and not typing fast
11529 enough, or forgetting to enter the empty line at the end of the
11530 request. The HTTP status code is likely a 408 here.
11531
11532 CT The client aborted while its session was tarpitted. It is important to
11533 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +020011534 wrong tarpit rules have been written. If a lot of them happen, it
11535 might make sense to lower the "timeout tarpit" value to something
11536 closer to the average reported "Tw" timer, in order not to consume
11537 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011538
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011539 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011540 the TCP connection (the proxy received a TCP RST or an ICMP message
11541 in return). Under some circumstances, it can also be the network
11542 stack telling the proxy that the server is unreachable (eg: no route,
11543 or no ARP response on local network). When this happens in HTTP mode,
11544 the status code is likely a 502 or 503 here.
11545
11546 sC The "timeout connect" stroke before a connection to the server could
11547 complete. When this happens in HTTP mode, the status code is likely a
11548 503 or 504 here.
11549
11550 SD The connection to the server died with an error during the data
11551 transfer. This usually means that haproxy has received an RST from
11552 the server or an ICMP message from an intermediate equipment while
11553 exchanging data with the server. This can be caused by a server crash
11554 or by a network issue on an intermediate equipment.
11555
11556 sD The server did not send nor acknowledge any data for as long as the
11557 "timeout server" setting during the data phase. This is often caused
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011558 by too short timeouts on L4 equipments before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011559 load-balancers, ...), as well as keep-alive sessions maintained
11560 between the client and the server expiring first on haproxy.
11561
11562 SH The server aborted before sending its full HTTP response headers, or
11563 it crashed while processing the request. Since a server aborting at
11564 this moment is very rare, it would be wise to inspect its logs to
11565 control whether it crashed and why. The logged request may indicate a
11566 small set of faulty requests, demonstrating bugs in the application.
11567 Sometimes this might also be caused by an IDS killing the connection
11568 between haproxy and the server.
11569
11570 sH The "timeout server" stroke before the server could return its
11571 response headers. This is the most common anomaly, indicating too
11572 long transactions, probably caused by server or database saturation.
11573 The immediate workaround consists in increasing the "timeout server"
11574 setting, but it is important to keep in mind that the user experience
11575 will suffer from these long response times. The only long term
11576 solution is to fix the application.
11577
11578 sQ The session spent too much time in queue and has been expired. See
11579 the "timeout queue" and "timeout connect" settings to find out how to
11580 fix this if it happens too often. If it often happens massively in
11581 short periods, it may indicate general problems on the affected
11582 servers due to I/O or database congestion, or saturation caused by
11583 external attacks.
11584
11585 PC The proxy refused to establish a connection to the server because the
11586 process' socket limit has been reached while attempting to connect.
Cyril Bontédc4d9032012-04-08 21:57:39 +020011587 The global "maxconn" parameter may be increased in the configuration
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011588 so that it does not happen anymore. This status is very rare and
11589 might happen when the global "ulimit-n" parameter is forced by hand.
11590
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010011591 PD The proxy blocked an incorrectly formatted chunked encoded message in
11592 a request or a response, after the server has emitted its headers. In
11593 most cases, this will indicate an invalid message from the server to
11594 the client.
11595
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011596 PH The proxy blocked the server's response, because it was invalid,
11597 incomplete, dangerous (cache control), or matched a security filter.
11598 In any case, an HTTP 502 error is sent to the client. One possible
11599 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010011600 containing unauthorized characters. It is also possible but quite
11601 rare, that the proxy blocked a chunked-encoding request from the
11602 client due to an invalid syntax, before the server responded. In this
11603 case, an HTTP 400 error is sent to the client and reported in the
11604 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011605
11606 PR The proxy blocked the client's HTTP request, either because of an
11607 invalid HTTP syntax, in which case it returned an HTTP 400 error to
11608 the client, or because a deny filter matched, in which case it
11609 returned an HTTP 403 error.
11610
11611 PT The proxy blocked the client's request and has tarpitted its
11612 connection before returning it a 500 server error. Nothing was sent
11613 to the server. The connection was maintained open for as long as
11614 reported by the "Tw" timer field.
11615
11616 RC A local resource has been exhausted (memory, sockets, source ports)
11617 preventing the connection to the server from establishing. The error
11618 logs will tell precisely what was missing. This is very rare and can
11619 only be solved by proper system tuning.
11620
Willy Tarreau996a92c2010-10-13 19:30:47 +020011621The combination of the two last flags gives a lot of information about how
11622persistence was handled by the client, the server and by haproxy. This is very
11623important to troubleshoot disconnections, when users complain they have to
11624re-authenticate. The commonly encountered flags are :
11625
11626 -- Persistence cookie is not enabled.
11627
11628 NN No cookie was provided by the client, none was inserted in the
11629 response. For instance, this can be in insert mode with "postonly"
11630 set on a GET request.
11631
11632 II A cookie designating an invalid server was provided by the client,
11633 a valid one was inserted in the response. This typically happens when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040011634 a "server" entry is removed from the configuration, since its cookie
Willy Tarreau996a92c2010-10-13 19:30:47 +020011635 value can be presented by a client when no other server knows it.
11636
11637 NI No cookie was provided by the client, one was inserted in the
11638 response. This typically happens for first requests from every user
11639 in "insert" mode, which makes it an easy way to count real users.
11640
11641 VN A cookie was provided by the client, none was inserted in the
11642 response. This happens for most responses for which the client has
11643 already got a cookie.
11644
11645 VU A cookie was provided by the client, with a last visit date which is
11646 not completely up-to-date, so an updated cookie was provided in
11647 response. This can also happen if there was no date at all, or if
11648 there was a date but the "maxidle" parameter was not set, so that the
11649 cookie can be switched to unlimited time.
11650
11651 EI A cookie was provided by the client, with a last visit date which is
11652 too old for the "maxidle" parameter, so the cookie was ignored and a
11653 new cookie was inserted in the response.
11654
11655 OI A cookie was provided by the client, with a first visit date which is
11656 too old for the "maxlife" parameter, so the cookie was ignored and a
11657 new cookie was inserted in the response.
11658
11659 DI The server designated by the cookie was down, a new server was
11660 selected and a new cookie was emitted in the response.
11661
11662 VI The server designated by the cookie was not marked dead but could not
11663 be reached. A redispatch happened and selected another one, which was
11664 then advertised in the response.
11665
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011666
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200116678.6. Non-printable characters
11668-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011669
11670In order not to cause trouble to log analysis tools or terminals during log
11671consulting, non-printable characters are not sent as-is into log files, but are
11672converted to the two-digits hexadecimal representation of their ASCII code,
11673prefixed by the character '#'. The only characters that can be logged without
11674being escaped are comprised between 32 and 126 (inclusive). Obviously, the
11675escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
11676is the same for the character '"' which becomes "#22", as well as '{', '|' and
11677'}' when logging headers.
11678
11679Note that the space character (' ') is not encoded in headers, which can cause
11680issues for tools relying on space count to locate fields. A typical header
11681containing spaces is "User-Agent".
11682
11683Last, it has been observed that some syslog daemons such as syslog-ng escape
11684the quote ('"') with a backslash ('\'). The reverse operation can safely be
11685performed since no quote may appear anywhere else in the logs.
11686
11687
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200116888.7. Capturing HTTP cookies
11689---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011690
11691Cookie capture simplifies the tracking a complete user session. This can be
11692achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011693section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011694cookie will simultaneously be checked in the request ("Cookie:" header) and in
11695the response ("Set-Cookie:" header). The respective values will be reported in
11696the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011697locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011698not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
11699user switches to a new session for example, because the server will reassign it
11700a new cookie. It is also possible to detect if a server unexpectedly sets a
11701wrong cookie to a client, leading to session crossing.
11702
11703 Examples :
11704 # capture the first cookie whose name starts with "ASPSESSION"
11705 capture cookie ASPSESSION len 32
11706
11707 # capture the first cookie whose name is exactly "vgnvisitor"
11708 capture cookie vgnvisitor= len 32
11709
11710
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200117118.8. Capturing HTTP headers
11712---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011713
11714Header captures are useful to track unique request identifiers set by an upper
11715proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
11716the response, one can search for information about the response length, how the
11717server asked the cache to behave, or an object location during a redirection.
11718
11719Header captures are performed using the "capture request header" and "capture
11720response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011721section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011722
11723It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011724time. Non-existent headers are logged as empty strings, and if one header
11725appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011726are grouped within braces '{' and '}' in the same order as they were declared,
11727and delimited with a vertical bar '|' without any space. Response headers
11728follow the same representation, but are displayed after a space following the
11729request headers block. These blocks are displayed just before the HTTP request
11730in the logs.
11731
11732 Example :
11733 # This instance chains to the outgoing proxy
11734 listen proxy-out
11735 mode http
11736 option httplog
11737 option logasap
11738 log global
11739 server cache1 192.168.1.1:3128
11740
11741 # log the name of the virtual server
11742 capture request header Host len 20
11743
11744 # log the amount of data uploaded during a POST
11745 capture request header Content-Length len 10
11746
11747 # log the beginning of the referrer
11748 capture request header Referer len 20
11749
11750 # server name (useful for outgoing proxies only)
11751 capture response header Server len 20
11752
11753 # logging the content-length is useful with "option logasap"
11754 capture response header Content-Length len 10
11755
11756 # log the expected cache behaviour on the response
11757 capture response header Cache-Control len 8
11758
11759 # the Via header will report the next proxy's name
11760 capture response header Via len 20
11761
11762 # log the URL location during a redirection
11763 capture response header Location len 20
11764
11765 >>> Aug 9 20:26:09 localhost \
11766 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
11767 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
11768 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
11769 "GET http://fr.adserver.yahoo.com/"
11770
11771 >>> Aug 9 20:30:46 localhost \
11772 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
11773 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
11774 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010011775 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011776
11777 >>> Aug 9 20:30:46 localhost \
11778 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
11779 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
11780 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
11781 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010011782 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011783
11784
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200117858.9. Examples of logs
11786---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011787
11788These are real-world examples of logs accompanied with an explanation. Some of
11789them have been made up by hand. The syslog part has been removed for better
11790reading. Their sole purpose is to explain how to decipher them.
11791
11792 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
11793 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
11794 "HEAD / HTTP/1.0"
11795
11796 => long request (6.5s) entered by hand through 'telnet'. The server replied
11797 in 147 ms, and the session ended normally ('----')
11798
11799 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
11800 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
11801 0/9 "HEAD / HTTP/1.0"
11802
11803 => Idem, but the request was queued in the global queue behind 9 other
11804 requests, and waited there for 1230 ms.
11805
11806 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
11807 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
11808 "GET /image.iso HTTP/1.0"
11809
11810 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011811 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011812 14 ms, 243 bytes of headers were sent to the client, and total time from
11813 accept to first data byte is 30 ms.
11814
11815 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
11816 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
11817 "GET /cgi-bin/bug.cgi? HTTP/1.0"
11818
11819 => the proxy blocked a server response either because of an "rspdeny" or
11820 "rspideny" filter, or because the response was improperly formatted and
Willy Tarreau3c92c5f2011-08-28 09:45:47 +020011821 not HTTP-compliant, or because it blocked sensitive information which
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011822 risked being cached. In this case, the response is replaced with a "502
11823 bad gateway". The flags ("PH--") tell us that it was haproxy who decided
11824 to return the 502 and not the server.
11825
11826 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +010011827 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 +010011828
11829 => the client never completed its request and aborted itself ("C---") after
11830 8.5s, while the proxy was waiting for the request headers ("-R--").
11831 Nothing was sent to any server.
11832
11833 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
11834 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
11835
11836 => The client never completed its request, which was aborted by the
11837 time-out ("c---") after 50s, while the proxy was waiting for the request
11838 headers ("-R--"). Nothing was sent to any server, but the proxy could
11839 send a 408 return code to the client.
11840
11841 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
11842 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
11843
11844 => This log was produced with "option tcplog". The client timed out after
11845 5 seconds ("c----").
11846
11847 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
11848 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +010011849 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011850
11851 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011852 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +010011853 (config says 'retries 3'), and no redispatch (otherwise we would have
11854 seen "/+3"). Status code 503 was returned to the client. There were 115
11855 connections on this server, 202 connections on this proxy, and 205 on
11856 the global process. It is possible that the server refused the
11857 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +010011858
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011859
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200118609. Statistics and monitoring
11861----------------------------
11862
11863It is possible to query HAProxy about its status. The most commonly used
11864mechanism is the HTTP statistics page. This page also exposes an alternative
11865CSV output format for monitoring tools. The same format is provided on the
11866Unix socket.
11867
11868
118699.1. CSV format
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011870---------------
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010011871
Willy Tarreau7f062c42009-03-05 18:43:00 +010011872The statistics may be consulted either from the unix socket or from the HTTP
11873page. Both means provide a CSV format whose fields follow.
11874
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010011875 0. pxname: proxy name
11876 1. svname: service name (FRONTEND for frontend, BACKEND for backend, any name
11877 for server)
11878 2. qcur: current queued requests
11879 3. qmax: max queued requests
11880 4. scur: current sessions
11881 5. smax: max sessions
11882 6. slim: sessions limit
11883 7. stot: total sessions
11884 8. bin: bytes in
11885 9. bout: bytes out
11886 10. dreq: denied requests
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010011887 11. dresp: denied responses
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010011888 12. ereq: request errors
11889 13. econ: connection errors
Willy Tarreauae526782010-03-04 20:34:23 +010011890 14. eresp: response errors (among which srv_abrt)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010011891 15. wretr: retries (warning)
11892 16. wredis: redispatches (warning)
Cyril Bonté0dae5852010-02-03 00:26:28 +010011893 17. status: status (UP/DOWN/NOLB/MAINT/MAINT(via)...)
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +010011894 18. weight: server weight (server), total weight (backend)
11895 19. act: server is active (server), number of active servers (backend)
11896 20. bck: server is backup (server), number of backup servers (backend)
11897 21. chkfail: number of failed checks
11898 22. chkdown: number of UP->DOWN transitions
11899 23. lastchg: last status change (in seconds)
11900 24. downtime: total downtime (in seconds)
11901 25. qlimit: queue limit
11902 26. pid: process id (0 for first instance, 1 for second, ...)
11903 27. iid: unique proxy id
11904 28. sid: service id (unique inside a proxy)
11905 29. throttle: warm up status
11906 30. lbtot: total number of times a server was selected
11907 31. tracked: id of proxy/server if tracking is enabled
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +020011908 32. type (0=frontend, 1=backend, 2=server, 3=socket)
Krzysztof Piotr Oledzkidb57c6b2009-08-31 21:23:27 +020011909 33. rate: number of sessions per second over last elapsed second
11910 34. rate_lim: limit on new sessions per second
11911 35. rate_max: max number of new sessions per second
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +020011912 36. check_status: status of last health check, one of:
Cyril Bontéf0c60612010-02-06 14:44:47 +010011913 UNK -> unknown
11914 INI -> initializing
11915 SOCKERR -> socket error
11916 L4OK -> check passed on layer 4, no upper layers testing enabled
11917 L4TMOUT -> layer 1-4 timeout
11918 L4CON -> layer 1-4 connection problem, for example
11919 "Connection refused" (tcp rst) or "No route to host" (icmp)
11920 L6OK -> check passed on layer 6
11921 L6TOUT -> layer 6 (SSL) timeout
11922 L6RSP -> layer 6 invalid response - protocol error
11923 L7OK -> check passed on layer 7
11924 L7OKC -> check conditionally passed on layer 7, for example 404 with
11925 disable-on-404
11926 L7TOUT -> layer 7 (HTTP/SMTP) timeout
11927 L7RSP -> layer 7 invalid response - protocol error
11928 L7STS -> layer 7 response error, for example HTTP 5xx
Krzysztof Piotr Oledzki09605412009-09-23 22:09:24 +020011929 37. check_code: layer5-7 code, if available
11930 38. check_duration: time in ms took to finish last health check
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011931 39. hrsp_1xx: http responses with 1xx code
11932 40. hrsp_2xx: http responses with 2xx code
11933 41. hrsp_3xx: http responses with 3xx code
11934 42. hrsp_4xx: http responses with 4xx code
11935 43. hrsp_5xx: http responses with 5xx code
11936 44. hrsp_other: http responses with other codes (protocol error)
Willy Tarreaud63335a2010-02-26 12:56:52 +010011937 45. hanafail: failed health checks details
11938 46. req_rate: HTTP requests per second over last elapsed second
11939 47. req_rate_max: max number of HTTP requests per second observed
11940 48. req_tot: total number of HTTP requests received
Willy Tarreauae526782010-03-04 20:34:23 +010011941 49. cli_abrt: number of data transfers aborted by the client
11942 50. srv_abrt: number of data transfers aborted by the server (inc. in eresp)
Willy Tarreau55058a72012-11-21 08:27:21 +010011943 51. comp_in: number of HTTP response bytes fed to the compressor
11944 52. comp_out: number of HTTP response bytes emitted by the compressor
11945 53. comp_byp: number of bytes that bypassed the HTTP compressor (CPU/BW limit)
Willy Tarreau11d4ec82012-11-26 00:49:03 +010011946 54. comp_rsp: number of HTTP responses that were compressed
Willy Tarreau844e3c52008-01-11 16:28:18 +010011947
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011948
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200119499.2. Unix Socket commands
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011950-------------------------
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010011951
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011952The following commands are supported on the UNIX stats socket ; all of them
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011953must be terminated by a line feed. The socket supports pipelining, so that it
11954is possible to chain multiple commands at once provided they are delimited by
11955a semi-colon or a line feed, although the former is more reliable as it has no
11956risk of being truncated over the network. The responses themselves will each be
11957followed by an empty line, so it will be easy for an external script to match a
11958given response with a given request. By default one command line is processed
11959then the connection closes, but there is an interactive allowing multiple lines
11960to be issued one at a time.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011961
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020011962It is important to understand that when multiple haproxy processes are started
11963on the same sockets, any process may pick up the request and will output its
11964own stats.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010011965
Willy Tarreaud63335a2010-02-26 12:56:52 +010011966clear counters
11967 Clear the max values of the statistics counters in each proxy (frontend &
11968 backend) and in each server. The cumulated counters are not affected. This
11969 can be used to get clean counters after an incident, without having to
11970 restart nor to clear traffic counters. This command is restricted and can
11971 only be issued on sockets configured for levels "operator" or "admin".
11972
11973clear counters all
11974 Clear all statistics counters in each proxy (frontend & backend) and in each
11975 server. This has the same effect as restarting. This command is restricted
11976 and can only be issued on sockets configured for level "admin".
11977
Simon Hormanc88b8872011-06-15 15:18:49 +090011978clear table <table> [ data.<type> <operator> <value> ] | [ key <key> ]
11979 Remove entries from the stick-table <table>.
11980
11981 This is typically used to unblock some users complaining they have been
11982 abusively denied access to a service, but this can also be used to clear some
11983 stickiness entries matching a server that is going to be replaced (see "show
11984 table" below for details). Note that sometimes, removal of an entry will be
11985 refused because it is currently tracked by a session. Retrying a few seconds
11986 later after the session ends is usual enough.
11987
11988 In the case where no options arguments are given all entries will be removed.
11989
11990 When the "data." form is used entries matching a filter applied using the
11991 stored data (see "stick-table" in section 4.2) are removed. A stored data
11992 type must be specified in <type>, and this data type must be stored in the
11993 table otherwise an error is reported. The data is compared according to
11994 <operator> with the 64-bit integer <value>. Operators are the same as with
11995 the ACLs :
11996
11997 - eq : match entries whose data is equal to this value
11998 - ne : match entries whose data is not equal to this value
11999 - le : match entries whose data is less than or equal to this value
12000 - ge : match entries whose data is greater than or equal to this value
12001 - lt : match entries whose data is less than this value
12002 - gt : match entries whose data is greater than this value
12003
12004 When the key form is used the entry <key> is removed. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +090012005 same type as the table, which currently is limited to IPv4, IPv6, integer and
12006 string.
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012007
12008 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020012009 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +020012010 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020012011 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
12012 bytes_out_rate(60000)=187
12013 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
12014 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012015
12016 $ echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1
12017
12018 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Emeric Brun7c6b82e2010-09-24 16:34:28 +020012019 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau62a36c42010-08-17 15:53:10 +020012020 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
12021 bytes_out_rate(60000)=191
Simon Hormanc88b8872011-06-15 15:18:49 +090012022 $ echo "clear table http_proxy data.gpc0 eq 1" | socat stdio /tmp/sock1
12023 $ echo "show table http_proxy" | socat stdio /tmp/sock1
12024 >>> # table: http_proxy, type: ip, size:204800, used:1
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012025
Willy Tarreau532a4502011-09-07 22:37:44 +020012026disable frontend <frontend>
12027 Mark the frontend as temporarily stopped. This corresponds to the mode which
12028 is used during a soft restart : the frontend releases the port but can be
12029 enabled again if needed. This should be used with care as some non-Linux OSes
12030 are unable to enable it back. This is intended to be used in environments
12031 where stopping a proxy is not even imaginable but a misconfigured proxy must
12032 be fixed. That way it's possible to release the port and bind it into another
12033 process to restore operations. The frontend will appear with status "STOP"
12034 on the stats page.
12035
12036 The frontend may be specified either by its name or by its numeric ID,
12037 prefixed with a sharp ('#').
12038
12039 This command is restricted and can only be issued on sockets configured for
12040 level "admin".
12041
Willy Tarreaud63335a2010-02-26 12:56:52 +010012042disable server <backend>/<server>
12043 Mark the server DOWN for maintenance. In this mode, no more checks will be
12044 performed on the server until it leaves maintenance.
12045 If the server is tracked by other servers, those servers will be set to DOWN
12046 during the maintenance.
12047
12048 In the statistics page, a server DOWN for maintenance will appear with a
12049 "MAINT" status, its tracking servers with the "MAINT(via)" one.
12050
12051 Both the backend and the server may be specified either by their name or by
Willy Tarreauf5f31922011-08-02 11:32:07 +020012052 their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010012053
12054 This command is restricted and can only be issued on sockets configured for
12055 level "admin".
12056
Willy Tarreau532a4502011-09-07 22:37:44 +020012057enable frontend <frontend>
12058 Resume a frontend which was temporarily stopped. It is possible that some of
12059 the listening ports won't be able to bind anymore (eg: if another process
12060 took them since the 'disable frontend' operation). If this happens, an error
12061 is displayed. Some operating systems might not be able to resume a frontend
12062 which was disabled.
12063
12064 The frontend may be specified either by its name or by its numeric ID,
12065 prefixed with a sharp ('#').
12066
12067 This command is restricted and can only be issued on sockets configured for
12068 level "admin".
12069
Willy Tarreaud63335a2010-02-26 12:56:52 +010012070enable server <backend>/<server>
12071 If the server was previously marked as DOWN for maintenance, this marks the
12072 server UP and checks are re-enabled.
12073
12074 Both the backend and the server may be specified either by their name or by
Willy Tarreauf5f31922011-08-02 11:32:07 +020012075 their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010012076
12077 This command is restricted and can only be issued on sockets configured for
12078 level "admin".
12079
12080get weight <backend>/<server>
12081 Report the current weight and the initial weight of server <server> in
12082 backend <backend> or an error if either doesn't exist. The initial weight is
12083 the one that appears in the configuration file. Both are normally equal
12084 unless the current weight has been changed. Both the backend and the server
12085 may be specified either by their name or by their numeric ID, prefixed with a
Willy Tarreauf5f31922011-08-02 11:32:07 +020012086 sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010012087
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012088help
12089 Print the list of known keywords and their basic usage. The same help screen
12090 is also displayed for unknown commands.
Willy Tarreau3dfe6cd2008-12-07 22:29:48 +010012091
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012092prompt
12093 Toggle the prompt at the beginning of the line and enter or leave interactive
12094 mode. In interactive mode, the connection is not closed after a command
12095 completes. Instead, the prompt will appear again, indicating the user that
12096 the interpreter is waiting for a new command. The prompt consists in a right
12097 angle bracket followed by a space "> ". This mode is particularly convenient
12098 when one wants to periodically check information such as stats or errors.
12099 It is also a good idea to enter interactive mode before issuing a "help"
12100 command.
12101
12102quit
12103 Close the connection when in interactive mode.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010012104
Willy Tarreau2a0f4d22011-08-02 11:49:05 +020012105set maxconn frontend <frontend> <value>
Willy Tarreau3c7a79d2012-09-26 21:07:15 +020012106 Dynamically change the specified frontend's maxconn setting. Any positive
12107 value is allowed including zero, but setting values larger than the global
12108 maxconn does not make much sense. If the limit is increased and connections
12109 were pending, they will immediately be accepted. If it is lowered to a value
12110 below the current number of connections, new connections acceptation will be
Willy Tarreau2a0f4d22011-08-02 11:49:05 +020012111 delayed until the threshold is reached. The frontend might be specified by
12112 either its name or its numeric ID prefixed with a sharp ('#').
12113
Willy Tarreau91886b62011-09-07 14:38:31 +020012114set maxconn global <maxconn>
12115 Dynamically change the global maxconn setting within the range defined by the
12116 initial global maxconn setting. If it is increased and connections were
12117 pending, they will immediately be accepted. If it is lowered to a value below
12118 the current number of connections, new connections acceptation will be
12119 delayed until the threshold is reached. A value of zero restores the initial
12120 setting.
12121
Willy Tarreauf5b22872011-09-07 16:13:44 +020012122set rate-limit connections global <value>
12123 Change the process-wide connection rate limit, which is set by the global
12124 'maxconnrate' setting. A value of zero disables the limitation. This limit
12125 applies to all frontends and the change has an immediate effect. The value
12126 is passed in number of connections per second.
12127
William Lallemandd85f9172012-11-09 17:05:39 +010012128set rate-limit http-compression global <value>
12129 Change the maximum input compression rate, which is set by the global
12130 'maxcomprate' setting. A value of zero disables the limitation. The value is
William Lallemand096f5542012-11-19 17:26:05 +010012131 passed in number of kilobytes per second. The value is available in the "show
12132 info" on the line "CompressBpsRateLim" in bytes.
William Lallemandd85f9172012-11-09 17:05:39 +010012133
Willy Tarreau654694e2012-06-07 01:03:16 +020012134set table <table> key <key> data.<data_type> <value>
12135 Create or update a stick-table entry in the table. If the key is not present,
12136 an entry is inserted. See stick-table in section 4.2 to find all possible
12137 values for <data_type>. The most likely use consists in dynamically entering
12138 entries for source IP addresses, with a flag in gpc0 to dynamically block an
12139 IP address or affect its quality of service.
12140
Willy Tarreaud63335a2010-02-26 12:56:52 +010012141set timeout cli <delay>
12142 Change the CLI interface timeout for current connection. This can be useful
12143 during long debugging sessions where the user needs to constantly inspect
12144 some indicators without being disconnected. The delay is passed in seconds.
12145
12146set weight <backend>/<server> <weight>[%]
12147 Change a server's weight to the value passed in argument. If the value ends
12148 with the '%' sign, then the new weight will be relative to the initially
Simon Horman58b5d292013-02-12 10:45:52 +090012149 configured weight. Absolute weights are permitted between 0 and 256.
12150 Relative weights must be positive with the resulting absolute weight is
12151 capped at 256. Servers which are part of a farm running a static
12152 load-balancing algorithm have stricter limitations because the weight
12153 cannot change once set. Thus for these servers, the only accepted values
12154 are 0 and 100% (or 0 and the initial weight). Changes take effect
12155 immediately, though certain LB algorithms require a certain amount of
12156 requests to consider changes. A typical usage of this command is to
12157 disable a server during an update by setting its weight to zero, then to
12158 enable it again after the update by setting it back to 100%. This command
12159 is restricted and can only be issued on sockets configured for level
12160 "admin". Both the backend and the server may be specified either by their
12161 name or by their numeric ID, prefixed with a sharp ('#').
Willy Tarreaud63335a2010-02-26 12:56:52 +010012162
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010012163show errors [<iid>]
12164 Dump last known request and response errors collected by frontends and
12165 backends. If <iid> is specified, the limit the dump to errors concerning
Willy Tarreau6162db22009-10-10 17:13:00 +020012166 either frontend or backend whose ID is <iid>. This command is restricted
12167 and can only be issued on sockets configured for levels "operator" or
12168 "admin".
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010012169
12170 The errors which may be collected are the last request and response errors
12171 caused by protocol violations, often due to invalid characters in header
12172 names. The report precisely indicates what exact character violated the
12173 protocol. Other important information such as the exact date the error was
12174 detected, frontend and backend names, the server name (when known), the
12175 internal session ID and the source address which has initiated the session
12176 are reported too.
12177
12178 All characters are returned, and non-printable characters are encoded. The
12179 most common ones (\t = 9, \n = 10, \r = 13 and \e = 27) are encoded as one
12180 letter following a backslash. The backslash itself is encoded as '\\' to
12181 avoid confusion. Other non-printable characters are encoded '\xNN' where
12182 NN is the two-digits hexadecimal representation of the character's ASCII
12183 code.
12184
12185 Lines are prefixed with the position of their first character, starting at 0
12186 for the beginning of the buffer. At most one input line is printed per line,
12187 and large lines will be broken into multiple consecutive output lines so that
12188 the output never goes beyond 79 characters wide. It is easy to detect if a
12189 line was broken, because it will not end with '\n' and the next line's offset
12190 will be followed by a '+' sign, indicating it is a continuation of previous
12191 line.
12192
12193 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020012194 $ echo "show errors" | socat stdio /tmp/sock1
12195 >>> [04/Mar/2009:15:46:56.081] backend http-in (#2) : invalid response
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010012196 src 127.0.0.1, session #54, frontend fe-eth0 (#1), server s2 (#1)
12197 response length 213 bytes, error at position 23:
12198
12199 00000 HTTP/1.0 200 OK\r\n
12200 00017 header/bizarre:blah\r\n
12201 00038 Location: blah\r\n
12202 00054 Long-line: this is a very long line which should b
12203 00104+ e broken into multiple lines on the output buffer,
12204 00154+ otherwise it would be too large to print in a ter
12205 00204+ minal\r\n
12206 00211 \r\n
12207
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012208 In the example above, we see that the backend "http-in" which has internal
Willy Tarreaue0c8a1a2009-03-04 16:33:10 +010012209 ID 2 has blocked an invalid response from its server s2 which has internal
12210 ID 1. The request was on session 54 initiated by source 127.0.0.1 and
12211 received by frontend fe-eth0 whose ID is 1. The total response length was
12212 213 bytes when the error was detected, and the error was at byte 23. This
12213 is the slash ('/') in header name "header/bizarre", which is not a valid
12214 HTTP character for a header name.
Krzysztof Piotr Oledzki2c6962c2008-03-02 02:42:14 +010012215
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012216show info
12217 Dump info about haproxy status on current process.
12218
12219show sess
12220 Dump all known sessions. Avoid doing this on slow connections as this can
Willy Tarreau6162db22009-10-10 17:13:00 +020012221 be huge. This command is restricted and can only be issued on sockets
12222 configured for levels "operator" or "admin".
12223
Willy Tarreau66dc20a2010-03-05 17:53:32 +010012224show sess <id>
12225 Display a lot of internal information about the specified session identifier.
12226 This identifier is the first field at the beginning of the lines in the dumps
12227 of "show sess" (it corresponds to the session pointer). Those information are
12228 useless to most users but may be used by haproxy developers to troubleshoot a
12229 complex bug. The output format is intentionally not documented so that it can
Willy Tarreau76153662012-11-26 01:16:39 +010012230 freely evolve depending on demands. The special id "all" dumps the states of
12231 all sessions, which can be avoided as much as possible as it is highly CPU
12232 intensive and can take a lot of time.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012233
12234show stat [<iid> <type> <sid>]
12235 Dump statistics in the CSV format. By passing <id>, <type> and <sid>, it is
12236 possible to dump only selected items :
12237 - <iid> is a proxy ID, -1 to dump everything
12238 - <type> selects the type of dumpable objects : 1 for frontends, 2 for
12239 backends, 4 for servers, -1 for everything. These values can be ORed,
12240 for example:
12241 1 + 2 = 3 -> frontend + backend.
12242 1 + 2 + 4 = 7 -> frontend + backend + server.
12243 - <sid> is a server ID, -1 to dump everything from the selected proxy.
12244
12245 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020012246 $ echo "show info;show stat" | socat stdio unix-connect:/tmp/sock1
12247 >>> Name: HAProxy
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012248 Version: 1.4-dev2-49
12249 Release_date: 2009/09/23
12250 Nbproc: 1
12251 Process_num: 1
12252 (...)
12253
12254 # pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,dreq, (...)
12255 stats,FRONTEND,,,0,0,1000,0,0,0,0,0,0,,,,,OPEN,,,,,,,,,1,1,0, (...)
12256 stats,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,0,0,0,,0,250,(...)
12257 (...)
12258 www1,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,1,1,0,,0,250, (...)
12259
12260 $
12261
12262 Here, two commands have been issued at once. That way it's easy to find
12263 which process the stats apply to in multi-process mode. Notice the empty
12264 line after the information output which marks the end of the first block.
12265 A similar empty line appears at the end of the second block (stats) so that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012266 the reader knows the output has not been truncated.
Willy Tarreau9a42c0d2009-09-22 19:31:03 +020012267
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012268show table
12269 Dump general information on all known stick-tables. Their name is returned
12270 (the name of the proxy which holds them), their type (currently zero, always
12271 IP), their size in maximum possible number of entries, and the number of
12272 entries currently in use.
12273
12274 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020012275 $ echo "show table" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090012276 >>> # table: front_pub, type: ip, size:204800, used:171454
12277 >>> # table: back_rdp, type: ip, size:204800, used:0
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012278
Simon Horman17bce342011-06-15 15:18:47 +090012279show table <name> [ data.<type> <operator> <value> ] | [ key <key> ]
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012280 Dump contents of stick-table <name>. In this mode, a first line of generic
12281 information about the table is reported as with "show table", then all
12282 entries are dumped. Since this can be quite heavy, it is possible to specify
Simon Horman17bce342011-06-15 15:18:47 +090012283 a filter in order to specify what entries to display.
12284
12285 When the "data." form is used the filter applies to the stored data (see
12286 "stick-table" in section 4.2). A stored data type must be specified
12287 in <type>, and this data type must be stored in the table otherwise an
12288 error is reported. The data is compared according to <operator> with the
12289 64-bit integer <value>. Operators are the same as with the ACLs :
12290
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012291 - eq : match entries whose data is equal to this value
12292 - ne : match entries whose data is not equal to this value
12293 - le : match entries whose data is less than or equal to this value
12294 - ge : match entries whose data is greater than or equal to this value
12295 - lt : match entries whose data is less than this value
12296 - gt : match entries whose data is greater than this value
12297
Simon Hormanc88b8872011-06-15 15:18:49 +090012298
12299 When the key form is used the entry <key> is shown. The key must be of the
Simon Horman619e3cc2011-06-15 15:18:52 +090012300 same type as the table, which currently is limited to IPv4, IPv6, integer,
12301 and string.
Simon Horman17bce342011-06-15 15:18:47 +090012302
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012303 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020012304 $ echo "show table http_proxy" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090012305 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020012306 >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
12307 bytes_out_rate(60000)=187
12308 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
12309 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012310
Willy Tarreau62a36c42010-08-17 15:53:10 +020012311 $ echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090012312 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020012313 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
12314 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012315
Willy Tarreau62a36c42010-08-17 15:53:10 +020012316 $ echo "show table http_proxy data.conn_rate gt 5" | \
12317 socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090012318 >>> # table: http_proxy, type: ip, size:204800, used:2
Willy Tarreau62a36c42010-08-17 15:53:10 +020012319 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
12320 bytes_out_rate(60000)=191
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012321
Simon Horman17bce342011-06-15 15:18:47 +090012322 $ echo "show table http_proxy key 127.0.0.2" | \
12323 socat stdio /tmp/sock1
Simon Horman64b28d02011-08-13 08:03:50 +090012324 >>> # table: http_proxy, type: ip, size:204800, used:2
Simon Horman17bce342011-06-15 15:18:47 +090012325 >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
12326 bytes_out_rate(60000)=191
12327
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012328 When the data criterion applies to a dynamic value dependent on time such as
12329 a bytes rate, the value is dynamically computed during the evaluation of the
12330 entry in order to decide whether it has to be dumped or not. This means that
12331 such a filter could match for some time then not match anymore because as
12332 time goes, the average event rate drops.
12333
12334 It is possible to use this to extract lists of IP addresses abusing the
12335 service, in order to monitor them or even blacklist them in a firewall.
12336 Example :
Willy Tarreau62a36c42010-08-17 15:53:10 +020012337 $ echo "show table http_proxy data.gpc0 gt 0" \
12338 | socat stdio /tmp/sock1 \
Willy Tarreau88bc4ec2010-08-01 07:58:48 +020012339 | fgrep 'key=' | cut -d' ' -f2 | cut -d= -f2 > abusers-ip.txt
12340 ( or | awk '/key/{ print a[split($2,a,"=")]; }' )
Krzysztof Piotr Oledzki719e7262009-10-04 15:02:46 +020012341
Willy Tarreau532a4502011-09-07 22:37:44 +020012342shutdown frontend <frontend>
12343 Completely delete the specified frontend. All the ports it was bound to will
12344 be released. It will not be possible to enable the frontend anymore after
12345 this operation. This is intended to be used in environments where stopping a
12346 proxy is not even imaginable but a misconfigured proxy must be fixed. That
12347 way it's possible to release the port and bind it into another process to
12348 restore operations. The frontend will not appear at all on the stats page
12349 once it is terminated.
12350
12351 The frontend may be specified either by its name or by its numeric ID,
12352 prefixed with a sharp ('#').
12353
12354 This command is restricted and can only be issued on sockets configured for
12355 level "admin".
12356
Willy Tarreaua295edc2011-09-07 23:21:03 +020012357shutdown session <id>
12358 Immediately terminate the session matching the specified session identifier.
12359 This identifier is the first field at the beginning of the lines in the dumps
12360 of "show sess" (it corresponds to the session pointer). This can be used to
12361 terminate a long-running session without waiting for a timeout or when an
12362 endless transfer is ongoing. Such terminated sessions are reported with a 'K'
12363 flag in the logs.
12364
Willy Tarreau52b2d222011-09-07 23:48:48 +020012365shutdown sessions <backend>/<server>
12366 Immediately terminate all the sessions attached to the specified server. This
12367 can be used to terminate long-running sessions after a server is put into
12368 maintenance mode, for instance. Such terminated sessions are reported with a
12369 'K' flag in the logs.
12370
Willy Tarreau0ba27502007-12-24 16:55:16 +010012371/*
12372 * Local variables:
12373 * fill-column: 79
12374 * End:
12375 */